GPT Image 2 異步圖片接口

ReachAPI 提供 GPT Image 2 的任務式圖片接口。需要任務狀態查詢、終態回調，以及從 data[].url 讀取最終圖片地址時，請使用本文檔說明的異步接口。

異步接口使用公開調用碼 gpt-image-2-async。該調用碼僅用於 POST /v1/images/create。OpenAI Image API 兼容接口的 /v1/images/generations 和 /v1/images/edits 仍使用 gpt-image-2。

1. 接口概覽

提交任務：POST https://direct.reachapi.ai/v1/images/create
查詢任務：GET https://direct.reachapi.ai/v1/tasks/{task_id}
調用碼：gpt-image-2-async
執行方式：異步任務
結果字段：data[].url

請求頭：

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

2. 提交任務

請求體：

{
  "model": "gpt-image-2-async",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A children's book drawing of a veterinarian using a stethoscope to listen to a small animal.",
    "resolution": "1k",
    "aspect_ratio": "2:3",
    "quality": "medium",
    "background": "auto",
    "moderation": "auto",
    "output_format": "png"
  }
}

2.1 頂層參數

字段	類型	必填	說明
`model`	string	是	固定傳 `gpt-image-2-async`
`callback_url`	string	否	任務終態回調地址。僅支持 `https`，最大長度 `2048`，本地、內網及私網目標會被拒絕
`input`	object	是	圖片生成參數

2.2 `input` 參數

字段	類型	必填	說明
`prompt`	string	是	文生圖或圖像編輯提示詞
`image_urls`	`array<string>`	否	參考圖 URL 列表。不傳或傳空數組表示文生圖，非空表示圖像編輯，最多 14 張
`size`	string	否	精確輸出尺寸，例如 `1024x1536`。如傳入，則優先於 `resolution + aspect_ratio`
`resolution`	string	否	標準分辨率檔位。可選值：`1k`、`2k`、`4k`。不傳時默認 `1k`
`aspect_ratio`	string	否	標準畫面比例。可選值：`1:1`、`3:2`、`2:3`。不傳時默認 `1:1`
`quality`	string	否	質量檔位。可選值：`low`、`medium`、`high`。不傳時默認 `medium`
`background`	string	否	背景模式。可選值：`auto`、`opaque`、`transparent`。`gpt-image-2` 不支持 `transparent`
`moderation`	string	否	審核模式。可選值：`auto`、`low`
`output_format`	string	否	輸出格式偏好。可選值：`png`、`jpeg`、`webp`

說明：

input.size 優先於 resolution + aspect_ratio
input.size 的最長邊必須小於或等於 3840px，兩條邊都必須是 16px 的倍數，長邊與短邊比例不能超過 3:1，總像素數必須不少於 655,360 且不超過 8,294,400
background=transparent 不能與 output_format=jpeg 同時使用
如果需要使用本地圖片，請先上傳為可訪問的 HTTPS URL，再傳入 input.image_urls

2.3 標準尺寸映射

`resolution + aspect_ratio`	輸出尺寸
`1k + 1:1`	`1024x1024`
`1k + 3:2`	`1536x1024`
`1k + 2:3`	`1024x1536`
`2k + 1:1`	`2048x2048`
`2k + 3:2`	`2048x1152`
`4k + 3:2`	`3840x2160`
`4k + 2:3`	`2160x3840`

如果組合不在表格內，請使用 input.size 指定精確輸出尺寸。

3. 計費規則

異步任務接口按本次請求歸一後的 resolution + quality 固定按次計費。

quality 大小寫不敏感，會歸一為 low、medium、high；不傳時默認 medium。

`quality`	`1k`	`2k`	`4k`
`low`	`$0.010`	`$0.020`	`$0.030`
`medium`	`$0.060`	`$0.120`	`$0.180`
`high`	`$0.220`	`$0.440`	`$0.660`

計費用的分辨率按以下方式確定：

如果傳入 input.size，會按寬高像素數映射為 1k、2k 或 4k
如果未傳 input.size，使用 input.resolution；未傳時默認 1k

4. 請求示例

4.1 文生圖

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "An editorial fashion photo of a silver handbag on a reflective pedestal, soft studio lighting",
      "resolution": "4k",
      "aspect_ratio": "2:3",
      "quality": "high",
      "output_format": "png"
    }
  }'

4.2 自定義尺寸

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "A fashion poster with a tall custom composition",
      "size": "2336x3504",
      "quality": "high",
      "output_format": "png"
    }
  }'

4.3 圖像編輯

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "Turn this sneaker photo into a premium e-commerce hero shot with a clean studio background",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "1k",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "jpeg"
    }
  }'

5. 提交響應

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

字段	類型	說明
`code`	integer	平臺業務狀態碼
`msg`	string	狀態或錯誤信息
`status`	string	初始任務狀態，通常為 `queued`
`task_id`	string	任務 ID，後續用於查詢結果
`data`	array	提交階段為空數組

6. 查詢任務

請求：

curl -X GET "https://direct.reachapi.ai/v1/tasks/task_xxx" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY"

狀態說明：

狀態	說明
`queued`	已受理，等待執行
`generating`	生成中
`success`	生成成功
`failed`	生成失敗

成功響應：

{
  "code": 200,
  "msg": "",
  "status": "success",
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://cdn.example.com/generated/gpt-image-2.png",
      "size": "1024x1536",
      "revised_prompt": "A children's book illustration of a veterinarian using a stethoscope."
    }
  ],
  "cost": {
    "spend": 0.12
  }
}

失敗響應：

{
  "code": 500,
  "msg": "Model service request failed",
  "status": "failed",
  "task_id": "task_xxx",
  "data": []
}

7. 回調說明

如果提交任務時傳了 callback_url，ReachAPI 會在任務進入 success 或 failed 後向該地址發送 POST 請求。回調 body 與任務查詢接口的響應結構一致。

回調約束：

僅支持 HTTPS 地址
最大長度 2048
localhost、.local、私網和本地 IP 目標會被拒絕
單次投遞超時 10s
失敗後最多重試 2 次，總計最多投遞 3 次

8. 參數約束

prompt 必填，且不能為空字符串
image_urls 僅支持服務端可訪問的 HTTPS URL
image_urls 最多 14 張
不支持 image_base64s
不支持 n > 1
此異步接口不支持 mask
不支持 output_compression
不支持 user
size 必須使用像素尺寸，最長邊不超過 3840px，兩條邊都是 16px 的倍數，長邊與短邊比例不超過 3:1，總像素數介於 655,360 到 8,294,400 之間
resolution 支持 1k、2k、4k
標準映射模式下，aspect_ratio 支持 1:1、3:2、2:3
若未傳 size，則 resolution + aspect_ratio 必須命中標準尺寸映射表
quality 支持 low、medium、high
background、moderation、output_format 需要按文檔枚舉值傳入
background=transparent 不支持 output_format=jpeg

GPT Image 2 異步圖片接口

On this page