{"openapi":"3.1.0","info":{"title":"PicBase API","version":"1.0.0","description":"图片压缩 + 转换 + 存储 + CDN 直链，一个 API 搞定。上传任意图片，自动压成 WebP（现代浏览器经 Accept 协商得到更小的 AVIF），返回全球 CDN 直链。API Key 鉴权，错误码稳定，Agent 友好。","contact":{"url":"https://www.picbase.net"}},"servers":[{"url":"https://api.picbase.net","description":"Production"},{"url":"https://api-dev.picbase.net","description":"Dev"}],"security":[{"apiKey":[]}],"components":{"responses":{"Err":{"description":"错误（统一错误模型，按 code 分支）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API Key（`pk_live_…`），在控制台 app.picbase.net 创建。放在 `Authorization: Bearer <key>`。"}},"schemas":{"Image":{"type":"object","properties":{"id":{"type":"string","example":"img_4KBRX1AMVJY4P06X"},"url":{"type":"string","format":"uri","example":"https://cdn.picbase.net/u/.../<hash>.webp"},"format":{"type":"string","enum":["webp","gif"]},"size_original":{"type":"integer","example":2451200},"size_optimized":{"type":"integer","example":612300},"compression_ratio":{"type":"number","example":0.75},"width":{"type":"integer","example":1920},"height":{"type":"integer","example":1080}}},"Usage":{"type":"object","properties":{"period":{"type":"string","example":"2026-06"},"plan":{"type":"string","enum":["free","pro","biz"]},"image_count":{"type":"integer","example":12},"image_quota":{"type":"integer","example":50},"storage_used_bytes":{"type":"integer"},"transform_count":{"type":"integer"},"api_calls":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","unsupported_format","file_too_large","unauthorized","forbidden","not_found","already_exists","payload_too_large","decode_failed","rate_limited","quota_exceeded","transcode_unavailable","internal"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}},"paths":{"/v1/images":{"post":{"summary":"上传并压缩图片","description":"上传图片（≤10MB 走 multipart；更大走 /v1/uploads/presign）。自动转 WebP 并存储，返回 CDN 直链。同一内容自动去重。","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"图片二进制（jpeg/png/webp/gif）"},"quality":{"type":"integer","minimum":1,"maximum":100,"default":82},"lossless":{"type":"boolean","default":false},"resize":{"type":"string","description":"\"1920x\" / \"x1080\" / \"800x600\""}}}},"application/json":{"schema":{"type":"object","required":["staging_key"],"properties":{"staging_key":{"type":"string","description":"presign 流上传后得到的 staging key"},"quality":{"type":"integer"},"lossless":{"type":"boolean"},"resize":{"type":"string"}}}}}},"responses":{"200":{"description":"命中去重，返回已有","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"201":{"description":"已创建","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"400":{"$ref":"#/components/responses/Err"},"401":{"$ref":"#/components/responses/Err"},"429":{"description":"限流或额度用尽（quota_exceeded / rate_limited）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"列出图片（游标分页）","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"next_cursor":{"type":["string","null"]}}}}}}}}},"/v1/images/{id}":{"get":{"summary":"查图片元数据","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"404":{"$ref":"#/components/responses/Err"}}},"delete":{"summary":"删除图片","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"已删除"},"404":{"$ref":"#/components/responses/Err"}}}},"/v1/uploads/presign":{"post":{"summary":"取大文件上传地址（>10MB）","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content_type","size"],"properties":{"content_type":{"type":"string","example":"image/png"},"size":{"type":"integer","example":18000000}}}}}},"responses":{"200":{"description":"返回 upload_url（PUT 原图到此）+ staging_key（再 POST /v1/images 触发转码）","content":{"application/json":{"schema":{"type":"object","properties":{"upload_url":{"type":"string"},"method":{"type":"string"},"staging_key":{"type":"string"},"expires_in":{"type":"integer"}}}}}}}}},"/v1/usage":{"get":{"summary":"用量与额度","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}}}}}}}