Appearance
异步生图
异步生图适合大尺寸图片、复杂提示词和容易超过普通 HTTP 等待时间的请求。客户端提交后会立即获得任务 ID，不需要一直保持生成请求的连接。
文生图和图片编辑都支持异步模式：
| 功能 | 提交接口 | 请求体 |
|---|---|---|
| 文生图 | POST /v1/images/generations | application/json |
| 图片编辑 / 图生图 | POST /v1/images/edits | multipart/form-data |
| 查询任务 | GET /v1/images/generations/{task_id} | 无 |
查询地址
图片编辑任务也使用 /v1/images/generations/{task_id} 查询。目前没有 /v1/images/edits/{task_id} 查询接口。
使用前提
- 使用正常的词元 API Key，通过
Authorization: Bearer $API_KEY鉴权。 - 对应模型必须有已开启异步生图的可用渠道。
- 请求必须带
Prefer: respond-async，否则仍按同步图片接口处理。 - 建议不要同时开启
stream；平台托管的异步任务会关闭流式输出。
异步文生图
请求地址：
http
POST /v1/images/generationscurl 示例：
bash
curl https://code.ciyuanapi.xyz/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Prefer: respond-async" \
-d '{
"model": "gpt-image-2",
"prompt": "一只橘猫坐在窗边，柔和自然光，写实摄影风格",
"size": "1024x1024",
"quality": "standard",
"n": 1
}'异步图片编辑
请求地址：
http
POST /v1/images/edits图片文件仍然通过 multipart/form-data 上传：
bash
curl https://code.ciyuanapi.xyz/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-H "Prefer: respond-async" \
-F "model=gpt-image-2" \
-F "image=@./input.png" \
-F "prompt=把背景换成干净的白色摄影棚，主体保持不变" \
-F "size=1024x1024"需要蒙版时可以继续增加：
bash
-F "mask=@./mask.png"部分模型支持多张输入图片，但支持数量和字段形式取决于所选模型及渠道。建议先按单张 image 文件完成接入。
提交响应
服务端接受任务后返回 HTTP 202 Accepted，并带有两个响应头：
http
Location: /v1/images/generations/task_xxx
Preference-Applied: respond-async响应体示例：
json
{
"id": "task_xxx",
"object": "image.generation.task",
"status": "queued",
"created_at": 1785758400,
"progress": "10%"
}Location 是相对地址，应与提交任务时使用的域名组合。也可以直接读取响应体中的 id 构造查询地址。
查询任务
使用同一账号下的有效 API Key 查询。通常直接继续使用提交任务时的 API Key：
bash
curl https://code.ciyuanapi.xyz/v1/images/generations/task_xxx \
-H "Authorization: Bearer $API_KEY"建议每 2 至 5 秒查询一次，进入 completed 或 failed 后停止轮询。progress 是阶段性进度，不保证连续递增。
任务状态
| 状态 | 说明 |
|---|---|
queued | 任务已提交或正在排队 |
in_progress | 正在生成或保存图片 |
completed | 任务成功，可读取 data |
failed | 任务失败，可读取 error |
成功响应
json
{
"id": "task_xxx",
"object": "image.generation.task",
"status": "completed",
"created_at": 1785758400,
"progress": "100%",
"data": [
{
"url": "https://code3.ciyuanapi.xyz/api/async-images/random-name.png",
"revised_prompt": ""
}
]
}图片实际保存在哪个节点，就可能返回哪个节点的域名。客户端不应自行替换结果 URL 的域名。
失败响应
任务执行失败时，查询接口仍返回 HTTP 200，通过 status 和 error 表示结果：
json
{
"id": "task_xxx",
"object": "image.generation.task",
"status": "failed",
"created_at": 1785758400,
"progress": "100%",
"error": {
"message": "image provider request failed",
"type": "image_generation_failed",
"code": "image_generation_failed"
}
}JavaScript 轮询示例
js
const baseURL = "https://code.ciyuanapi.xyz"
const apiKey = process.env.CIYUAN_API_KEY
const submit = await fetch(`${baseURL}/v1/images/generations`, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
Prefer: "respond-async",
},
body: JSON.stringify({
model: "gpt-image-2",
prompt: "一座漂浮在云海上的未来城市",
size: "1024x1024",
n: 1,
}),
})
if (submit.status !== 202) {
throw new Error(await submit.text())
}
const task = await submit.json()
while (true) {
await new Promise((resolve) => setTimeout(resolve, 3000))
const response = await fetch(
`${baseURL}/v1/images/generations/${task.id}`,
{ headers: { Authorization: `Bearer ${apiKey}` } },
)
const result = await response.json()
if (result.status === "completed") {
console.log(result.data)
break
}
if (result.status === "failed") {
throw new Error(result.error?.message || "异步生图失败")
}
}图片保存时间
- 成功图片会暂存在词元 API 服务器，并以 URL 形式返回。
- 图片文件保留 6 小时，请在有效期内下载到自己的存储。
- 图片过期后 URL 返回
404；任务记录仍可能显示completed。 - 单张临时图片最大 20 MB，仅保存 PNG、JPEG 和 WebP。
- 需要长期展示时，不要把临时 URL 直接永久写入业务数据库，应下载后转存到自己的对象存储。
计费与失败
- 提交任务时会预留预计额度或订阅请求次数。
- 任务最终失败时，系统会退还对应额度或请求次数。
- 固定价格模型可能在任务完成后按实际返回图片数量结算差额。
限制与常见错误
| 情况 | 结果 |
|---|---|
未带 Prefer: respond-async | 按同步图片接口处理 |
| 没有开启异步的可用渠道 | 请求失败，不会创建任务 |
原生异步渠道传 response_format=b64_json | HTTP 400 |
| 托管异步队列已满 | HTTP 503，请稍后重试 |
| 任务不存在或不属于当前账号 | HTTP 404，错误码 task_not_found |
| 查询任务失败 | HTTP 500，错误码 task_query_failed |
当前不提供异步图片任务的主动取消接口。客户端应在本地停止轮询或忽略不再需要的任务，但已提交的服务端任务仍可能继续执行和计费。