API 与 MCP 文档

免费 API 是独立于浏览器工具的云端功能。使用 Google 登录并确认账户是 Google 已验证的 @gmail.com 后，再通过 Turnstile，即可在每个 UTC 自然月获得 500 credits，不绑卡。免费云端压缩每月有 20 美元计算预算。

激活后在账户设置页创建 API key。该账户下所有 key 共用同一 credit 池、限速和未完成任务上限。免费计算预算用尽后，新免费任务会暂停到页面显示的恢复时间；付费 Developer 任务和浏览器本地压缩继续独立工作。

发送 multipart 请求，包含 GIF 文件和 JSON 字符串 options。目标模式使用十进制字节 targetBytes；不要把 mode 或 targetBytes 拆成单独表单字段。

每个创建请求都必须带账户范围内的 Idempotency-Key。同一个 key 搭配同一个文件和选项会返回原任务，不会再次预占 credits。

创建响应的顶层 id 就是任务 ID，并不嵌套在 job 属性内。把它保存为 JOB_ID，用于状态查询地址。创建响应本身不提供下载链接，即使幂等重放的是已完成任务，也需要查询状态。将示例中的 YOUR_JOB_ID 替换为该 ID；任务成功后，把 result.downloadUrl 填入 DOWNLOAD_URL，再执行下载命令。

status 为 queued 或 processing 时，result 为 null；为 succeeded 时，读取 result.downloadUrl 和 result.expiresInSeconds。遇到 failed 或 canceled，请停止轮询，检查 error.code 和 error.message，不要继续尝试下载。

建议每隔几秒查询一次，并遵守账户的查询限速。文件仍可访问时，重新查询状态可以获得新的下载链接。链接最长有效 15 分钟，但不会延长文件的 24 小时访问期限。轮询、下载和完全相同请求的幂等重放都不消耗 credits。

JSON 创建请求使用 sourceUrl 和 options。服务端只抓取 HTTPS，逐跳验证重定向，阻止私网地址，并执行同样的文件大小限制。

如果某个网站阻止浏览器 CORS，本地 URL 导入可能失败。REST URL 导入仍属于云端任务，会使用你的 API key、credits、限速和保留规则。

GET /api/v1/usage 返回 { usage }。usage 包含当前额度池、额度上限、已用、预占、剩余、resetAt、windowStart 和 windowEnd。

免费 API 按 UTC 自然月重置。Developer 按订阅锚点逐月重置，年付也按月发放，未用 credits 不结转。 免费 API 每分钟可创建 10 个任务，Developer 为 60 个；查询接口每个账户每分钟最多 120 次。免费账户最多同时有 2 个未完成任务，Developer 为 20 个。免费队列最多积压 100 个任务，等待超过 10 分钟会终止并释放预占额度。

MCP 接口是 /api/mcp 上的 Streamable HTTP，提供 compress_gif、get_compression 和 get_usage，并使用同一个 REST API key。

MCP 接受远程 HTTPS GIF 地址。本地文件请通过 REST 上传；不要向 MCP 传服务器本地路径或大型 Base64。

调用 compress_gif 时，传入 sourceUrl、可选的 options 对象和必填的 idempotencyKey；随后把返回的 id 传给 get_compression。适配层将 REST 响应放在 structuredContent.data 中；工具调用成功不代表压缩任务已经完成。调用 get_usage 时传入空对象，即可查询余额。

不超过 5MB 的输入，质量/体积模式扣 1 credit，目标模式扣 2 credits。超过 5MB 且不超过 20MB 的输入扣 2 credits，目标模式扣 4 credits。 每次处理最多 60 秒，包含最多 8 次候选编码。

验证失败、系统失败和超时不扣用户 credits。返回有效结果但未达目标时，因为计算已完成，仍按已披露报价结算，并标记 targetMet: false。

任务中的 credits 和 cost.credits 表示报价，不代表已经实际扣点。接受任务时预占 credits，成功后结算，失败则释放。当前已用、预占和剩余额度请查询 /api/v1/usage。

401（API_KEY_REQUIRED、API_KEY_INVALID）表示密钥缺失或无效。402（INSUFFICIENT_CREDITS）表示额度耗尽；403（FREE_API_NOT_ACTIVE）表示尚未激活免费 API。409（IDEMPOTENCY_CONFLICT）表示同一 Idempotency-Key 被不同输入复用。

413（INPUT_TOO_LARGE）表示输入超过文件限制；422（INVALID_GIF）表示 GIF 或参数无效。429（RATE_LIMITED、TOO_MANY_OUTSTANDING_TASKS）表示触发请求或未完成任务上限。503（FREE_COMPUTE_BUDGET_EXHAUSTED）表示免费计算预算已用尽，下一 UTC 自然月恢复；付费 API 与浏览器工具继续工作。其他 503 表示服务暂不可用。如返回 Retry-After，请遵守。

浏览器本地压缩和云端 API 任务的数据处理方式不同。需要 GIF 留在设备上时，请使用浏览器工具；需要远程自动化处理时，再使用 REST 或 MCP。

浏览器工具不会上传你的 GIF。通过地址导入时，浏览器会直接访问图片所在网站。API 和 MCP 会上传文件，或由服务抓取公开 HTTPS 地址。应用、数据库和文件存储由 Cloudflare 托管。API 原始文件和结果文件在 24 小时后无法访问，下载链接最长有效 15 分钟。过期文件由后台清理，实际删除可能晚于访问失效时间。 为了解可靠性和使用情况，我们在 Cloudflare 服务日志中记录压缩成功或失败、输入输出大小、目标达成状态、下载等技术事件。这些事件不包含文件名、来源地址或文件内容。Cloudflare 还会处理提供服务和安全防护所需的请求数据。产品事件日志最多保留 7 天。

创建任务、查询状态和用量时，发送 Authorization: Bearer YOUR_API_KEY，也可以使用 x-api-key 请求头。账户登录 Cookie 不能替代 API key；同一账户的所有密钥共用额度和限制。

把密钥放在服务端环境变量或 AI 客户端的安全配置中，不要写进公开网页、代码仓库或图片地址。密钥泄露后，请在 API 密钥设置中撤销并重新创建。免费浏览器工具不需要 API key。

mode 支持 quality、size 或 target，默认是 quality。target 模式必须传正整数 targetBytes，单位是十进制字节：100KB 为 100000，1MB 为 1000000。使用 multipart 上传时，这些参数都放在 JSON 字符串 options 内。

可选参数 colors 支持 auto、64、128 或 256；lossyLevel 是 0 到 200 的整数；width 是 1 到 4096 的整数，用于主动调整尺寸，不传则保留原尺寸。目前不支持丢帧或格式转换参数。

每个请求处理一个 GIF。免费 API 输入最多 5MB，Developer 最多 20MB；两者还要求每条边不超过 4096 像素、最多 1,000 帧，且宽 × 高 × 帧数不超过 50,000,000。即使动画很短，尺寸过大也可能先触及这些限制。

每个新的文件与参数组合使用新的 Idempotency-Key；网络响应不确定、需要重试时，继续使用原 key。key 长度为 1–128 个非空格、可打印 ASCII 字符。完全相同的请求会返回原任务；同一个 key 换了输入或参数，会返回 409 IDEMPOTENCY_CONFLICT。

遇到 429 或临时 503 时，遵守返回的 Retry-After，并逐步延长重试间隔。402 表示 credits 不足，需要等待额度重置或更改套餐，重复请求不能解决。503 FREE_COMPUTE_BUDGET_EXHAUSTED 表示新免费任务暂停至页面显示的恢复时间，付费任务和本地工具仍独立运行。

对失败任务重放同一个 key，仍会返回原失败任务。请先检查原因，确实需要重新处理时再换一个 key。不要每次超时都创建新 key，因为第一次请求可能已经被接受。