开发者 API 文档

接口地址

所有接口均部署在你的云语图床域名下，统一前缀为 /api/v1。

鉴权方式

1. 用户 API Token

在 用户中心 → API 与对接 获取 Token，通过请求头传递：

Authorization: Bearer 你的API_TOKEN

2. 网站 AppKey 签名

在后台「站点对接」创建站点后获得 AppKey / AppSecret。每次请求需携带以下请求头：

X-App-Key: 你的AppKey
X-Timestamp: 当前Unix时间戳（允许 ±300 秒）
X-Signature: HMAC-SHA256(时间戳 + "\n" + 请求方法 + "\n" + 请求路径, AppSecret)

签名路径示例：/api/v1/upload。使用 AppKey 上传的文件会自动进入该站点绑定的云语文件夹，并标记站点归属。

上传文件

POST /api/v1/upload，使用 multipart/form-data，字段 file 或 files[]（支持多文件）。

curl -X POST 'https://tc.yykbk.com/api/v1/upload' \
  -H 'Authorization: Bearer 你的API_TOKEN' \
  -F 'file=@demo.jpg' \
  -F 'visibility=public'

成功响应：

{
  "code": 1,
  "msg": "上传成功",
  "data": [{
    "id": 12,
    "name": "demo.jpg",
    "url": "https://tc.yykbk.com/i/12",
    "page": "https://tc.yykbk.com/f/12",
    "download": "https://tc.yykbk.com/d/12",
    "kind": "image"
  }]
}

删除文件

POST /api/v1/delete，JSON 或表单提交：

{
  "file_id": 12
}

也可以传 url，系统会自动解析文件 ID。网站删除文件时调用该接口，云语上的对应文件会同步删除；若文件属于某个对接站点，云语会再向该站点回调 file.deleted 事件（自己删除自己的文件时不会重复通知）。

文件列表

GET /api/v1/files?page=1&per_page=20。AppKey 鉴权时返回该站点文件夹内的文件，用户 Token 鉴权时返回自己的文件。

{
  "code": 1,
  "data": {
    "items": [ ... ],
    "total": 128,
    "page": 1,
    "pages": 7
  }
}

创建分享

POST /api/v1/share：

{
  "file_id": 12,
  "days": 7,
  "pwd": "ab12",
  "max_visits": 20
}

days 支持 0（永久）、1、7、30；pwd 留空则无提取码；max_visits 为 0 表示不限。

网站对接完整流程

1. 后台创建站点：填写站点名称、回调地址、允许的来源域名，系统自动生成 AppKey / AppSecret，并创建专属文件夹。
2. 网站上传文件：使用 AppKey 签名调用 /api/v1/upload，文件自动进入绑定文件夹，返回直链。
3. 网站展示：把返回的 url / page 保存到网站数据库，直接在前台展示图片或提供下载。
4. 网站删除：用户删除网站内容时，网站调用 /api/v1/delete，云语文件同步删除。
5. 云语删除：管理员或用户在云语删除文件时，云语向站点回调地址发送 file.deleted，网站校验签名后删除本地记录。

源码包内附带 sdk/yunyu-sdk.php，已封装上传、删除、签名与 Webhook 校验方法，可直接引入使用。

网站上传示例

<?php
// 方式二：网站对接（AppKey + HMAC 签名），文件自动进入绑定文件夹
$appKey    = '你的 AppKey';
$appSecret = '你的 AppSecret';
$path      = '/api/v1/upload';
$timestamp = (string)time();
$signature = hash_hmac('sha256', $timestamp . "\n" . 'POST' . "\n" . $path, $appSecret);

$ch = curl_init($base . $path);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'X-App-Key: ' . $appKey,
        'X-Timestamp: ' . $timestamp,
        'X-Signature: ' . $signature,
    ],
    CURLOPT_POSTFIELDS => ['file' => new CURLFile('/path/to/file.zip')],
]);
$data = json_decode(curl_exec($ch), true);

Webhook 回调与验签

云语删除文件时，会向站点回调地址 POST JSON，并携带以下请求头：

X-Yunyu-Event: file.deleted
X-Yunyu-Timestamp: 1730000000
X-Yunyu-Signature: HMAC-SHA256(时间戳 + "." + 原始请求体, AppSecret)

回调数据结构

{
  "event": "file.deleted",
  "timestamp": 1730000000,
  "site": { "id": 1, "name": "我的网站" },
  "data": {
    "id": 12,
    "name": "demo.jpg",
    "url": "https://tc.yykbk.com/i/12",
    "download": "https://tc.yykbk.com/d/12",
    "ext": "jpg",
    "size": 204800,
    "kind": "image",
    "folder_id": 3,
    "deleted_at": 1730000000
  }
}

验签并删除本地记录

<?php
// 接收云语文件图床的删除通知（file.deleted）
$raw       = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_YUNYU_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_YUNYU_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $timestamp . '.' . $raw, $appSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('invalid signature');
}

$payload = json_decode($raw, true);
if (($payload['event'] ?? '') === 'file.deleted') {
    $fileId = (int)$payload['data']['id'];
    // 在这里删除网站本地保存的文件记录 / 引用
    // DELETE FROM attachments WHERE yunyu_file_id = $fileId;
}

echo json_encode(['ok' => true]);

请务必校验签名，并返回 2xx 状态码，否则云语后台会记录为失败。