> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 图像生成（异步接口）

> 使用 /v1/images/*/async 创建任务，并通过 GET 轮询获取图片 URL（适用于 Gemini/Imagen 生图模型）

本文档介绍本网关提供的 **Sora 风格**图片异步任务接口：创建任务后，通过轮询查询任务状态获取最终图片 URL。

## 适用范围

* Gemini 图像模型：`gemini-3-pro-image-preview`、`gemini-2.5-flash-image`、`gemini-2.5-flash-image-preview`（含同系列分辨率 SKU）
* Imagen 系列（仅文生图）：`imagen-*`
* 异步接口返回的图片为 **URL（24 小时有效）**，不返回 `b64_json`

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

异步图片任务强制要求配置对象存储（S3 或 AliOSS）用于：

* 上传生成图片
* 返回 **24 小时有效**的临时签名 URL

<Note>
  若对象存储未配置，调用异步接口会直接返回错误（`error.code=storage_not_configured`）。
</Note>

## 接口列表

* 创建文生图任务：`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) 创建任务

```bash theme={null}
curl -X POST "$BASE_URL/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 theme={null}
{
  "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"
}
```

<Note>
  `task_id` 为兼容字段，等同于 `id`。
</Note>

### 2) 轮询查询结果

```bash theme={null}
curl -X GET "$BASE_URL/v1/images/generations/image_01KCRVET35FAVZME1CEEED9VBS" \
  -H "Authorization: Bearer $TOKEN"
```

完成态响应示例：

```json theme={null}
{
  "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 theme={null}
{
  "id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "task_id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "object": "image.generation",
  "created_at": 1700000000,
  "status": "failed",
  "progress": 0,
  "error": {
    "code": "task_failed",
    "message": "任务执行失败，请稍后重试"
  }
}
```

## 改图：创建 + 轮询示例

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

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

```bash theme={null}
curl -X POST "$BASE_URL/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 theme={null}
curl -X POST "$BASE_URL/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 theme={null}
curl -X GET "$BASE_URL/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

<Tip>
  若你只需要 OpenAI 风格同步调用，请参考《[图像生成 (OpenAI 风格)](/gemini/images-openai)》。
</Tip>