GPT Image 2.5 圖片接口

ReachAPI 同時透過 OpenAI 相容的同步圖片接口和 ReachAPI 異步任務接口提供 GPT Image 2.5 Flare 與 Sunburst。兩個產品目前均處於 Internal Preview。

• gpt-image-2.5-flare：適合快速、高品質的日常圖片生成。
• gpt-image-2.5-sunburst：適合更重視最高能力與編輯精度的工作流。

1. 選擇接口

• 同步生成：POST https://direct.reachapi.ai/v1/images/generations
• 同步編輯：POST https://direct.reachapi.ai/v1/images/edits
• 異步任務：POST https://direct.reachapi.ai/v1/images/create
• 查詢異步任務：GET https://direct.reachapi.ai/v1/tasks/{task_id}

調用方可以等待完整響應並希望使用 OpenAI 原生請求與響應結構時，使用同步 Image API。長時間任務、URL 參考圖、輪詢、回調以及從 data[].url 取得託管結果時，使用異步任務 API。

兩種方式使用相同的模型碼和認證：

Authorization: Bearer YOUR_REACH_API_KEY

2. 同步 Image API

同步端點遵循 OpenAI Image API 契約。圖片生成使用 JSON 請求；圖片編輯使用一個或多個圖片檔案組成的原生 multipart 表單。

生成圖片

curl -X POST "https://direct.reachapi.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "銀色腕錶置於深灰色石板上的精緻產品攝影，柔和棚拍光線",
    "size": "1536x1024",
    "quality": "high",
    "background": "auto",
    "moderation": "auto",
    "output_format": "png"
  }'

編輯圖片

curl -X POST "https://direct.reachapi.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=保持腕錶結構不變，只將背景替換為深色拉絲金屬" \
  -F "image[]=@/path/to/watch.png" \
  -F "size=1536x1024" \
  -F "quality=xhigh" \
  -F "output_format=png"

不要手動設定 multipart boundary；客戶端、SDK 或 curl -F 會自動生成。

同步接口契約

• 使用 model、prompt、size、quality、background、moderation、output_format 等扁平 OpenAI 欄位，不要包在 input 中。
• 文生圖使用 POST /v1/images/generations；基於檔案的圖片編輯使用 POST /v1/images/edits。
• 同步端點返回 OpenAI 原生 Images 響應，不返回 ReachAPI task_id，也不支援任務輪詢或 callback_url。
• mask、多圖編輯以及完整參數和響應契約以 OpenAI 相容端點為準。

3. 異步任務 API

異步端點使用嵌套的 { "model": "...", "input": { ... } } 請求，並立即返回任務 ID。

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.5-flare",
    "callback_url": "https://example.com/reachapi/callback",
    "input": {
      "prompt": "銀色腕錶置於深灰色石板上的精緻產品攝影，柔和棚拍光線",
      "resolution": "2k",
      "aspect_ratio": "3:2",
      "quality": "high",
      "background": "auto",
      "moderation": "auto",
      "output_format": "png"
    }
  }'

頂層參數

input 參數

background=transparent 不能與 output_format=jpeg 同時使用。

標準尺寸映射

所需組合不在表中時，請直接使用 input.size。

異步圖片編輯

傳入 input.image_urls 即可編輯或轉換參考圖：

{
  "model": "gpt-image-2.5-sunburst",
  "input": {
    "prompt": "保持腕錶結構不變，只將背景替換為深色拉絲金屬",
    "image_urls": ["https://cdn.example.com/watch.png"],
    "resolution": "2k",
    "aspect_ratio": "3:2",
    "quality": "xhigh",
    "output_format": "png"
  }
}

任務結果與回調

提交成功後返回任務 ID：

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

輪詢 GET /v1/tasks/{task_id}，直到狀態變為 success 或 failed。成功任務會在 data[].url 返回圖片，也可能附帶 size 與 revised_prompt。

傳入 callback_url 後，ReachAPI 會將終態響應發送至該 HTTPS 地址。單次投遞逾時 10 秒，首次失敗後最多重試 2 次。

異步接口約束

• prompt 必填且不能為空。
• image_urls 最多接收 14 個 HTTPS URL；不支援 base64 圖片輸入。
• 該異步接口不開放 n > 1、mask、output_compression 和 user。
• 未傳 size 時，resolution + aspect_ratio 必須命中標準映射表。

4. 價格

同步與異步方式使用相同的 GPT Image 2.5 Standard Token 價格。ReachAPI 僅計算以下三項：

Flare 與 Sunburst 使用相同的 Token 單價。模型、品質、尺寸、提示詞和參考圖都可能改變 Token 用量，因此單張圖片的實際費用可能不同。

5. 可用性與官方參考

兩個 GPT Image 2.5 模型碼均處於 Internal Preview，可能不會出現在 GET /v1/models。

• OpenAI 圖片生成指南
• OpenAI Images API 參考
• OpenAI 價格