Tài liệu API

Lấy khóa API

Đăng nhập, vào Tài khoản của tôi và mở tab API. Khóa của bạn hiển thị ở đó, cùng với nút Tạo lại. Tạo lại khóa sẽ vô hiệu hóa khóa cũ ngay lập tức, vì vậy hãy cập nhật mọi nơi đang dùng khóa trước khi bấm.

Tab đó còn có một khóa chỉ tải lên thứ hai, độc lập - xem mẹo bên dưới và Plugin diễn đàn để biết khi nào nên dùng khóa này.

Xác thực

Hãy gửi khóa của bạn qua header - cách này được ưu tiên, vì query string thường bị ghi vào log truy cập, log proxy và header Referer:

X-API-Key: YOUR_API_KEY

Tham số query ?key= cũng dùng được, được giữ lại để tương thích với các tích hợp cũ và những lệnh curl chạy nhanh một lần. Nếu có cả hai, header sẽ được ưu tiên.

?key=YOUR_API_KEY

Endpoint

Tải lên, liệt kê và xóa dùng chung cơ chế xác thực và giới hạn tốc độ; file lớn có thể được gửi theo từng phần trước.

POST /api - Tải lên một file

Tải lên một file cho tài khoản đã xác thực.

Định dạng được chấp nhận: ảnh JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC hoặc HEIF; video MP4, WEBM hoặc AVI (danh sách chính xác có thể mở rộng theo thời gian). HEIC/HEIF và TIFF được lưu thành WebP, video không phải MP4/WebM được chuyển sang MP4, và ảnh JPEG/PNG lớn hơn được chuyển sang WebP ngay sau khi tải lên nếu việc đó giúp file nhỏ đi đáng kể. Dung lượng tối đa: 200MB; file quá lớn hoặc không đọc được sẽ bị từ chối với lỗi 422.

Phản hồi - 200 OK:

{
  "type": "success",
  "msg": "success",
  "data": {
    "id": "aB3xY9qRz1",
    "type": "image",
    "path": "https://i.yourimageshare.com/aB3xY9qRz1.png",
    "src": "https://yourimageshare.com/ib/aB3xY9qRz1.png",
    "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
    "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
    "width": 1920,
    "height": 1080,
    "size": 482113,
    "locked": false,
    "visibility": "unlisted",
    "title": null,
    "description": null,
    "expires_at": null,
    "duplicate": false,
    "delete_url": "https://yourimageshare.com/delete#iV3x...k9"
  }
}

POST /api/chunk - File lớn

Một request chỉ chứa được tối đa 100MB. Với file lớn hơn (tới 200MB), hoặc để giữ mỗi request nhỏ khi kết nối chậm, hãy gửi file theo từng phần tối đa 5MB, rồi kết thúc bằng POST /api:

1. Chọn một upload id: 32 ký tự hex ngẫu nhiên.
2. Với mỗi phần, gửi POST /api/chunk (multipart/form-data) với upload_id, index (bắt đầu từ 0), total (số phần) và các byte trong chunk. Phản hồi là {"type": "success", "chunk_size": 5242880}.
3. Gửi POST /api với upload_id và filename thay cho uploads, cùng các trường tải lên khác nếu có. Phản hồi là phản hồi tải lên thông thường.

Các phần của một lần tải lên chưa hoàn tất sẽ bị xóa sau 2 giờ. Chỉ POST /api cuối cùng được tính vào giới hạn tải lên.

GET /api/{id} và PATCH /api/{id} - Một file tải lên

GET trả về một file tải lên của bạn với các trường giống như danh sách bên dưới. PATCH thay đổi visibility, title hoặc description của file (qua trường form hoặc JSON; tiêu đề hoặc mô tả để trống sẽ xóa nội dung đó) và trả về file đã cập nhật. Cả hai đều cần khóa API đầy đủ; trả về 404 nếu tài khoản của bạn không có file đó.

curl -X PATCH https://yourimageshare.com/api/aB3xY9qRz1 \
  -H "X-API-Key: YOUR_API_KEY" -d visibility=public -d title="Sunset"

POST /api/{id}/replace - Thay file

Đổi file nằm sau một lần tải lên của bạn nhưng giữ nguyên id, trang và mọi link. Mọi định dạng được phép đều dùng được, kể cả định dạng khác (một ảnh có thể trở thành video). Gửi file mới dưới dạng uploads (hoặc upload_id của một file đã gửi theo từng phần bằng POST /api/chunk); keep_original hoạt động như khi tải lên. File mới được kiểm tra và chuyển đổi như một file tải lên mới, và phiên bản trước sẽ bị xóa. Cần khóa API đầy đủ; trả về 404 nếu tài khoản của bạn không có file đó, 409 nếu file được bảo vệ bằng mật khẩu hoặc bị giới hạn lượt xem.

curl -X POST https://yourimageshare.com/api/aB3xY9qRz1/replace \
  -H "X-API-Key: YOUR_API_KEY" -F [email protected]

GET /api - Liệt kê file đã tải lên

Trả về danh sách phân trang các file tải lên của tài khoản đã xác thực (từ mọi nguồn - API, website hoặc trình chỉnh sửa), mới nhất trước, 50 file mỗi trang.

Phản hồi - 200 OK:

{
  "type": "success",
  "data": [
    {
      "id": "aB3xY9qRz1",
      "type": "image",
      "title": null,
      "path": "https://i.yourimageshare.com/aB3xY9qRz1.webp",
      "src": "https://yourimageshare.com/ib/aB3xY9qRz1.webp",
      "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
      "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
      "width": 1920,
      "height": 1080,
      "size": 482113,
      "locked": false,
      "visibility": "unlisted",
      "description": null,
      "expires_at": null,
      "created_at": "2026-07-23T15:43:28+01:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Các trường ở đây có ý nghĩa giống như trong phản hồi tải lên ở trên (với file tải lên được bảo vệ bằng mật khẩu, path và thumb là các link có chữ ký, chỉ tồn tại trong thời gian ngắn). Hiện chưa có endpoint riêng để "lấy một file tải lên", nên danh sách này cũng là cách để tra cứu id của một file sau này.

DELETE /api/{id} - Xóa một file tải lên

Xóa vĩnh viễn một file tải lên của tài khoản đã xác thực. Không thể hoàn tác từ API. {id} là giá trị được trả về dưới dạng id bởi các endpoint tải lên hoặc liệt kê.

Phản hồi - 200 OK:

{ "type": "success", "msg": "Deleted." }

Trả về 404 nếu tài khoản của bạn không có file tải lên nào với id đó (hoặc nó chưa bao giờ là của bạn, hoặc đã bị xóa).

Giới hạn tốc độ

Mỗi khóa API có hạn mức riêng theo phút và theo ngày, cộng thêm một mức trần theo ngày cho mỗi IP, rộng hơn, để phòng trường hợp một IP dùng lần lượt nhiều khóa. Tải lên, liệt kê và xóa dùng chung các giới hạn này.

Các giới hạn này có thể thay đổi. Mọi phản hồi đều có các header giới hạn tốc độ chuẩn:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14

Khi vượt giới hạn, hệ thống trả về 429 kèm header Retry-After cho biết bạn cần chờ bao nhiêu giây.

Lỗi

Mọi phản hồi lỗi đều có cùng một cấu trúc, bất kể endpoint hay nguyên nhân:

{ "type": "error", "errors": "A human-readable description of what went wrong." }

Thư viện client

Các SDK chính thức bao bọc những endpoint ở trên, trả về kết quả có kiểu dữ liệu và báo lỗi API thay vì bạn phải tự xử lý HTTP thô.

JavaScript / TypeScript

Không có dependency, chạy được trên Node.js và trình duyệt. Cũng có trên JSR với tên @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - cùng mã nguồn, được phát hành trực tiếp dưới dạng TypeScript.

npm install yourimageshare

Python

Một dependency (requests), Python 3.8+.

pip install yourimageshare

PHP

Không có dependency Composer (dùng extension curl có sẵn của PHP), PHP 7.4+. Mã nguồn trên GitHub.

composer require yourimageshare/yourimageshare-php

Go

Không có dependency (chỉ dùng thư viện chuẩn), Go 1.18+. Xem pkg.go.dev để đọc tài liệu tham chiếu đầy đủ.

go get github.com/yourimageshare/yourimageshare/go

Rust

Hai dependency (ureq cho HTTP blocking - không kéo theo async runtime - cùng serde), Rust 1.70+. Mã nguồn trên GitHub.

cargo add yourimageshare

Ruby

Không có gem dependency (dùng Net::HTTP + json của stdlib), Ruby 2.7+. Mã nguồn trên GitHub.

gem install yourimageshare

.NET

Một dependency (System.Text.Json của chính Microsoft), nhắm tới netstandard2.0 nên chạy được trên cả .NET Framework lẫn .NET hiện đại. Mã nguồn trên GitHub. Đã được xây dựng và kiểm chứng với API thật này; sắp phát hành trên NuGet.

dotnet add package YourImageShare

Dart / Flutter

Một dependency (http, gói của chính đội Dart), Dart 2.17+. Mã nguồn trên GitHub. Đã được xây dựng và kiểm chứng với API thật này; sắp phát hành trên pub.dev.

dart pub add yourimageshare

Elixir

Một dependency (Req), Elixir 1.14+. Trả về tuple có gắn nhãn {:ok, result}| {:error, reason} - tương đương trực tiếp với cách xử lý lỗi của API này trong mọi SDK khác - cùng các biến thể có dấu chấm than sẽ raise lỗi. Mã nguồn trên GitHub, tài liệu trên HexDocs.

{:yourimageshare, "~> 1.1"}

MCP Server

Dành cho các AI coding agent (Claude Code, Cursor và các công cụ khác tương thích MCP) - đưa ảnh chụp màn hình vào báo cáo lỗi, mô tả PR hoặc cuộc trao đổi hỗ trợ dưới dạng một link thật thay vì chuỗi base64 hay bước tải lên thủ công. Hoạt động tương tự với Claude Desktop và mọi MCP client khác. Chạy trực tiếp bằng npx, không cần cài đặt:

npx yourimageshare-mcp

Công cụ: upload_image (file cục bộ, nội dung trực tiếp hoặc link, tối đa 200MB, kèm tùy chọn chế độ hiển thị, tiêu đề và tự động xóa), list_uploads, get_upload, update_upload và delete_upload.

Cũng có trong MCP Registry chính thức (với tên io.github.yourimageshare/yourimageshare) và được liệt kê trên Smithery và Glama, nếu MCP client của bạn cài từ một trong các nguồn đó.

Mới làm quen với MCP? Xem cách kết nối Claude và ChatGPT với API này qua MCP để có hướng dẫn thiết lập đầy đủ.

Ví dụ code

curl

# Upload a file
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg"

# Upload from a link (files up to 200MB; one direct upload request stops at 100MB -
# bigger files go in pieces, see Large Files above)
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "url=https://example.com/video.mp4"

# Upload a file that auto-deletes after 1 hour
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "expires_in=3600"

# List uploads
curl "https://yourimageshare.com/api" -H "X-API-Key: YOUR_API_KEY"

# Upload a file without a page of its own (file only) and give it a title
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "visibility=private" \
  -F "title=Sunset"

# Look up one upload, then make it public
curl "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"
curl -X PATCH "https://yourimageshare.com/api/aB3xY9qRz1" \
  -H "X-API-Key: YOUR_API_KEY" -d "visibility=public"

# Delete an upload
curl -X DELETE "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"

JavaScript (fetch)

const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://yourimageshare.com/api';

async function uploadFile(file) {
  const form = new FormData();
  form.append('uploads', file);

  const res = await fetch(BASE, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: form,
  });
  const json = await res.json();
  if (json.type !== 'success') throw new Error(json.errors);
  return json.data;
}

async function listUploads(page = 1) {
  const res = await fetch(`${BASE}?page=${page}`, {
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

async function deleteUpload(id) {
  const res = await fetch(`${BASE}/${id}`, {
    method: 'DELETE',
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

Python (requests)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://yourimageshare.com/api"

HEADERS = {"X-API-Key": API_KEY}

# Upload a file
with open("/path/to/photo.jpg", "rb") as f:
    res = requests.post(BASE, headers=HEADERS, files={"uploads": f})
res.raise_for_status()
upload = res.json()["data"]

# List uploads
res = requests.get(BASE, headers=HEADERS, params={"page": 1})
uploads = res.json()

# Delete an upload
res = requests.delete(f"{BASE}/{upload['id']}", headers=HEADERS)

PHP (curl)

<?php

$apiKey = 'YOUR_API_KEY';
$base = 'https://yourimageshare.com/api';

// Upload a file
$curl = curl_init($base);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    CURLOPT_POSTFIELDS => ['uploads' => new CURLFile('/path/to/photo.jpg')],
    CURLOPT_RETURNTRANSFER => true,
]);
$upload = json_decode(curl_exec($curl), true)['data'];
curl_close($curl);

// List uploads
$curl = curl_init("$base?page=1");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$uploads = json_decode(curl_exec($curl), true);
curl_close($curl);

Go (net/http)

SDK Go chính thức ở trên đã bao bọc sẵn việc này cho bạn - phiên bản thô này dành cho ai không muốn thêm dependency.

package main

import (
    "bytes"
    "encoding/json"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

const apiKey = "YOUR_API_KEY"
const base = "https://yourimageshare.com/api"

func uploadFile(path string) (map[string]any, error) {
    file, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("uploads", path)
    io.Copy(part, file)
    writer.Close()

    req, _ := http.NewRequest("POST", base, body)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("X-API-Key", apiKey)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    var result map[string]any
    json.NewDecoder(res.Body).Decode(&result)
    return result, nil
}

Công cụ chụp màn hình

Một tiện ích trình duyệt cùng các cấu hình và script dựng sẵn để gửi ảnh chụp màn hình thẳng lên YourImageShare, không cần tải lên thủ công. Mỗi công cụ đều tải lên qua cùng endpoint /api được nêu ở trên.

Tiện ích trình duyệt (Chrome & Firefox)

Tiện ích YourImageShare Capture cho Chrome và Firefox giúp bạn bỏ qua script và file cấu hình hoàn toàn. Tiện ích chụp vùng đang hiển thị, một vùng kéo chọn hoặc cả trang cuộn dài, mở trình chỉnh sửa tích hợp để thêm mũi tên, văn bản, làm mờ/che thông tin và các chú thích khác, sau đó tải kết quả xuống, sao chép vào clipboard hoặc đăng thẳng lên YourImageShare chỉ với một cú nhấp. Việc đăng dùng cùng endpoint /api được nêu ở trên - chỉ cần thêm khóa API một lần trong phần Cài đặt của tiện ích và mỗi lần đăng sau đó sẽ trả về ngay một link chia sẻ. Hoạt động trên Chrome máy tính (và các trình duyệt Chromium khác), Firefox máy tính và Firefox cho Android.

Tải YourImageShare Capture cho Firefox Tải YourImageShare Capture cho Chrome

ShareX

Tải trình tải lên tùy chỉnh bên dưới, rồi trong ShareX vào Destinations > Custom uploader settings > Import > from file, mở file .sxcu vừa tải, và thay YOUR_API_KEY trong trường Headers bằng khóa thật của bạn. Đặt nó làm đích cho ảnh/file và các ảnh chụp sẽ tự động được tải lên.

Tải YourImageShare.sxcu

Flameshot (Linux)

Một shell script nhỏ chạy flameshot gui, tải ảnh chụp lên và sao chép link vào clipboard. Hãy gán nó cho một phím tắt trong môi trường desktop của bạn thay cho phím tắt mặc định của Flameshot.

Tải yis-flameshot-upload.sh

# One-time setup
chmod +x yis-flameshot-upload.sh
export YIS_API_KEY="YOUR_API_KEY"   # or add to ~/.config/yourimageshare/api_key

# Then bind this to a hotkey instead of calling flameshot directly:
/path/to/yis-flameshot-upload.sh

Greenshot (Windows)

Một script PowerShell cho đích External command tích hợp sẵn của Greenshot. Tương thích với Windows PowerShell 5.1 đi kèm Windows, không cần cài thêm gì.

Tải yis-greenshot-upload.ps1

# One-time setup
setx YIS_API_KEY "YOUR_API_KEY"

# In Greenshot: Preferences > Destinations > External command > Settings
#   Command:   powershell.exe
#   Arguments: -ExecutionPolicy Bypass -File "C:\path\to\yis-greenshot-upload.ps1" "%1"

Plugin diễn đàn

Thêm một nút "Tải ảnh lên" thực sự cạnh trình soạn thảo bài viết của diễn đàn. Mỗi plugin tải lên qua cùng endpoint /api được nêu ở trên và chèn BBCode tại vị trí con trỏ - không cần mở tab riêng, không phải sao chép dán thủ công.

Ảnh tải lên từ diễn đàn mặc định là private: ảnh hiển thị được trong bài viết, nhưng YourImageShare không tạo trang riêng cho ảnh (không có bình luận, reaction hay quảng cáo). Mỗi plugin có một tùy chọn để chuyển sang unlisted nếu bạn muốn có thêm một trang cho bất kỳ ai có link.

phpBB

Một extension phpBB 3.2/3.3 thực thụ. Giải nén vào ext/, bật nó trong Customise > Manage extensions, rồi thay YOUR_UPLOAD_ONLY_KEY trong file template event của extension bằng khóa chỉ tải lên thật của bạn.

Tải cho phpBB

SMF (Simple Machines Forum)

Một gói SMF thực thụ - cài qua Admin > Package Manager, rồi thay YOUR_UPLOAD_ONLY_KEY trong Sources/yis_forumupload.php bằng khóa chỉ tải lên thật của bạn.

Tải cho SMF

MyBB

Một plugin MyBB 1.8 thực thụ. Sao chép vào inc/plugins/, kích hoạt trong Configuration > Plugins, rồi thay YOUR_UPLOAD_ONLY_KEY trong file plugin bằng khóa chỉ tải lên thật của bạn.

Tải cho MyBB

FluxBB, PunBB & ZetaBoards

Các diễn đàn này không có hệ thống plugin chính thức, nên đây là một đoạn mã nhỏ được dán trực tiếp vào template (FluxBB/PunBB) hoặc Admin CP (ZetaBoards) - có hướng dẫn sao chép dán đầy đủ cho từng loại:

Hướng dẫn FluxBB Hướng dẫn PunBB Hướng dẫn ZetaBoards

Plugin WordPress

Chuyển Thư viện phương tiện của bạn sang YourImageShare thay vì ổ đĩa cục bộ. Ảnh/video mới tải lên sẽ tự động đi qua cùng endpoint /api được nêu ở trên, file cục bộ (và mọi kích thước thu nhỏ được tạo ra) sẽ bị xóa khi việc tải lên được xác nhận, và mọi URL đính kèm của WordPress - trình soạn thảo block, ảnh đại diện, thư viện ảnh, REST API - đều trỏ tới file được lưu trữ trên YourImageShare. Không cần shortcode, không đổi quy trình làm việc.

• Chuyển hàng loạt Thư viện phương tiện hiện có chạy nền (hoặc bằng wp yis offload --all), không chỉ các file mới tải lên
• Ảnh và video đã chèn trong bài viết vẫn hoạt động sau khi file cục bộ bị xóa
• Ảnh thu nhỏ và srcset dùng ảnh thu nhỏ 280px của chúng tôi, nên các vị trí ảnh nhỏ không phải tải file kích thước đầy đủ
• File tới 200MB, được gửi theo từng phần nên video lớn không bao giờ làm nặng host dùng chung
• Khôi phục bất kỳ file nào đã chuyển về lưu trữ cục bộ bất cứ lúc nào
• Một cột trong Thư viện phương tiện cho biết file nào đã chuyển và file nào vẫn ở cục bộ
• File đã chuyển được lưu ở chế độ private: chúng hiển thị ở mọi nơi trang web của bạn dùng, nhưng không có trang riêng trên YourImageShare

Tải trên WordPress.org Tải file ZIP

Trong WordPress: Plugins > Add New, tìm YourImageShare Media Offload, rồi Install và Activate.

Từ blog