图像编辑
用图像 API 做整图编辑、蒙版局部重绘和生成变体。
概述
图像 API 提供三种编辑方式：整图编辑、蒙版局部重绘、变体。每种模式的源图（及可选蒙版）都以直传素材的形式提供 —— 没有 URL 通路，也没有内联通路。
警告
/v1/images/edits 与 /v1/images/variations 只接受 application/json。历史的 multipart/form-data 直传文件入口已下线 —— 发 multipart 会返回 415 legacy_multipart_removed。无论图片几 KB 还是 25 MB，源图和蒙版都必须先走预签名直传，再用 image_upload_id / mask_upload_id 提交 JSON。
三种模式
| 模式 | 端点 | 必填 | 效果 |
|---|---|---|---|
| 整图编辑 | POST /v1/images/edits | model、prompt、image_upload_id | 按提示词改整张图 |
| 蒙版局部重绘 | POST /v1/images/edits | 上面 + mask_upload_id | 只改蒙版覆盖的区域 |
| 变体 | POST /v1/images/variations | model、image_upload_id（无需 prompt） | 生成同风格变体 |
传了 mask_upload_id 就自动进入局部重绘模式，不需要额外开关。
编辑图片
先预签名直传源图（purpose=image_edit_source；局部重绘再传蒙版 purpose=image_edit_mask），然后提交 JSON：
| 1 | curl https://api.alltoken.ai/v1/images/edits -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "prompt": "把背景换成日落", |
| 4 | "image_upload_id": "upl_source...", |
| 5 | "mask_upload_id": "upl_mask...", |
| 6 | "size": "1024x1024", |
| 7 | "output_format": "png" |
| 8 | }' |
常用可选字段：size、quality、output_format、output_compression、background、moderation、n、user。完整字段见 图像 API 参考。
生成变体
变体只需一张源图（purpose=image_variation_source），无需 prompt：
| 1 | curl https://api.alltoken.ai/v1/images/variations -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "image_upload_id": "upl_source...", |
| 4 | "n": 2 |
| 5 | }' |
可选字段：size、n、output_compression、user。
取结果
创建返回 202 + { id, status: "queued", ... }。三种模式共用同一个轮询端点：
$curl https://api.alltoken.ai/v1/images/generations/{id} -H "Authorization: Bearer $ALLTOKEN_API_KEY"queued / processing 时响应带 next_poll_after_ms —— 按它决定下次轮询间隔。completed 时每个 data[] 项含 b64_json、r2_url、r2_url_expires_at、mime_type、revised_prompt。
警告
b64_json 是一次性交付 —— 只有首次 completed 的 GET 才返回，拿到就立即落盘。优先消费 r2_url（30 天有效、跨设备可访问），把 b64_json 当首次领取的兜底。r2_url 过期后 GET 返 410 image_expired。没有「图片列表」接口 —— 历史结果请自行按 task_id 记录。
批量编辑
单次请求只处理一张源图（加一张可选蒙版）。要批量编辑 N 张，就是 N 次独立的三步走 —— 每张各自 presign → PUT → 创建 → 轮询。可以并发，注意两条：
- pending 上限 100 个 —— 别一次性 presign 出几百个
upload_id放着不用。 - 日上限 2 GiB —— 25 MiB 的大图约 80 张就到顶。
建议：控制在 5～10 路并发，每路走完整的 presign → PUT → 创建 → 轮询再取下一张。这样 pending 数量恒定很小，也不会撞配额。配额细节见 媒体上传。