图像生成（异步接口）

本文档介绍本网关提供的 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

若对象存储未配置，调用异步接口会直接返回错误（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_<ULID>（示例：image_01KCRVET35FAVZME1CEEED9VBS）

任务状态与轮询

查询接口返回的 status 可能为：

pending：排队中
in_progress：执行中
completed：已完成（可读取 data[].url）
failed：失败（返回 error.code / error.message）

建议轮询策略：

interval: 3–10 秒
timeout: 5–15 分钟（取决于服务负载情况与图片分辨率）

文生图：创建 + 轮询示例

1) 创建任务

curl -X POST "https://models.phanedge.cloud/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"
  }'

响应示例：

{
  "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"
}

task_id 为兼容字段，等同于 id。

2) 轮询查询结果

curl -X GET "https://models.phanedge.cloud/v1/images/generations/image_01KCRVET35FAVZME1CEEED9VBS" \
  -H "Authorization: Bearer $TOKEN"

完成态响应示例：

{
  "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" }
  ]
}

失败态响应示例：

{
  "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：

{
  "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
    }
  }
}

只有已按 token 完成结算的 no-image 失败任务会返回 usage。普通失败任务仍只返回 error，不会附带 usage。任务只能由创建该任务的用户查询，不能通过任务 ID 读取其他用户的 usage。

改图：创建 + 轮询示例

改图异步任务仅支持 Gemini 图像模型（gemini-*-image*），Imagen 暂不支持编辑。

创建改图任务使用 multipart/form-data：

curl -X POST "https://models.phanedge.cloud/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：

curl -X POST "https://models.phanedge.cloud/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"

轮询接口：

curl -X GET "https://models.phanedge.cloud/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/*/async
- response_format 固定为 url（传入 b64_json 会被忽略）
- 强制要求对象存储（S3/AliOSS），返回 24h 临时 URL

若你只需要 OpenAI 风格同步调用，请参考《图像生成 (OpenAI 风格)》。若使用 gpt-image-2 或 gpt-image-2-plus，请参考《OpenAI 图像生成》中的异步图片任务章节。

快速开始

文本与多模态

图像生成

视频生成

帮助

适用范围

前置条件：对象存储（必需）

接口列表

任务状态与轮询

文生图：创建 + 轮询示例

1) 创建任务

2) 轮询查询结果

改图：创建 + 轮询示例

与同步接口的关系

​适用范围

​前置条件：对象存储（必需）

​接口列表

​任务状态与轮询

​文生图：创建 + 轮询示例

​1) 创建任务

​2) 轮询查询结果

​改图：创建 + 轮询示例

​与同步接口的关系

适用范围

前置条件：对象存储（必需）

接口列表

任务状态与轮询

文生图：创建 + 轮询示例

1) 创建任务

2) 轮询查询结果

改图：创建 + 轮询示例

与同步接口的关系