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

# GPT Image 2.5 异步图像生成

> 提交 GPT Image 2.5 异步任务并轮询获取图片。

使用 `gpt-image-2.5-async` 提交异步生成任务。提交接口与同步生成相同，通过模型名区分调用方式；成功提交后立即返回任务 ID。

## 提交任务

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl --request POST \
    --url https://xcompute.us/v1/images/generations \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-image-2.5-async",
      "prompt": "未来城市夜景，电影感灯光，无文字",
      "size": "1536x1024",
      "quality": "medium"
    }'
  ```

  ```python Python theme={null} theme={null}
  import requests

  response = requests.post(
      "https://xcompute.us/v1/images/generations",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "gpt-image-2.5-async",
          "prompt": "未来城市夜景，电影感灯光，无文字",
          "size": "1536x1024",
          "quality": "medium",
      },
      timeout=30,
  )
  response.raise_for_status()
  print(response.json()["id"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null} theme={null}
  {
    "id": "task_AVzfphDDvLn189o8FyF07uEzx1skzfJP",
    "status": "queued",
    "mode": "generate",
    "model": "gpt-image-2.5-async",
    "size": "1536x1024",
    "quality": "medium",
    "created_at": "2026-09-11 03:33:10"
  }
  ```
</ResponseExample>

保存响应中的 `id`，后续用于查询任务结果。

## 查询任务

使用任务 ID 调用 `GET /v1/tasks/{task_id}`：

```bash cURL theme={null} theme={null}
curl --request GET \
  --url https://xcompute.us/v1/tasks/task_AVzfphDDvLn189o8FyF07uEzx1skzfJP \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

<ResponseExample>
  ```json 200 theme={null} theme={null}
  {
    "status": "completed",
    "task_id": "task_AVzfphDDvLn189o8FyF07uEzx1skzfJP",
    "progress": "100%",
    "result_url": "https://example.com/generated-image.png",
    "result": {
      "items": [
        {
          "id": "task_AVzfphDDvLn189o8FyF07uEzx1skzfJP",
          "status": "success",
          "data": [
            {
              "url": "https://example.com/generated-image.png"
            }
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>

优先读取顶层 `result_url`。如果该字段为空，可以读取 `result.items[0].data[0].url`。

## 支持尺寸

异步调用的 `size` 仅支持以下值：

| 档位   | 支持的 `size`                                                                                                                                      |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 标准   | `1024x1024`、`1536x1024`、`1024x1536`、`1024x1365`、`1365x1024`、`1088x1920`、`1920x1088`                                                             |
| 高分辨率 | `2048x2048`、`1712x2560`、`2560x1712`、`2048x1536`、`1152x2048`、`2048x1152`、`2880x2880`、`2560x3840`、`3840x2560`、`3840x2880`、`2160x3840`、`3840x2160` |

## 状态说明

| 顶层 `status`   | 含义      | 处理方式                      |
| ------------- | ------- | ------------------------- |
| `queued`      | 任务已进入队列 | 继续轮询                      |
| `in_progress` | 任务正在执行  | 继续轮询                      |
| `completed`   | 任务执行完成  | 读取 `result_url`           |
| `failed`      | 任务执行失败  | 读取 `error` 或结果项中的 `error` |
| `cancelled`   | 任务已取消   | 停止轮询                      |

## 接入建议

* 每 3 到 5 秒查询一次，最长等待 10 分钟。
* 停止轮询不会取消服务端任务。
* 不要调用 `/v1/images/generations/async` 或 `/api/image-tasks/generations`，它们不是当前客户接口。
* 异步调用使用 `gpt-image-2.5-async`。