ClawDrive 图床 API

多用户图床系统 — 图片上传、管理、CDN 加速。支持人类用户和 AI Agent 接入。

Base URL: https://clawdrive.qname.com
OpenAPI 规范: openapi.yaml
Agent Skill 文档: skill.md（给 AI agent 的接入指南，可直接让 agent 读取）

快速开始

人类用户：使用 Gmail 注册 → 邮箱激活 → 获得 10GB 免费配额

AI Agent：调用注册接口 → 支付 0.0001 BTC → 轮询获取 Access Key → 全程无需人工

AI Agent 接入（全自动）

POST/api/agent/registerAgent

Agent 注册，返回 BTC 收款地址。无需邮箱。

{
  "keyName": "my-bot",
  "expiresIn": 30
}

响应：

{
  "success": true,
  "data": {
    "btcAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "minPayment": "10000 satoshi (0.0001 BTC)",
    "minPaymentSat": 10000,
    "deadline": "2026-07-05T00:00:00.000Z",
    "tips": "支付后轮询 GET /api/agent/status?address={btcAddress}"
  }
}

GET/api/agent/status?address={btcAddress}Agent

轮询支付状态，确认后自动激活并返回 Access Key。

未支付：

{
  "success": false,
  "status": "pending",
  "currentBalance": 0,
  "requiredBalance": 10000
}

已支付：

{
  "success": true,
  "status": "active",
  "accessKey": "ak_xxx",
  "secretKey": "sk_xxx",
  "signatureKey": "abc123...",
  "quotaLimit": "2147483648",
  "paidSat": 10000
}

Agent 完整流程：注册 → 往 btcAddress 打钱 → 轮询 status 直到返回 accessKey → 用 Access Key 调 API

认证方式

JWT Token（Web 用户登录后获取）

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Access Key（Agent 支付后获取）

X-Access-Key: ak_xxx
X-Signature: hmac_sha256_hex
X-Timestamp: 1727000000000

签名方式：HMAC-SHA256(signatureKey, "METHOD\n/path\ntimestamp")；timestamp 为毫秒，与服务器偏差须 < 5 分钟

用户认证（人类用户）

POST/api/auth/register免费 10GB

使用 Gmail 邮箱注册，发送激活邮件（仅限 @gmail.com）

{ "email": "[email protected]", "username": "myuser", "password": "mypassword123" }

响应：

{
  "success": true,
  "message": "注册成功，请查收邮件激活账户"
}

GET/api/auth/verify?token=xxx

点击邮件中的链接激活账户

POST/api/auth/login

{ "email": "[email protected]", "password": "mypassword123" }

POST/api/auth/send-code

发送 6 位登录验证码到邮箱（10 分钟有效，60 秒可重发）

{ "email": "[email protected]" }

POST/api/auth/login-code

邮箱 + 验证码登录（免密码，验证码一次性有效），返回 JWT Token

{ "email": "[email protected]", "code": "123456" }

配额升级（BTC 支付）

GET/api/upgrade需登录

获取专属 BTC 支付地址，向该地址支付后系统自动检测并升级配额

配额	金额
1 GB	0.0001 BTC
5 GB	0.0002 BTC
20 GB	0.0005 BTC
100 GB	0.001 BTC

图片上传

POST/api/upload

上传文件：图片自动转 WebP + 生成缩略图；音频/视频原样存储。伺服支持 Range 请求（206），可直接用于 <audio>/<video> 播放

参数	类型	说明
file	file	图片（jpg/png/gif/webp）或音视频（mp3/m4a/ogg/mp4），最大 10MB

响应：

{
  "success": true,
  "data": {
    "id": "7439902121924759552",
    "url": "https://img.qname.com/u/123/abc.webp",
    "thumbnail": "https://img.qname.com/t/123/abc.webp",
    "size": 152,
    "width": 200,
    "height": 200
  }
}

图片管理

GET/api/images

获取图片列表

参数	类型	默认	说明
page	int	1	页码
limit	int	20	每页数量
keyword	string	-	搜索关键词

DELETE/api/images/{id}

删除指定图片

文件管理（任意格式）

POST/api/files/upload

上传任意文件，原样存储不转换格式（图片自动生成缩略图），默认最大 100MB。字段名 file

GET/api/files

获取文件列表，支持 page / limit / keyword / folderId 参数，返回 cdnUrl 和 thumbUrl

DELETE/api/files/{id}

删除指定文件

配额查询

GET/api/quota

查询存储配额使用情况

{
  "success": true,
  "data": {
    "used": "1048576",
    "limit": "10737418240",
    "percentage": 0
  }
}

Access Key 管理

GET/api/keys

获取 Access Key 列表

POST/api/keys

创建 Access Key（用于程序调用）

{
  "keyName": "my-app",
  "expiresIn": 30
}

DELETE/api/keys/{id}

删除 Access Key

下载 OpenAPI 规范 (YAML)Agent Skill 文档 (skill.md)

支持项目

如果这个项目对你有帮助，欢迎捐赠：

ETH: 0x776C5394f5338828C24354067c0039aB77f48804