开发者文档

MiniPic 提供两层 API：兼容层（兼容主流压缩 API 的认证与响应结构，接入只需换地址与 Key）与原生层（/v1/*，同步压缩与用量查询）。只按成功压缩计费，每月 500 次免费额度，所有响应带用量头，账单可逐条对账。

接口稳定承诺：/shrink 与 /v1 的破坏性变更提前 90 天公告。

快速开始

30 秒压缩第一张图：在控制台创建 API Key，然后直接发起请求。

# 压缩一张 PNG（Basic 认证，user 固定为 api） curl -s --user api:你的_API_KEY \ --data-binary @input.png \ -o output.png \ https://api.minipic.cn/v1/compress

结果以加密私有链接返回，仅持有 Key 的你可访问——图片仅用于本次压缩，全程加密、拒绝泄漏，绝不用于训练或任何其他用途。

认证

HTTP Basic（兼容主流压缩 API）：用户名固定 api，密码为 API Key——Authorization: Basic base64("api:KEY")
Bearer（原生层推荐）：Authorization: Bearer KEY

Key 前缀 mp_live_（生产）/ mp_test_（沙箱）；服务端仅保存 Key 哈希，完整 Key 只在创建时展示一次。每个账户最多 5 个 Key。认证失败统一返回 401，不区分原因（防枚举）。

POST /shrink 压缩图片

请求体二选一：原始二进制图片（PNG / JPEG / WebP / HEIC），或 JSON 指定来源 URL（仅 http/https 公网地址，拉取超时 10 秒）。HEIC 仅作输入：不指定输出格式时转为 JPEG。

# 方式一：直接上传二进制 curl -s --user api:你的_API_KEY \ --data-binary @input.png \ https://api.minipic.cn/shrink

# 方式二：由服务端拉取 URL curl -s --user api:你的_API_KEY \ -H "Content-Type: application/json" \ -d '{"source": {"url": "https://example.com/input.png"}}' \ https://api.minipic.cn/shrink

成功返回 201 Created，响应头含 Location（结果地址）与 Compression-Count（当月已计费张数）：

{ "input": { "size": 207565, "type": "image/png" }, "output": { "size": 63274, "type": "image/png", "width": 1280, "height": 720, "ratio": 0.3049, "url": "https://api.minipic.cn/output/{id}" } }

GET /output/{id} 下载结果

需认证；返回压缩结果二进制。结果经加密私有链接提供，链接过期后返回 404 OutputExpired，重新压缩即可再次获取。重复下载同一结果不计费。

POST /output/{id} 衍生操作

对压缩结果执行 resize / convert / preserve，每个衍生输出计 1 张：

# 等比缩放到宽 800，并转 WebP curl -s --user api:你的_API_KEY \ -H "Content-Type: application/json" \ -d '{"resize": {"method": "scale", "width": 800}, "convert": {"type": "image/webp"}}' \ -o thumb.webp \ https://api.minipic.cn/output/{id}

resize.method：scale（单边等比）/ fit（完整放入）/ cover（裁切填满，当前为中心裁切）
convert.type：image/webp、image/png、image/jpeg 互转
preserve：copyright / creation / location 元数据保留

能力边界（接入前必读）：thumb 智能缩略图暂未开放（返回 501 NotImplemented）；cover 为中心裁切（智能主体检测规划中）；不支持 AVIF 输出；不支持 store 直传 S3/GCS（国内对象存储直传方案规划中）。

POST /v1/compress 同步压缩（原生层）

一次请求直接返回压缩结果二进制，省一次往返，CI 场景友好：

# 质量档位与输出格式由查询参数控制 curl -s -H "Authorization: Bearer 你的_API_KEY" \ --data-binary @input.jpg \ -o output.jpg \ "https://api.minipic.cn/v1/compress?quality=smart&format=keep"

quality：smart（默认）/ high / extreme / 1-100
format：keep（保持原格式）/ webp
响应头：X-Input-Size / X-Output-Size / X-Ratio / Compression-Count

GET /v1/usage 用量查询

返回当月计数、免费余量、资源包余量与预估账单，与控制台、月账单完全同源：

{ "month": "2026-06", "compressed": 1234, "free_quota": { "total": 500, "used": 500 }, "bundles": [ { "id": "...", "total": 10000, "remaining": 5210 } ], "pay_as_you_go": { "count": 734, "estimated_amount_cny": "36.70" }, "rate_limit": { "rps": 10, "burst": 20 } }

配额与限流

速率：10 req/s/Key，突发 20（令牌桶）；超出返回 429 + Retry-After
并发：同 Key 进行中任务 ≤ 20
免费月配额：500 张/月/账户；用尽且未绑支付返回 429 AccountLimitReached
单文件：免费 5MB；付费 80MB；企业可定制
像素：≤ 1 亿像素，超出返回 422 ImageTooComplex

所有计量端点响应头：Compression-Count、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。

计费口径

POST /shrink 成功（201）：计 1 张
POST /v1/compress 成功（200）：计 1 张
GET /output/{id} 重复下载：不计费
POST /output/{id} 衍生操作成功：每次计 1 张
4xx / 5xx、审核拦截、URL 拉取失败：不计费；重试后成功仅计成功那次

扣费顺序：免费额度 → 资源包（先购先扣，永不过期）→ 按量月结。单价见定价页阶梯表。

AI / Skill 接入

MiniPic 提供官方 Agent Skill（minipic-compress）：装上之后，对 Claude Code / Cursor / Codex CLI / Copilot CLI 等支持 Anthropic Agent Skills 开放标准的 AI agent 说一句「把这个目录的图片压一下」，它就会自动调用 MiniPic API 完成压缩、转 WebP、批量处理，并报告压缩比——无需你手写 curl 与重试逻辑。

安装

任选一种方式（三选一）：

# 方式一：经 skills.sh（npx，推荐） npx skills add minipic/minipic-skill

# 方式二：经 gh skill gh skill install minipic/minipic-skill

# 方式三：手动放入 skills 目录（Claude Code 个人级 / 项目级） cp -r minipic-compress ~/.claude/skills/ # 或项目级：cp -r minipic-compress <你的项目>/.claude/skills/

其它支持 Agent Skills 标准的 agent（Cursor / Codex CLI / Copilot CLI 等），按其文档把minipic-compress/ 目录放入对应的 skills 路径即可。

配置 API Key

Key 只从环境变量读取，绝不硬编码、绝不回显。在控制台创建 Key 后设入环境变量：

# 必填：你的 API Key（免费 500 张/月/账户） export MINIPIC_API_KEY=mp_live_你的key # 可选：覆盖 API 基址（默认 https://api.minipic.cn） # export MINIPIC_API_BASE=https://api.minipic.cn

能力范围与触发示例

当你对 agent 表达以下意图时，Skill 会自动触发：

「把这张图 / 这个目录的图片压缩一下」
「把 hero.png 转成 WebP 并尽量小」
「这些图太大了，打包前帮我批量优化，并告诉我省了多少」

覆盖能力：单文件 / 目录批量 / 远程 URL 压缩，PNG·JPEG·WebP 互转，质量档位（smart / high / extreme）选择，自动换算并报告节省百分比，429 限流自动退避重试。

平台网络限制：本 Skill 调用云端 HTTP API，需要外网，主打有网络的本地 agent 场景（Claude Code / Cursor / Codex CLI / Copilot CLI）。Claude API 的代码沙箱默认无外网、 Claude.ai 网络受限，可能不可用；需要纯离线本地压缩请用 MiniPic 桌面客户端。

错误码表

错误体结构遵循主流压缩 API 约定：{"error": "代码", "message": "人话描述"}，字段只增不删。

HTTP	error	触发条件	说明
400	`BadRequest`	请求体为空、JSON 非法、参数越界	请求参数有误，这张图没有压缩成功。请重试，持续出现请联系 support@minipic.cn
400	`InputMissing`	请求体缺少图片内容	文件内容为空，无法压缩。请检查文件后重新上传
401	`Unauthorized`	Key 缺失 / 无效 / 停用	API Key 无效或已停用。请检查 Key 是否正确，或到控制台重新创建
403	`AccountSuspended`	账户封禁 / 欠费	该账户已被限制使用。如有疑问，请联系 support@minipic.cn
404	`NotFound`	路径错误	请求的资源不存在。请检查链接是否正确
404	`OutputExpired`	结果私有链接已过期	这个加密私有链接已过期，结果无法再访问。重新上传即可再次压缩
413	`PayloadTooLarge`	超过套餐单文件上限	这张图超过免费版单张 5 MB 上限。升级 Pro 可压缩最大 80 MB 的大图
415	`UnsupportedMediaType`	非 PNG / JPEG / WebP 输入	暂不支持这个格式，目前支持 PNG、JPEG、WebP
422	`DecodeError`	文件损坏、伪装扩展名	这张图片无法解码：文件可能已损坏，或不是有效的图片。请检查后重新上传
422	`ImageTooComplex`	超过 1 亿像素上限	图片超过 1 亿像素处理上限。请先缩小尺寸再压缩
422	`ContentBlocked`	内容安全拦截（不计费）	未通过内容安全检测，已拦截并彻底删除，未计入用量。如认为是误判，请联系 appeal@minipic.cn
429	`TooManyRequests`	限流 / 并发超限（带 Retry-After）	请求太频繁，这张图暂时排不进队列。请稍等片刻再重试
429	`AccountLimitReached`	免费额度用尽且未绑支付（带 upgrade_url）	今天的 100 张免费额度已用完。登录后不限每日次数（每月 1,000 张），Pro 单图最大 80MB
500	`InternalServerError`	服务异常（带 request_id）	服务出现异常，这张图没有压缩成功，请稍后重试
501	`NotImplemented`	resize thumb 等未开放能力	这个功能暂未开放。请关注开发者文档的更新公告
503	`ServiceUnavailable`	过载 / 维护（带 Retry-After）	服务正忙，这张图暂时没有压缩成功，请稍后重试