PicBase API

一个 API 搞定 图片压缩 + 格式转换 + 存储 + CDN 直链。上传任意图片，自动压成 WebP（现代浏览器经 Accept 协商得到更小的 AVIF），返回全球 CDN 直链。

BASEhttps://api.picbase.net SPECopenapi.json

概览

项	说明
协议	HTTPS REST，请求/响应均 JSON（上传用 `multipart/form-data`）
鉴权	`Authorization: Bearer <API_KEY>`（`pk_live_…`）
错误	统一错误模型，稳定 `code` 字段（按 code 分支，不依赖文案）
机器可读	OpenAPI 3.1：`GET /openapi.json` · 发现端点：`GET /`
编码	默认 WebP（视觉无损 q82）；分发层按 `Accept` 协商 AVIF/WebP
去重	内容寻址：同图重复上传不重复计费、复用同一直链
隐私	默认剥除 EXIF（含 GPS）

快速开始（3 步接入）

# 1) 在控制台 app.picbase.net 创建 API Key（pk_live_…），明文仅显示一次
# 2) 上传一张图片 → 自动压成 WebP → 返回 CDN 直链
curl -X POST https://api.picbase.net/v1/images \
  -H "Authorization: Bearer pk_live_xxx" \
  -F file=@photo.jpg

# 响应
{
  "id": "img_4KBRX1AMVJY4P06X",
  "url": "https://cdn.picbase.net/u/usr_xxx/<hash>.webp",
  "size_original": 2451200, "size_optimized": 612300,
  "compression_ratio": 0.75, "width": 1920, "height": 1080
}

鉴权

所有 /v1/* 端点需在请求头带 API Key：

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API Key 在控制台（app.picbase.net）登录后创建；明文仅创建时返回一次，服务端只存哈希。
可创建多把、随时吊销，吊销即时生效。
无效/缺失凭据 → 401 unauthorized。

控制台用邮箱 + 密码注册登录（首次注册收邮件验证码，并有人机验证）→ 登录后创建 API Key。

Agent / 程序自助接入

PicBase API 为 Agent 友好设计，便于 LLM Agent / SDK / 自动化工具自助接入：

发现：GET https://api.picbase.net/ 返回 API 元信息 + OpenAPI 链接。
读 spec：GET /openapi.json（OpenAPI 3.1）—— 可据此自动生成调用、校验参数、枚举错误码。
拿 Key：由人在控制台创建后交给 Agent 使用（一次性配置）。
调用：端点 RESTful、参数可预测、错误码稳定，适合 Agent 自动重试与分支。

把上传封装成一个 LLM 工具：

{
  "name": "picbase_upload_image",
  "description": "压缩并上传一张图片到 PicBase，返回 CDN 直链",
  "parameters": {
    "type": "object",
    "properties": {
      "file_path": {"type":"string"},
      "quality": {"type":"integer","minimum":1,"maximum":100}
    },
    "required": ["file_path"]
  }
}

对应实现：POST /v1/images（multipart）→ 取响应 url。

API 端点

POST上传并压缩

/v1/images

GET列出图片

/v1/images

GET查元数据

/v1/images/{id}

DEL删除

/v1/images/{id}

POST大文件直传

/v1/uploads/presign

GET用量与额度

/v1/usage

POST /v1/images — 上传并压缩

把图片压成 WebP 并存储，返回 CDN 直链。两种入口：

A. 小文件（≤10MB）—— multipart

POST /v1/images
Authorization: Bearer <key>
Content-Type: multipart/form-data

字段：
  file       图片二进制（必填，jpeg/png/webp/gif）
  quality    1–100，默认 82
  lossless   true/false，默认 false
  resize     可选，"1920x" / "x1080" / "800x600"

B. 大文件（>10MB）—— 先 presign 直传再触发

POST /v1/images
Content-Type: application/json

{ "staging_key": "<来自 presign 的 key>", "quality": 82 }

响应 201 Created（去重命中为 200）：

{
  "id": "img_xxx",
  "url": "https://cdn.picbase.net/u/usr_xxx/<hash>.webp",
  "format": "webp",
  "size_original": 2451200, "size_optimized": 612300,
  "compression_ratio": 0.75, "width": 1920, "height": 1080
}

去重：同账户同内容重复上传 → 返回已有记录（200），不重复占额度/存储。
GIF：当前透传保留动画（format:"gif"），不转码。
AVIF：上传后异步在后台生成 AVIF；分发层按 Accept 自动发更小的 AVIF（见内容协商），无需你额外操作。

GET /v1/images — 列出图片（游标分页）

GET /v1/images?limit=50&cursor=<opaque>
→ { "data": [ {Image}, … ], "next_cursor": "…" | null }

limit ≤ 100。用上一页返回的 next_cursor 取下一页；null 表示到底。

GET /v1/images/{id} — 查元数据

→ 200 返回 {Image}；不存在或非本人 → 404 not_found。

DELETE /v1/images/{id} — 删除

→ 204 No Content（软删 + 扣减存储计量）。

POST /v1/uploads/presign — 大文件直传

POST /v1/uploads/presign
{ "content_type": "image/png", "size": 18000000 }
→ {
  "upload_url": "https://api.picbase.net/v1/uploads/put?grant=…",
  "method": "PUT",
  "staging_key": "staging/usr_xxx/…",
  "expires_in": 3600
}

流程：① 调 presign 拿 upload_url + staging_key → ② 把原图字节 PUT 到 upload_url（带同一个 Authorization）→ ③ POST /v1/images { staging_key } 触发转码。

GET /v1/usage — 用量与额度

{
  "period": "2026-06", "plan": "free",
  "image_count": 12, "image_quota": 50,
  "storage_used_bytes": 31550, "transform_count": 12, "api_calls": 18
}

错误模型

所有错误统一结构，HTTP 状态码 + 稳定 code：

{ "error": { "code": "quota_exceeded", "message": "…", "request_id": "req_xxx" } }

HTTP	code	含义
400	`invalid_request` / `unsupported_format` / `file_too_large`	参数 / 格式 / 超限
401	`unauthorized`	无效或缺失凭据
403	`forbidden`	越权 / 账户被封
404	`not_found`	资源不存在
413	`payload_too_large`	请求体超限
422	`decode_failed`	图片无法解码
429	`rate_limited` / `quota_exceeded`	限流 / 额度用尽（带 `Retry-After`）
503	`transcode_unavailable`	转码暂不可用
500	`internal`	内部错误（含 `request_id`）

建议：客户端/Agent 按 code 分支；遇 429 读 Retry-After 退避重试；5xx 指数退避重试。

限额与配额

维度	免费档	说明
图片总数	50 张	新用户默认；满额上传返回 `429 quota_exceeded`
上传单图	≤10MB / ≤50MB	multipart / presign
像素	单边 ≤ 8000px
限流	按 Key/用户滑动窗口	超限 `429 rate_limited` + `Retry-After`
转码	按月计	跨月归零

付费档（Pro/Biz）额度更高，详见控制台。计费当前未开放。

内容协商（自动更小）

图片直链统一是 …/<hash>.webp。分发层（CDN）按浏览器 Accept 头自动协商：

支持 AVIF 的浏览器（Accept: image/avif）→ 自动得到更小的 AVIF（约比 WebP 再小 20~30%）；
不支持的 → 回退 WebP。

你无需改 URL、无需做任何事——同一个直链，不同客户端各取所需。响应头 X-PicBase-Format 指示实际格式；Vary: Accept + 长缓存 immutable。

代码示例

cURL

curl -X POST https://api.picbase.net/v1/images \
  -H "Authorization: Bearer $PICBASE_KEY" -F file=@photo.jpg -F quality=82

Python

import requests
r = requests.post("https://api.picbase.net/v1/images",
    headers={"Authorization": f"Bearer {KEY}"},
    files={"file": open("photo.jpg","rb")}, data={"quality": 82})
print(r.json()["url"])

Node.js

const fd = new FormData();
fd.append("file", new Blob([await fs.readFile("photo.jpg")]), "photo.jpg");
const r = await fetch("https://api.picbase.net/v1/images", {
  method: "POST", headers: { Authorization: `Bearer ${KEY}` }, body: fd });
console.log((await r.json()).url);

约定与版本

API 版本前缀 /v1；破坏性变更走新版本号，旧版并行过渡。
契约以 GET /openapi.json 为机器可读真值，随发布更新。
时间戳为 Unix 秒；ID 形如 img_/usr_/ak_。

获取 API Key →