API 文档

格式与限制

API 接收静态 JPEG、PNG 和 WebP 图片，可返回原格式、JPEG、PNG 或 WebP。不支持 GIF、BMP、HEIC、AVIF、JPEG XL、SVG、TIFF 和动图。单个文件不得超过 5 MB、2000 万像素。服务会校验 MIME 类型、文件签名并尝试解码，但这不能代替病毒扫描。

访问密钥

请在账户中创建 API 密钥。完整密钥只显示一次。通过 Authorization 请求头发送密钥，并将其保存在服务器上，不要放入公开代码。

压缩请求

向 /api-compress.php 发送 multipart/form-data 格式的 POST 请求，文件字段名为 image。可选字段 format 支持 original、jpeg、png、webp，默认为 original。billing_mode 支持 standard 或 bitrix，默认为 standard。成功响应包含处理后的图片，并在响应头中提供处理前后的大小。

curl

curl -X POST 'https://ankpicpress.com/api-compress.php' \
+  -H 'Authorization: Bearer ank_test_DEMO_ONLY_NOT_A_REAL_KEY' \
+  -F 'image=@photo.jpg' -F 'format=webp' --output photo.webp

Bitrix 模块计费模式

ank.imagecompress 使用 billing_mode=bitrix，并发送由 64 位十六进制字符组成的 X-ANK-Request-ID。重试同一任务时必须使用相同 ID；同一 ID 用于不同文件或格式时返回 409。重试结果最多保留 30 天。此模式仅在有效结果小于原图时扣除 1 次额度。standard 模式下，每次成功处理均扣除 1 次额度。

服务状态

GET /api-health.php 无需密钥，不处理图片也不消耗额度。服务可用时返回 200 和 {"status":"ok"}；检查失败时返回 503 和 {"status":"unavailable"}。HEAD 返回相同的 HTTP 状态，但不包含响应正文。

查询余额

GET /api-balance.php 需要 Authorization: Bearer <API_KEY>。响应包含 free_remaining、paid_credits 和 total_available，不会修改余额。无效或已撤销的密钥返回 401。每个密钥每分钟最多请求 60 次，超出后返回 429。

额度与错误码

每个自然月前 500 次 API 处理免费，剩余额度不结转。每次成功压缩或转换消耗 1 次额度。购买的额度不过期。错误码：400 请求无效；401 密钥无效；402 额度不足；413 超出大小限制；415 格式不支持；429 请求过于频繁；503 临时服务错误。错误响应为 JSON，说明位于 error 字段。