Appearance
图像生成(异步接口)
使用 /v1/images/*/async 创建任务,并通过 GET 轮询获取图片 URL(适用于 Gemini/Imagen 和 GPT Image 模型)
本文档介绍本网关提供的 Sora 风格图片异步任务接口:创建任务后,通过轮询查询任务状态获取最终图片 URL。
适用范围
- Gemini 图像模型:
gemini-3-pro-image-preview、gemini-2.5-flash-image、gemini-2.5-flash-image-preview(含同系列分辨率 SKU) - Imagen 系列(仅文生图):
imagen-* - OpenAI 图像模型:
gpt-image-2、gpt-image-2-plus - 异步接口返回的图片为 URL(24 小时有效),不返回
b64_json
前置条件:对象存储(必需)
异步图片任务强制要求配置对象存储(S3 或 AliOSS)用于:
- 上传生成图片
- 返回 24 小时有效的临时签名 URL
INFO
若对象存储未配置,调用异步接口会直接返回错误(error.code=storage_not_configured)。
接口列表
- 创建文生图任务:
POST /v1/images/generations/async - 创建改图任务:
POST /v1/images/edits/async - 查询任务状态:
GET /v1/images/generations/{id}/GET /v1/images/edits/{id}
任务 ID 统一为:
image_(示例:image_01KCRVET35FAVZME1CEEED9VBS)
任务状态与轮询
查询接口返回的 status 可能为:
pending:排队中in_progress:执行中completed:已完成(可读取data[].url)failed:失败(返回error.code/error.message)
建议轮询策略:
interval: 3–10 秒timeout: 5–15 分钟(取决于服务负载情况与图片分辨率)
文生图:创建 + 轮询示例
1) 创建任务
bash
curl -X POST "https://aiapi.fhddos.com/v1/images/generations/async" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"prompt": "A futuristic cityscape at sunset with flying cars",
"n": 1,
"size": "1024x1024",
"response_format": "url"
}'响应示例:
json
{
"id": "image_01KCRVET35FAVZME1CEEED9VBS",
"task_id": "image_01KCRVET35FAVZME1CEEED9VBS",
"object": "image.generation",
"created_at": 1700000000,
"status": "pending",
"progress": 0,
"model": "gemini-3-pro-image-preview",
"prompt": "A futuristic cityscape at sunset with flying cars"
}INFO
task_id 为兼容字段,等同于 id。
2) 轮询查询结果
bash
curl -X GET "https://aiapi.fhddos.com/v1/images/generations/image_01KCRVET35FAVZME1CEEED9VBS" \
-H "Authorization: Bearer $TOKEN"完成态响应示例:
json
{
"id": "image_01KCRVET35FAVZME1CEEED9VBS",
"task_id": "image_01KCRVET35FAVZME1CEEED9VBS",
"object": "image.generation",
"created_at": 1700000000,
"status": "completed",
"progress": 100,
"completed_at": 1700000066,
"expires_at": 1700086466,
"model": "gemini-3-pro-image-preview",
"data": [
{ "url": "https://example.com/signed-url.png" }
]
}失败态响应示例:
json
{
"id": "image_01KCRVET35FAVZME1CEEED9VBS",
"task_id": "image_01KCRVET35FAVZME1CEEED9VBS",
"object": "image.generation",
"created_at": 1700000000,
"status": "failed",
"progress": 0,
"error": {
"code": "task_failed",
"message": "任务执行失败,请稍后重试"
}
}当失败原因是可计费的 Gemini no-image 结果时,查询响应会额外返回 usage:
json
{
"id": "image_01KTKZBMH71ZBPHKJXJJ3R1076",
"task_id": "image_01KTKZBMH71ZBPHKJXJJ3R1076",
"object": "image.generation",
"created_at": 1780934365,
"status": "failed",
"progress": 0,
"error": {
"code": "no_image_generated",
"message": "no image generated"
},
"usage": {
"prompt_tokens": 353,
"completion_tokens": 0,
"input_tokens": 353,
"output_tokens": 0,
"total_tokens": 353,
"input_tokens_details": {
"cached_tokens": 0,
"text_tokens": 95,
"image_tokens": 258,
"audio_tokens": 0
}
}
}INFO
只有已按 token 完成结算的 no-image 失败任务会返回 usage。普通失败任务仍只返回 error,不会附带 usage。任务只能由创建该任务的用户查询,不能通过任务 ID 读取其他用户的 usage。
改图:创建 + 轮询示例
INFO
改图异步任务仅支持 Gemini 图像模型(gemini-*-image*),Imagen 暂不支持编辑。
创建改图任务使用 multipart/form-data:
bash
curl -X POST "https://aiapi.fhddos.com/v1/images/edits/async" \
-H "Authorization: Bearer $TOKEN" \
-F "model=gemini-3-pro-image-preview" \
-F "prompt=将这张图片转换为油画风格" \
-F "response_format=url" \
-F "image=@/path/to/image.png"也可通过 image_urls[] 传入图片 URL:
bash
curl -X POST "https://aiapi.fhddos.com/v1/images/edits/async" \
-H "Authorization: Bearer $TOKEN" \
-F "model=gemini-3-pro-image-preview" \
-F "prompt=将这张图转换为油画风格(URL 参考图)" \
-F "response_format=url" \
-F "image_urls[]=https://example.com/base.png" \
-F "image_urls[]=https://example.com/style-ref.png"轮询接口:
bash
curl -X GET "https://aiapi.fhddos.com/v1/images/edits/{id}" \
-H "Authorization: Bearer $TOKEN"与同步接口的关系
- 同步接口:
POST /v1/images/generations、POST /v1/images/edits- 可选择
response_format=b64_json或response_format=url - 若要求
url但上游只返回 base64,则需要配置 storage 才能上传并生成 URL
- 可选择
- 异步接口:
POST /v1/images/*/asyncresponse_format固定为url(传入b64_json会被忽略)- 强制要求对象存储(S3/AliOSS),返回 24h 临时 URL
TIP
若你只需要 OpenAI 风格同步调用,请参考《图像生成 (OpenAI 风格)》。若使用 gpt-image-2 或 gpt-image-2-plus,请参考《OpenAI 图像生成》中的异步图片任务章节。