图片处理 API
图片转换和压缩 API 开发者指南。
图片处理 API
使用带有 image 权限范围的 Developer API Key，可以在一次同步请求中转换或压缩一张图片。API 请求会消耗 Processing Credits，写入 Image API Request Log，并以内联 Base64 返回结果。
认证
使用以下任一请求头传递 Developer API Key：
Authorization: Bearer sk_dev_...
# 或
x-api-key: sk_dev_...密钥必须包含 image API Scope。只有 OCR scope 的密钥会被拒绝。
限制和计费
- 输入：JPEG、PNG、WebP、AVIF、GIF、TIFF 静态图片。
- 输出：JPEG、PNG、WebP、AVIF。
- 来源：multipart
file、JSONimage_url、JSONimage_base64。 - 限制：25 MB 输入、50 MP 像素、20 MB 原始输出、30 秒处理时间。
- 计费：按输入/输出较大的像素工作量计费，最低 1 个 Processing Credit。
- 默认移除元数据；可设置
preserve_metadata=true做尽力保留。
转换
curl -X POST https://image-to-text.org/api/v1/images/convert \
-H "Authorization: Bearer sk_dev_..." \
-F "[email protected]" \
-F "output_format=webp" \
-F "width=1200" \
-F "fit=inside"响应包含 data.output.base64、文件名、内容类型、尺寸、大小、data.metrics 和 data.usage。
压缩
按质量压缩：
curl -X POST https://image-to-text.org/api/v1/images/compress \
-H "Authorization: Bearer sk_dev_..." \
-F "[email protected]" \
-F "quality=72" \
-F "output_format=webp"按目标大小压缩：
curl -X POST https://image-to-text.org/api/v1/images/compress \
-H "Authorization: Bearer sk_dev_..." \
-H "Idempotency-Key: image-demo-001" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/photo.jpg",
"output_format": "jpeg",
"target_size_kb": 200
}'目标大小是尽力处理。只要生成了有效输出，请求会成功，并返回 target_reached 和 quality_used。
错误、幂等和限流
所有错误都使用统一结构：
{
"success": false,
"request_id": "...",
"error": {
"code": "invalid_input",
"message": "...",
"retryable": false
}
}使用 Idempotency-Key 可以安全重试计费请求。24 小时内完全相同的请求会返回缓存响应，不会再次扣除积分。相同 key 搭配不同输入或参数会返回 idempotency_conflict。Image API 的每日限制和最小请求间隔与 OCR 分开统计。
统一 OpenAPI 合约位于 /api/v1/openapi。