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

# 图像生成（异步接口）

使用异步任务接口创建 Gemini 图像生成任务，通过 `GET` 轮询获取 24 小时有效的图片 URL。适用于耗时较长的 2K / 4K 高清生成场景。

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

异步图片任务强制要求配置对象存储（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}` |

**Base URL**：`https://api.gregapi.com`

### 认证方式

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

### 任务 ID 格式

* 格式：`image_<ULID>`，示例：`image_01KCRVET35FAVZME1CEEED9VBS`
* `task_id` 为兼容字段，等同于 `id`

## 文生图：创建任务

```bash theme={null}
curl -X POST "https://api.gregapi.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 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"
}
```

轮询查询：

```bash theme={null}
curl -X GET "https://api.gregapi.com/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": "任务执行失败，请稍后重试"
  }
}
```

no-image 已计费失败响应（额外返回 usage）：

```json theme={null}
{
  "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
    }
  }
}
```

## 改图：创建任务

请求方式：multipart/form-data

```bash theme={null}
curl -X POST "https://api.gregapi.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"
```

或传入 URL：

```bash theme={null}
curl -X POST "https://api.gregapi.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"
```

改图异步任务仅支持 Gemini 图像模型，响应格式与文生图任务查询完全相同。

## 任务状态

| 状态 | 含义 |
| - | - |
| `pending` | 排队中 |
| `in_progress` | 执行中 |
| `completed` | 已完成，可读取 `data[].url` |
| `failed` | 失败，返回 `error.code` / `error.message` |

## 轮询策略

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

## 与同步接口的关系

| 特性 | 同步接口 | 异步接口 |
| - | - | - |
| 端点 | `/v1/images/generations`、`/v1/images/edits` | `/v1/images/*/async` |
| `response_format` | 可选 `b64_json` 或 `url` | 固定 `url`（传入 `b64_json` 会被忽略） |
| 对象存储 | 返回 URL 时需要配置 storage | 强制要求 S3/AliOSS，返回 24h 临时 URL |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.