SeeDream Images Generation API 對接說明

本文將介紹一種 SeeDream Images Generation API 對接說明，它是可以通過輸入自定義參數來生成 SeeDream 官方的圖片。

申請流程

要使用 SeeDream Images Generation API，首先到 Ace Data Cloud 控制台獲取您的 API Token，留作備用。

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台充值通用餘額。

📘 完整文檔：SeeDream Images Generation API →

基本使用

首先先了解下基本的使用方式，就是輸入提示詞 prompt、生成行為 action、圖片尺寸 size，便可獲得處理後的結果，首先需要簡單地傳遞一個 action 字段，它的值為 generate，然後我們還需要輸入提示詞，具體的內容如下：

可以看到這裡我們設置了 Request Headers，包括：

accept：想要接收怎樣格式的響應結果，這裡填寫為 application/json，即 JSON 格式。
authorization：調用 API 的密鑰，申請之後可以直接下拉選擇。

另外設置了 Request Body，包括：

prompt：提示詞。
model：生成模型，默認 doubao-seedream-5-0-260128（SeeDream 5.0 Lite，最新）。支持 doubao-seedream-5-0-pro-260628、doubao-seedream-5-0-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828、doubao-seedream-3-0-t2i-250415、doubao-seededit-3-0-i2i-250628。其中 doubao-seedream-5-0-pro-260628（SeeDream 5.0 Pro）為旗艦單圖模型，僅生成單圖，不支持組圖（sequential_image_generation）、流式（stream）與聯網搜索（tools）。model 必須傳入完整模型串（如 doubao-seedream-5-0-260128），傳 doubao-seedream-5.0-lite 這類簡寫會返回 400。
image: 輸入的圖片信息，支持 URL 或 Base64 編碼。其中，doubao-seedream-5-0-pro-260628 支持單圖或多圖輸入（多圖 2-10 張，第 2 張起按張計費），doubao-seedream-5-0-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 支持單圖或多圖輸入，doubao-seededit-3-0-i2i-250628 僅支持單圖輸入，doubao-seedream-3-0-t2i-250415 不支持該參數。
size: 指定生成圖像的尺寸信息，支持以下兩種方式，不可混用。方式 1 | 指定生成圖像的分辨率，並在 prompt 中用自然語言描述圖片寬高比。各模型支持的預設不同：doubao-seedream-5-0-pro-260628 支持 1K/2K；doubao-seedream-5-0-260128 支持 2K/3K/4K；doubao-seedream-4-5-251128 僅支持 2K/4K；doubao-seedream-4-0-250828 支持 1K/2K/4K；doubao-seedream-3-0-t2i-250415 與 doubao-seededit-3-0-i2i-250628 不支持預設，僅接受方式 2。方式 2 | 指定生成圖像的寬高像素值：默認 2048x2048，總像素與寬高比取值範圍隨模型不同（例如 5.0 Pro 總像素範圍 [921600, 4194304]，5.0 Lite / 4.5 總像素下限 3,686,400，4.0 下限 921,600，3.0-t2i / seededit-3.0-i2i 範圍 [512x512, 2048x2048]）。
seed: 隨機數種子，用於控制模型生成內容的隨機性。取值範圍為 [-1, 2147483647]。僅 doubao-seedream-3-0-t2i-250415 支持該參數。
sequential_image_generation: 組圖：基於您輸入的內容，生成的一組內容關聯的圖片。doubao-seedream-5-0-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 支持該參數，默認 disabled。
stream: 控制是否開啟流式輸出模式。doubao-seedream-5-0-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 支持該參數，默認是 false。
guidance_scale: 模型輸出結果與 prompt 的一致程度，值越大相關性越強。取值範圍 [1, 10]。doubao-seedream-3-0-t2i-250415 默認值 2.5，doubao-seededit-3-0-i2i-250628 默認值 5.5，其他模型不支持。
response_format: 指定生成圖像的返回格式。默認是 url，也支持 b64_json。
watermark: 是否在生成的圖片中添加水印。默認是 true。
output_format: 指定生成圖像的文件格式，支持 jpeg（默認）和 png。僅 doubao-seedream-5-0-pro-260628 和 doubao-seedream-5-0-260128 支持。
tools: 配置模型要調用的工具，目前支持 web_search（聯網搜索）。僅 doubao-seedream-5-0-260128 支持。
callback_url：需要回調結果的 URL。
async：是否以異步模式處理。設為 true 時接口立即返回 task_id，無需提供 callback_url，隨後通過 /seedream/tasks 輪詢獲取結果。

選擇之後，可以發現右側也生成了對應代碼，如圖所示：

點擊「Try」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果：

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "一瓶霧面玻璃香水瓶在濕潤的黑色板岩上的寫實工作室產品拍攝，單一柔光箱主光，水滴，黑暗陰鬱的背景，85mm 微距。",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

返回結果一共有多個字段，介紹如下：

success，此時視頻生成任務的狀態情況。
task_id，此時視頻生成任務 ID。
trace_id，此時視頻生成跟蹤 ID。
data，此時圖像生成任務的結果列表。
- image_url，此時圖片生成任務的鏈接。
- prompt，提示詞。
- size: 生成圖的像素

可以看到我們得到了滿意的圖片信息，我們只需要根據結果中 data 的圖片鏈接地址獲取生成的 SeeDream 圖片即可。另外如果想生成對應的對接代碼，可以直接複製生成，例如 CURL 的代碼如下：

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-260128",
  "prompt": "一瓶霧面玻璃香水瓶在濕潤的黑色板岩上的寫實工作室產品拍攝，單一柔光箱主光，水滴，黑暗陰鬱的背景，85mm 微距。"
}'

編輯圖片任務

如果想對某張圖片進行編輯的話，首先參數image必須傳入需要編輯的圖片鏈接

model：此次編輯圖片任務所採用的模型，doubao-seedream-5-0-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 支持單圖或多圖輸入，doubao-seededit-3-0-i2i-250628 僅支持單圖輸入。
image：上傳需要編輯的圖片，一張或者多張

填寫樣例如下：

對應的代碼：

import requests

url = "https://api.acedata.cloud/flux/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "保持模型姿勢和液體服裝流動形狀不變。將衣物材料從銀色金屬改為完全透明的水（或玻璃）。通過液體流動，模型皮膚的細節可見。光影效果從反射轉變為折射。",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

點擊運行，可以發現會立即得到一個結果，如下：

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "保持模型姿勢和液體服裝流動形狀不變。將衣物材料從銀色金屬改為完全透明的水（或玻璃）。通過液體流動，模型皮膚的細節可見。光影效果從反射轉變為折射。",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

可以看到，生成的效果是對原圖片進行編輯的效果，結果與上文類似。

異步回調

由於 SeeDream Images Generation API 生成的時間相對較長，大約需要 1-2 分鐘，如果 API 長時間無響應，HTTP 請求會一直保持連接，導致額外的系統資源消耗，所以本 API 也提供了異步回調的支持。整體流程是：客戶端發起請求的時候，額外指定一個 callback_url 字段，客戶端發起 API 請求之後，API 會立馬返回一個結果，包含一個 task_id 的字段信息，代表當前的任務 ID。當任務完成之後，生成圖片的結果會通過 POST JSON 的形式發送到客戶端指定的 callback_url，其中也包括了 task_id 字段，這樣任務結果就可以通過 ID 關聯起來了。如果你沒有可供回調的公網地址，也可以不指定 callback_url，而是在請求中設置 async 字段為 true。此時接口同樣會立即返回 task_id，但不會推送結果，你需要攜帶該 task_id 調用 /seedream/tasks 接口輪詢任務狀態來獲取最終結果。下面我們通過示例來了解下具體怎樣操作。點擊運行，可以發現會立即得到一個結果，如下：

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

內容如下：

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "保持模型姿勢和液體服裝流動形狀不變。將衣物材料從銀色金屬改為完全透明的水（或玻璃）。通過液體流動，模型皮膚的細節可見。光影效果從反射轉變為折射。",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

可以看到結果中有一個 task_id 字段，其他的字段都和上文類似，通過該字段即可實現任務的關聯。

錯誤處理

在調用 API 時，如果遇到錯誤，API 會返回相應的錯誤代碼和信息。例如：

400 token_mismatched：錯誤請求，可能是由於缺少或無效的參數。
400 api_not_implemented：錯誤請求，可能是由於缺少或無效的參數。
401 invalid_token：未授權，無效或缺少授權令牌。
429 too_many_requests：請求過多，你已超過速率限制。
500 api_error：內部伺服器錯誤，伺服器出現問題。

錯誤響應示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "獲取失敗"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

通过本文档，您已经了解了如何使用 SeeDream Images Generation API 可通过输入提示词来生成图片。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

代理

進階

SeeDream Images Generation API 對接說明

申請流程

基本使用

編輯圖片任務

異步回調

錯誤處理

錯誤響應示例

結論

​申請流程

​基本使用

​編輯圖片任務

​異步回調

​錯誤處理

​錯誤響應示例

​結論

申請流程

基本使用

編輯圖片任務

異步回調

錯誤處理

錯誤響應示例

結論