Reach APIReach API
進入 Dashboard
API ReferenceImage APIs

Seedream 接口

本平臺對外提供模型 ID 為 seedream-4-5、seedream-5-0-lite 和 seedream-5-0-pro 的異步圖片生成接口。

本文檔面向客戶端調用方，重點說明公開請求路徑、認證方式、請求參數，以及任務結果的返回契約。

說明：

  • 提交任務：POST /v1/images/create
  • 查詢任務：GET /v1/tasks/{task_id}
  • 模型 ID：seedream-4-5、seedream-5-0-lite、seedream-5-0-pro
  • 執行方式：異步任務
  • 典型場景：文生圖、圖像編輯、批量連續生成
  • 輸入圖片：僅支持通過 input.image_urls 傳 URL

1. 接口概覽

  • 請求方法：POST
  • 請求路徑：/v1/images/create
  • Content-Type：application/json
  • 結果獲取方式：
    • 提交接口只返回任務受理結果
    • 最終結果需要輪詢 /v1/tasks/{task_id}，或通過 callback_url 接收

2. 認證與請求頭

請求頭示例：

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json
請求頭必填說明
Authorization是平臺 API Key，格式：Bearer sk-xxxxxx
Content-Type是固定為 application/json

3. 提交任務

請求體示例：

{
  "model": "seedream-5-0-pro",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A premium product hero image, square composition, clean studio lighting",
    "image_urls": [],
    "resolution": "2k",
    "output_format": "png",
    "watermark": false,
    "sequential_image_generation": "disabled"
  }
}

3.1 頂層參數說明

字段類型必填說明
modelstring是固定傳 seedream-4-5、seedream-5-0-lite 或 seedream-5-0-pro
callback_urlstring否任務終態回調地址，僅支持 https，最大長度 2048，本地、內網及私網目標會被拒絕
inputobject是圖片生成參數

3.2 input 參數說明

字段類型必填說明
promptstring是生成提示詞；比例、構圖、用途等需求可寫進提示詞
image_urlsarray<string>否參考圖 URL 列表。不傳或傳空陣列表示文生圖，非空表示圖像編輯。seedream-5-0-pro 最多 10 張，其他型號最多 14 張
resolutionstring否輸出分辨率檔位。seedream-4-5 支持 2k、4k；seedream-5-0-lite 支持 2k、3k、4k；seedream-5-0-pro 支持 1k、2k，默認 2k
sizestring否輸出尺寸，優先級高於 resolution；支持模型對應的分辨率檔位或像素尺寸，如 2048x2048、3750x1250
output_formatstring否seedream-5-0-lite 和 seedream-5-0-pro 支持；可選值：png、jpeg。seedream-4-5 不支持該字段，默認輸出 JPEG
watermarkboolean否是否添加上游水印；不傳時按上游默認值處理
sequential_image_generationstring否是否啟用批量連續生成；可選值：auto、disabled；不傳時按上游默認 disabled 處理
sequential_image_generation_optionsobject否批量連續生成參數，僅在 sequential_image_generation 為 auto 時生效
optimize_prompt_optionsobject否提示詞優化參數；seedream-5-0-pro 支持 standard 和 fast，其他型號僅支持 standard

sequential_image_generation_options 參數：

字段類型必填說明
max_imagesinteger否本次最多生成圖片數；sequential_image_generation 為 auto 時取值範圍為 1 到 15；參考圖數量加 max_images 不能超過 15

optimize_prompt_options 參數：

字段類型必填說明
modestring否提示詞優化模式；standard 為默認值、偏重質量；fast 可降低延遲但可能犧牲部分質量，且僅 seedream-5-0-pro 支持

說明：

  • Seedream 不支持 input.aspect_ratio。如需比例控制，請寫進提示詞，或直接傳 input.size。
  • 平臺始終採用異步任務鏈路。
  • 任務結果主契約為 data[].url。
  • 本地圖片請先調用 POST /v1/images/uploads 上傳，再將返回的 URL 填入 input.image_urls。
  • 即使 Pro 上游模型直接支持 Base64，Base64 圖片輸入也不屬於 ReachAPI 的公開接口契約。

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": "seedream-4-5",
    "input": {
      "prompt": "A quiet ceramic tea cup on a wooden table, square composition, soft morning light",
      "resolution": "2k",
      "watermark": false
    }
  }'

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": "seedream-5-0-lite",
    "input": {
      "prompt": "A premium skincare bottle hero image, 4:5 vertical poster composition, clean studio lighting",
      "resolution": "3k",
      "output_format": "png",
      "watermark": false
    }
  }'

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": "seedream-4-5",
    "input": {
      "prompt": "Turn this sneaker photo into a clean e-commerce hero image, keep the original product shape",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "2k"
    }
  }'

4.4 自定義尺寸請求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "A wide cinematic concept art image for a sci-fi city skyline",
      "size": "3750x1250",
      "output_format": "jpeg"
    }
  }'

4.5 批量連續生成請求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "Create a coherent set of 4 product lifestyle images for the same perfume bottle",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "2k",
      "sequential_image_generation": "auto",
      "sequential_image_generation_options": {
        "max_images": 4
      }
    }
  }'

4.6 提示詞優化請求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "input": {
      "prompt": "A restaurant poster for a summer tasting menu",
      "resolution": "2k",
      "optimize_prompt_options": {
        "mode": "fast"
      }
    }
  }'

4.7 Seedream 5.0 Pro 交互式編輯

seedream-5-0-pro 支持通過自然語言描述輸入圖上的手繪標記來指定局部編輯區域。如需更精確的位置控制，可在提示詞中使用 <point> 或 <bbox> 坐標標籤。

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "input": {
      "prompt": "使用圖 2 中 <bbox>118 331 933 871</bbox> 的主體，替換圖 1 中 <bbox>179 283 796 986</bbox> 的主體。",
      "image_urls": [
        "https://cdn.example.com/base-image.png",
        "https://cdn.example.com/subject-reference.png"
      ],
      "resolution": "2k",
      "output_format": "png",
      "watermark": false
    }
  }'

坐標標籤用於說明編輯區域和目標位置，不能替代 image_urls。仍需按提示詞引用順序傳入對應圖片。

5. 提交響應

響應示例：

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

字段說明：

字段類型說明
codeinteger平臺業務狀態碼
msgstring錯誤或狀態信息
statusstring初始任務狀態，通常為 queued
task_idstring任務唯一 ID，後續用於查詢
dataarray提交階段為空陣列

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/image-1.jpeg"
    }
  ]
}

失敗響應示例：

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

說明：

  • 返回主契約是 data[].url。
  • 批量連續生成可能返回多張圖片，按 data[] 陣列承載。
  • 如果批量任務中部分圖片被上游內容過濾或生成失敗，平臺只返回成功生成的圖片；如果沒有任何成功圖片，任務失敗。

7. 回調說明

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

回調約束：

  • 僅支持 https 地址
  • 最大長度 2048
  • localhost、.local 以及明顯的私網目標會被拒絕
  • 單次投遞超時 10s
  • 失敗後最多重試 2 次，總計最多投遞 3 次

8. 參數約束與不支持字段

  • prompt 不能為空
  • seedream-5-0-pro 的 image_urls 最多 10 張；seedream-4-5 和 seedream-5-0-lite 最多 14 張
  • image_urls 必須是服務端可訪問的 https URL
  • seedream-5-0-pro 輸入格式支持 jpeg、png、webp、bmp、tiff、gif、heic、heif
  • Pro 每張輸入圖：文件不超過 30MB；寬、高均須大於 14px；寬高比在 1/16 到 16 之間；總像素不超過 36,000,000（6000x6000）
  • seedream-4-5 的 resolution 可選 2k、4k
  • seedream-5-0-lite 的 resolution 可選 2k、3k、4k
  • seedream-5-0-pro 的 resolution 可選 1k、2k，默認 2k
  • size 可傳模型支持的分辨率檔位或 <width>x<height> 格式的像素尺寸
  • seedream-5-0-pro 使用自定義像素 size 時，總像素須在 921,600（1280x720）到 4,624,220（2048x2048x1.1025）之間，寬高比須在 1/16 到 16 之間
  • seedream-4-5 和 seedream-5-0-lite 使用自定義像素 size 時，總像素須在 2560x1440 到 4096x4096 之間，寬高比須在 1/16 到 16 之間
  • sequential_image_generation 只允許 auto、disabled
  • seedream-5-0-pro 的 optimize_prompt_options.mode 可選 standard、fast；其他型號僅允許 standard
  • seedream-5-0-pro 的交互式編輯支持在 prompt 中使用自由標記及 <point> / <bbox> 坐標標籤
  • 上游生成圖片 URL 僅保留 24 小時，請及時下載或持久化保存
  • watermark 必須是 boolean

公開接口不支持的輸入字段包括：

  • input.image_base64s
  • 任意圖片輸入字段中的 Base64 圖片數據
  • input.aspect_ratio
  • input.system_prompt
  • input.enable_web_search
  • input.stream
  • input.response_format
  • input.seed
  • input.guidance_scale
  • input.n
  • input.quality
  • input.background
  • input.moderation
  • input.negative_prompt

GPT Image 2 異步圖片接口

Previous Page

nanobanana 接口

Next Page

On this page

1. 接口概覽
2. 認證與請求頭
3. 提交任務
3.1 頂層參數說明
3.2 input 參數說明
4. 請求示例
4.1 文生圖請求
4.2 指定輸出格式的文生圖請求
4.3 圖像編輯請求
4.4 自定義尺寸請求
4.5 批量連續生成請求
4.6 提示詞優化請求
4.7 Seedream 5.0 Pro 交互式編輯
5. 提交響應
6. 查詢任務
7. 回調說明
8. 參數約束與不支持字段