Documentation
API Reference / 图像生成 API
Interactive API
API Reference · 图像生成 API

图像生成 API

异步图像生成、编辑（图生图 & mask）与变体：创建任务、轮询状态、读取结果。返回持久化 r2_url 加一次性 b64_json，任务 30 分钟 TTL。

概览

所有图像操作都是异步任务：POST 会立即返回任务 ID，然后轮询 GET /images/generations/{id}，直到 status 变为 completed。三类任务共用这一个轮询端点：

  • 文生图 — POST /images/generations/async（仅 prompt）
  • 图像编辑（图生图 & mask） — POST /images/edits（源图 + prompt，mask 可选）
  • 图像变体 — POST /images/variations（仅源图）

编辑和变体都需要输入图像。推荐路径先通过 POST /uploads/presign 把图像直传到 R2，再把返回的 upload_id 以 JSON 提交，避免大图片字节穿过网关。旧 multipart/form-data 路径保留兼容。

使用 GET /images/models 获取实时模型列表。完整 schema 和约束请查看 交互式 API 参考。

端点用途
GET https://api.alltoken.ai/v1/images/models列出可用图像模型
POST https://api.alltoken.ai/v1/uploads/presign为输入图像 / mask 签发 R2 直传 presign
POST https://api.alltoken.ai/v1/images/generations/async创建文生图任务
POST https://api.alltoken.ai/v1/images/edits创建图像编辑任务（i_edit / mask_edit）
POST https://api.alltoken.ai/v1/images/variations创建图像变体任务
GET https://api.alltoken.ai/v1/images/generations/{id}轮询任务状态 / 领取结果

优先使用 r2_url 而非 b64_json：completed 响应会同时返回两者，但 b64_json 已弃用且仅首次读取返回（之后临时文件即被删除）。r2_url 是公开 URL，至少保留 30 天且可跨刷新访问。任务本身会在 30 分钟 后过期。

列出图像模型

GET
$GET https://api.alltoken.ai/v1/images/models

以 OpenAI 兼容格式返回所有可用的图像生成模型。

响应 JSON
1{
2 "object": "list",
3 "data": [
4 { "id": "gpt-image-2", "object": "model", "owned_by": "openai" }
5 ]
6}

创建图像生成任务

POST
$POST https://api.alltoken.ai/v1/images/generations/async

请求头:

  • Authorization: Bearer <API_KEY> - 必填
  • Idempotency-Key: <uuid> - 可选但推荐。服务端会在短窗口内去重；用相同 key 重试会返回原任务。
请求体 JSON
1{
2 "model": "gpt-image-2",
3 "prompt": "A clean product photo of a glass teapot on a walnut table, soft natural light",
4 "size": "1024x1024",
5 "quality": "high",
6 "output_format": "png",
7 "background": "auto",
8 "moderation": "auto"
9}

响应（任务已创建，状态为 queued）:

响应 JSON
1{
2 "id": "igen_a7b68c38c4b7832ee386a13e",
3 "status": "queued",
4 "model": "gpt-image-2",
5 "created_at": "2026-05-12T08:00:00Z"
6}

请求参数

以下参数用于 POST /images/generations/async 请求体。图像编辑（/images/edits）接受相同的 n / size / quality / output_format / output_compression / background / moderation 字段。

  • model （必填） - 图像模型 ID。文生图可用 gpt-image-2、wan2.7-image 或 wan2.7-image-pro；调用 GET /images/models 获取实时列表
  • prompt （必填） - 描述目标图像的文本（最长 32000 字符）
  • n - 单次生成张数，1-10（默认 1）
  • size - auto 或 WIDTHxHEIGHT。自 gpt-image-2 起支持任意分辨率（每边 16 整除、最大 3840x2160、比例 1:3 ~ 3:1），如 1024x1024 / 1536x1024 / 1024x1536
  • quality - low / medium / high / auto，控制推理预算和单图成本
  • output_format - png / jpeg / webp
  • output_compression - 0-100，仅 jpeg / webp 生效（上游默认 100）
  • background - auto / opaque / transparent
  • moderation - auto（默认，推荐）/ low（更低限制；用户需自行承担内容合规责任）

上传输入图像

图像编辑和变体需要一张源图（mask 可选）。推荐流程用预签名 URL 把每个文件直传到 R2，再提交其 upload_id——让大字节绕过网关和 Cloudflare 边缘。

第 1 步 — 申请预签名 URL：

POST
$POST https://api.alltoken.ai/v1/uploads/presign
请求体 JSON
1{
2 "purpose": "image_edit_source",
3 "content_type": "image/png",
4 "content_length": 524288,
5 "content_md5": "1B2M2Y8AsgTpgAmY7PhCfg==",
6 "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
7}
  • purpose （必填） - image_edit_source、image_edit_mask 或 image_variation_source。提交任务时会再次校验 purpose，不能跨用途复用
  • content_type （必填） - image/png / image/jpeg / image/webp（须落在 purpose 白名单内；bind 时服务端会复核真实类型）
  • content_length （必填） - 上传字节数；不同 purpose 有独立上限（在 max_content_length 回显）
  • content_md5 （必填） - Base64 MD5；R2 PUT 必须携带同值 Content-MD5
  • checksum_sha256 （必填） - 小写十六进制 SHA-256，bind 时用于服务端一致性校验
响应 JSON
1{
2 "upload_url": "https://r2.alltoken.ai/inputs/upl_2f8bb7d7f4a24c3a8f4f8a7e?signature=...",
3 "method": "PUT",
4 "required_headers": {
5 "Content-Type": "image/png",
6 "Content-MD5": "1B2M2Y8AsgTpgAmY7PhCfg=="
7 },
8 "upload_id": "upl_2f8bb7d7f4a24c3a8f4f8a7e",
9 "expires_in": 300,
10 "claim_expires_at": "2026-05-15T05:00:00Z",
11 "max_content_length": 26214400
12}

第 2 步 — 把文件 PUT 到 R2，使用 upload_url 并带上完全一致的 required_headers。预签名 URL 在 expires_in 秒内有效（当前为 300）：

cURL
$curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  -H "Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==" \
  --data-binary @teapot.png

第 3 步 — 提交 upload_id 给 /images/edits 或 /images/variations（见下）。未绑定的上传在 presign 后约 2 小时删除；已绑定的输入在任务成功 / 失败 / 取消后立即删除。只提交 upload_id——调试用的 public_url 不能作为任务输入。

编辑图像（图生图 & mask）

基于一张必填源图加 prompt 创建图生图任务。不提供 mask 时按整图编辑（i_edit）处理；提供 mask 时按局部编辑（mask_edit）处理——mask 的透明像素即编辑区。

POST
$POST https://api.alltoken.ai/v1/images/edits

推荐 — JSON + 已上传输入（先按上文 presign 源图 / mask）：

请求体 JSON（application/json）
1{
2 "model": "gpt-image-2",
3 "prompt": "Replace the sky with a dramatic sunset",
4 "image_upload_id": "upl_2f8bb7d7f4a24c3a8f4f8a7e",
5 "mask_upload_id": "upl_9c1aa0e2b7d3490f8e2c1a55",
6 "size": "1024x1024",
7 "quality": "high",
8 "output_format": "png"
9}
  • model （必填） - 如 gpt-image-2
  • prompt （必填） - 编辑提示词（最长 32000 字符）
  • image_upload_id （必填） - 来自 purpose=image_edit_source presign 的 upload_id
  • mask_upload_id - 可选；来自 purpose=image_edit_mask presign 的 upload_id。提供后任务切换为 mask_edit
  • n - 生成张数，1-10（默认 1）
  • size、quality、output_format、output_compression、background、moderation - 同文生图（见“请求参数”）

旧路径 — multipart/form-data（保留兼容；大 body 可能触发 413 / 边缘 challenge）。发送 model、prompt、二进制 image 字段，以及可选的二进制 mask 字段。源图和 mask 各 ≤ 25MB，MIME image/png / image/jpeg / image/webp。

响应（202，任务已创建） - 任务 ID 前缀为 igen_iedit_（i_edit）或 igen_mask_（mask_edit）；用 GET /images/generations/{id} 轮询：

响应 JSON
1{
2 "id": "igen_iedit_a7b68c38c4b7832ee386a13e",
3 "status": "queued",
4 "model": "gpt-image-2",
5 "created_at": "2026-05-15T03:00:00Z"
6}

图像变体

基于一张必填源图创建变体。不接受 prompt 或 mask。变体仅对支持该能力的模型有效（如 dall-e-2）；不支持的模型由上游返回 4xx 并透传到网关。

POST
$POST https://api.alltoken.ai/v1/images/variations
请求体 JSON（application/json）
1{
2 "model": "dall-e-2",
3 "image_upload_id": "upl_2f8bb7d7f4a24c3a8f4f8a7e",
4 "size": "1024x1024"
5}
  • model （必填） - 支持变体的模型，如 dall-e-2
  • image_upload_id （必填） - 来自 purpose=image_variation_source presign 的 upload_id
  • size - auto / 1024x1024 / 1536x1024 / 1024x1536

旧 multipart/form-data 路径用二进制 image 字段（≤ 25MB）替代 image_upload_id。返回任务 ID 前缀为 igen_ivar_；用 GET /images/generations/{id} 轮询。

获取任务状态

GET
$GET https://api.alltoken.ai/v1/images/generations/{id}

返回任务详情。该端点服务所有任务类型（文生图、编辑、变体）。当 status 为 completed 时，data 数组会包含每张图片的持久化 r2_url 以及一次性的 b64_json（按请求的 output_format 返回 PNG/JPEG/WebP 的 base64 编码）。

响应 JSON（completed）
1{
2 "id": "igen_a7b68c38c4b7832ee386a13e",
3 "status": "completed",
4 "model": "gpt-image-2",
5 "created": 1778572818,
6 "completed_at": "2026-05-12T08:00:18Z",
7 "expires_at": "2026-05-12T08:30:18Z",
8 "size": "1024x1024",
9 "quality": "high",
10 "output_format": "png",
11 "data": [
12 {
13 "r2_url": "https://r2.alltoken.ai/images/igen_a7b68c38.png",
14 "r2_url_expires_at": "2026-06-11T08:00:18Z",
15 "mime_type": "image/png",
16 "b64_json": "iVBORw0KGgo...",
17 "revised_prompt": "A clean studio product photo of a clear borosilicate glass teapot..."
18 }
19 ],
20 "usage": {
21 "input_tokens": 24,
22 "output_tokens": 1290,
23 "total_tokens": 1314
24 }
25}

优先用 r2_url；b64_json 一次性：首次读取 completed 会同时返回两者，但 b64_json 已弃用且读取后临时文件立即删除。r2_url 是公开 URL，至少保留 30 天（到 r2_url_expires_at 为止），且后续每次读取都会返回。若 R2 上传失败则没有 r2_url——请保留首次拿到的 b64_json；无 R2 兜底时再次读取返回 410 image_already_retrieved，r2_url 过期则返回 410 image_expired。

任务状态值

  • queued - 已入队，等待 GPU
  • processing - 模型正在生成
  • completed - 已完成；data[].b64_json 可读取一次
  • failed - 生成失败，详情见 error
  • cancelled - 完成前被取消

推荐轮询间隔：1-3 秒。多数任务会在 8-25 秒完成；高质量 1536x1024 任务可能需要 30-60 秒。

错误响应

  • 400 - 请求错误，例如 prompt 为空或 size 无效
  • 401 - API Key 无效或缺失
  • 402 - API 用量额度不足
  • 404 - 任务 ID 不存在
  • 409 - Idempotency-Key 对应的任务仍在进行中，或另一个请求正在领取完成结果
  • 410 - 任务已过期（30 分钟 TTL 已过）或结果已被读取
  • 413 - 上传文件过大（multipart 路径下源图或 mask > 25MB）
  • 429 - 触发速率限制，请遵守 Retry-After 响应头
  • 503 - 网关 R2 存储未配置，或上游存储不可用