API Reference · 图像生成 API

图像生成 API

使用 gpt-image-2 异步生成图像：创建任务、轮询状态、读取结果。结果以 b64_json 返回，并在 30 分钟 TTL 窗口内一次性投递。

概览

图像生成是一个异步任务：POST /images/generations/async 会立即返回任务 ID，然后轮询 GET /images/generations/{id}，直到 status 变为 completed。完成响应中的 data 数组会包含每张图片的 b64_json。

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

GET https://api.alltoken.ai/v1/images/models - 列出可用图像模型
POST https://api.alltoken.ai/v1/images/generations/async - 创建生成任务
GET https://api.alltoken.ai/v1/images/generations/{id} - 轮询任务状态

结果是一次性投递：第一次读取 completed 响应后，服务端会删除临时文件。请在首次收到结果时立即持久化 b64_json。任务会在 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	}

请求参数

model （必填） - 图像模型 ID，当前为 gpt-image-2
prompt （必填） - 描述目标图像的文本
size - 输出尺寸：1024x1024 / 1536x1024 / 1024x1536 / auto
quality - low / medium / high / auto，控制推理预算和单图成本
output_format - png / jpeg / webp
background - auto / opaque
moderation - auto（默认，推荐）/ low（更低限制；用户需自行承担内容合规责任）

获取任务状态

GET

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

返回任务详情。当 status 为 completed 时，data 数组会包含每张生成图片的 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	"b64_json": "iVBORw0KGgo...",
14	"revised_prompt": "A clean studio product photo of a clear borosilicate glass teapot..."
15	}
16	],
17	"usage": {
18	"input_tokens": 24,
19	"output_tokens": 1290,
20	"total_tokens": 1314
21	}
22	}

一次性投递：第一次成功读取 completed 响应后，服务端会删除临时图像文件。请立即持久化 b64_json。再次轮询会返回 410 image_already_retrieved。

任务状态值

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

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

错误响应

400 - 请求错误，例如 prompt 为空或 size 无效
401 - API Key 无效或缺失
402 - 余额不足
404 - 任务 ID 不存在
409 - Idempotency-Key 对应的任务仍在进行中，或另一个请求正在领取完成结果
410 - 任务已过期（30 分钟 TTL 已过）或结果已被读取
429 - 触发速率限制，请遵守 Retry-After 响应头