API 文档

获取 API 密钥

登录后进入我的账户, 打开 API 标签页。你的密钥会显示在那里,旁边还有一个 重新生成按钮。重新生成密钥会立即使旧密钥失效, 所以点击之前请先更新所有正在使用旧密钥的地方。

该标签页还有第二个独立的仅上传密钥, 请参阅下面的提示和论坛插件,了解何时应该改用它。

身份验证

推荐把密钥放在请求头中发送,因为查询字符串往往会被记录到访问日志、代理日志和 Referer 头里:

X-API-Key: YOUR_API_KEY

也可以使用 ?key= 查询参数,保留它是为了兼容旧的集成和临时的 curl 命令。如果两者同时存在,以请求头为准。

?key=YOUR_API_KEY

接口

上传、列出和删除使用相同的身份验证和频率限制; 大文件可以先分片发送。

POST /api - 上传文件

为已验证的账户上传单个文件。

支持的类型:图片:JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC 或 HEIF;视频:MP4, WEBM 或 AVI (具体列表可能会随时间扩充)。HEIC/HEIF 和 TIFF 会以 WebP 保存, MP4/WebM 以外的视频会转换为 MP4,较大的 JPEG/PNG 图片在上传后不久, 如果转换后明显更小,也会被转换为 WebP。最大 大小:200MB;超大或无法读取的文件会被拒绝并返回 422。

响应 - 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 - 大文件

单个请求最多只能携带 100MB。对于更大的文件(最大 200MB),或者在网速较慢时想让每个请求保持较小, 可以把文件拆成每片最大 5MB 的分片发送,最后用 POST /api 完成:

1. 选择一个上传 ID:32 个随机十六进制字符。
2. 对每个分片,使用 POST /api/chunk(multipart/form-data)发送 upload_id、index(从 0 开始)、total(分片总数) 以及放在 chunk 中的字节数据。响应为 {"type": "success", "chunk_size": 5242880}。
3. 使用 POST /api,发送 upload_id 和 filename 来代替 uploads,再加上其他任何上传字段。响应与普通上传的响应相同。

未完成的上传的分片会在 2 小时后删除。只有最后完成上传的 POST /api 才计入上传频率限制。

GET /api/{id} 和 PATCH /api/{id} - 单个上传内容

GET 返回你的一个上传内容,字段与下面的列表相同。 PATCH 修改它的 visibility、title 或 description(表单字段或 JSON;标题或描述为空则清除), 并返回更新后的上传内容。两者都需要完整的 API 密钥;如果你的账户中没有这个上传内容, 则返回 404。

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 - 替换文件

替换你某个上传内容背后的文件,同时保留它的 ID、页面和所有链接。任何允许的类型都可以,甚至可以换成不同的类型(图片可以变成视频)。把新文件作为 uploads 发送(或使用通过 POST /api/chunk 分片发送的文件的 upload_id);keep_original 的用法与上传时相同。新文件会经过与新上传相同的检查和转换,旧版本会被移除。需要完整的 API 密钥;如果你的账户中没有这个上传内容,则返回 404;如果它受密码保护或限制了查看次数,则返回 409。

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

GET /api - 列出你的上传内容

返回已验证账户的上传内容的分页列表(无论来自 API、网站还是编辑器), 按时间倒序,每页 50 条。

响应 - 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 }
}

这里各字段的含义与上面的上传响应相同 (对于受密码保护的上传内容,path 和 thumb 是短期有效的签名链接)。目前还没有单独的"获取单个上传内容" 接口,所以这个列表也是事后查找文件 id 的方法。

DELETE /api/{id} - 删除上传内容

永久删除已验证账户的一个上传内容。此操作无法通过 API 撤销。{id} 是上传或列出接口返回的 id 的值。

响应 - 200 OK:

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

如果你的账户中不存在该 ID 的上传内容(要么从来不是你的, 要么已经被删除),则返回 404。

频率限制

每个 API 密钥都有独立的每分钟和每天配额, 另外还有一个更宽松的每 IP 每日上限,用来防止同一个 IP 轮换使用 多个密钥。上传、列出和删除共用相同的限制。

这些限制可能会调整。每个响应都包含 标准的频率限制响应头:

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

超出限制后会返回 429,并带有 Retry-After 头,告诉你需要等待多少秒。

错误

无论是哪个接口、什么原因,所有错误响应都使用相同的格式:

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

客户端库

官方 SDK 封装了上述接口,返回带类型的 结果,并在 API 出错时抛出异常,无需自己处理原始 HTTP。

JavaScript / TypeScript

零依赖,可用于 Node.js 和浏览器。也发布在 JSR, 包名为 @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - 源码相同,直接以 TypeScript 发布。

npm install yourimageshare

Python

一个依赖(requests),Python 3.8+。

pip install yourimageshare

PHP

零 Composer 依赖(使用 PHP 自带的 curl 扩展),PHP 7.4+。 源码在 GitHub。

composer require yourimageshare/yourimageshare-php

Go

零依赖(仅使用标准库),Go 1.18+。完整的参考文档请见 pkg.go.dev。

go get github.com/yourimageshare/yourimageshare/go

Rust

两个依赖(用于阻塞式 HTTP 的 ureq,不会引入异步运行时, 外加 serde),Rust 1.70+。源码在 GitHub。

cargo add yourimageshare

Ruby

零 gem 依赖(标准库 Net::HTTP + json),Ruby 2.7+。 源码在 GitHub。

gem install yourimageshare

.NET

一个依赖(微软自己的 System.Text.Json),目标为 netstandard2.0, 因此 .NET Framework 和现代 .NET 都可以使用。源码在 GitHub。 已针对这个线上 API 构建并验证,即将发布到 NuGet。

dotnet add package YourImageShare

Dart / Flutter

一个依赖(http,Dart 团队自己的包),Dart 2.17+。源码在 GitHub。 已针对这个线上 API 构建并验证,即将发布到 pub.dev。

dart pub add yourimageshare

Elixir

一个依赖(Req),Elixir 1.14+。返回 {:ok, result}| {:error, reason} 标记元组,与其他所有 SDK 处理此 API 错误的方式直接对应,同时还提供会抛出异常的 bang 变体。源码在 GitHub, 文档在 HexDocs。

{:yourimageshare, "~> 1.1"}

MCP 服务器

适用于 AI 编程智能体(Claude Code、Cursor 以及其他兼容 MCP 的 工具):把截图作为真实的链接放进 bug 报告、PR 描述或支持对话, 而不是 base64 数据或手动上传步骤。与 Claude Desktop 和任何其他 MCP 客户端的使用方式相同。直接用 npx 运行,无需安装:

npx yourimageshare-mcp

工具:upload_image(本地文件、内联内容或链接,最大 200MB,可选设置可见性、标题和自动删除)、list_uploads、get_upload、update_upload 和 delete_upload。

也已收录于官方 MCP Registry(名称为 io.github.yourimageshare/yourimageshare),并上架 Smithery 和 Glama,如果你的 MCP 客户端从这些地方安装,也可以使用。

刚接触 MCP?请参阅如何通过 MCP 把 Claude 和 ChatGPT 连接到此 API,获取完整的设置教程。

代码示例

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)

上面的官方 Go SDK已经为你封装好了这些, 这个原始版本是留给不想添加依赖的人的。

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
}

截图工具

一个浏览器扩展,加上现成的配置和 脚本,可以把截图直接发送到 YourImageShare,无需手动 上传。它们都通过上面介绍的同一个 /api 接口上传。

浏览器扩展(Chrome 和 Firefox)

适用于 Chrome 和 Firefox 的 YourImageShare Capture 扩展完全不需要 脚本和配置文件。它可以截取可见区域、 拖选的区域或整个滚动页面,并打开内置编辑器, 添加箭头、文字、模糊/遮盖等标注,然后下载结果、 复制到剪贴板,或一键直接发布到 YourImageShare。 发布使用上面介绍的同一个 /api 接口: 在扩展的设置中填入一次 API 密钥,之后每次 发布都会立即返回可分享的链接。可用于电脑版 Chrome(以及其他 Chromium 浏览器)、电脑版 Firefox 和 Android 版 Firefox。

获取 Firefox 版 YourImageShare Capture 获取 Chrome 版 YourImageShare Capture

ShareX

下载下面的自定义上传器,然后在 ShareX 中依次进入 目标 > 自定义上传器设置 > 导入 > 从文件, 打开下载的 .sxcu 文件,并把 Headers 字段中的 YOUR_API_KEY 替换为你的真实密钥。把它设为图片/文件的目标位置,截图就会自动上传。

下载 YourImageShare.sxcu

Flameshot(Linux)

一个小型 shell 脚本,运行 flameshot gui,上传 截图,并把链接复制到剪贴板。在你的桌面环境中,把它绑定到键盘 快捷键,代替 Flameshot 的默认快捷键。

下载 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)

适用于 Greenshot 内置外部命令 目标的 PowerShell 脚本。兼容 Windows 自带的 Windows PowerShell 5.1, 无需额外安装。

下载 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"

论坛插件

在论坛的发帖编辑器旁添加一个真正的"上传图片"按钮。 它们都通过上面介绍的同一个 /api 接口上传,并在光标处插入 BBCode, 无需另开标签页,也不用手动复制粘贴。

论坛上传默认是私密的:图片可以在帖子中正常显示, 但 YourImageShare 不会为它生成独立页面(没有评论、表情回应或广告)。每个 插件都有一个设置,可以切换为 unlisted,让任何拿到链接的人 也能访问页面。

phpBB

一个真正的 phpBB 3.2/3.3 扩展。解压到 ext/,在 自定义 > 管理扩展下启用,然后把扩展模板事件文件中的 YOUR_UPLOAD_ONLY_KEY 替换为 你真实的仅上传密钥。

下载 phpBB 版

SMF(Simple Machines Forum)

一个真正的 SMF 软件包,通过 管理 > 软件包管理器安装, 然后把 Sources/yis_forumupload.php 中的 YOUR_UPLOAD_ONLY_KEY 替换为你真实的仅上传密钥。

下载 SMF 版

MyBB

一个真正的 MyBB 1.8 插件。复制到 inc/plugins/,在 配置 > 插件下激活,然后把插件文件中的 YOUR_UPLOAD_ONLY_KEY 替换为你真实的仅上传 密钥。

下载 MyBB 版

FluxBB、PunBB 和 ZetaBoards

这些论坛没有正式的插件系统,所以提供的是一小段代码,需要直接粘贴 到你的模板(FluxBB/PunBB)或管理后台(ZetaBoards)中,下面是每个论坛完整的 复制粘贴说明:

FluxBB 说明 PunBB 说明 ZetaBoards 说明

WordPress 插件

把媒体库转移到 YourImageShare,而不是 存在本地磁盘上。新的图片/视频上传会自动通过上面介绍的同一个 /api 接口完成,上传确认后本地文件(以及每个生成的 缩略图尺寸)会被删除,而每个 WordPress 附件 URL(区块编辑器、特色图片、图库、REST API)都会指向 存放在 YourImageShare 上的文件。无需短代码,也不用改变工作流程。

• 在后台批量转移现有媒体库(也可以用 wp yis offload --all),而不只是新上传的文件
• 已放在文章中的图片和视频,在本地文件被移除后仍可正常使用
• 缩略图和 srcset 使用我们的 280px 缩略图,因此较小的图片位置不会加载原尺寸文件
• 最大 200MB 的文件,以分片方式发送,大视频也不会给共享主机造成压力
• 随时可以把任何已转移的文件恢复到本地存储
• 媒体库中的一列会显示哪些已转移、哪些仍在本地
• 已转移的文件以私密方式保存:在你的网站使用它们的地方都能正常加载,但在 YourImageShare 上没有独立页面

在 WordPress.org 获取 下载 ZIP

在 WordPress 中:插件 > 安装插件,搜索 YourImageShare Media Offload,然后安装并启用。

来自博客