SeeDream Images Generation API 對接說明

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

申請流程

要使用 API，需要先到 SeeDream Images Generation API 對應頁面申請對應的服務，進入頁面之後，點擊「Acquire」按鈕，如圖所示：

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。在首次申請時會有免費額度贈送，可以免費使用該 API。

基本使用

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

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

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

另外設定了 Request Body，包括：

prompt：提示詞。
model：生成模型，預設 doubao-seedream-5.0-lite。支援 doubao-seedream-5.0-lite（最新）、doubao-seedream-4.5、doubao-seedream-4.0、doubao-seedream-3.0-t2i、doubao-seededit-3.0-i2i。
image: 輸入的圖片資訊，支援 URL 或 Base64 編碼。其中，doubao-seedream-5.0-lite、doubao-seedream-4.5、doubao-seedream-4.0 支援單圖或多圖輸入，doubao-seededit-3.0-i2i 僅支援單圖輸入，doubao-seedream-3.0-t2i 不支援該參數。
size: 指定生成圖像的尺寸資訊，支援以下兩種方式，不可混用。方式 1 | 指定生成圖像的解析度，並在 prompt 中用自然語言描述圖片寬高比。各模型支援的預設不同：doubao-seedream-5.0-lite 支援 2K/3K/4K；doubao-seedream-4.5 僅支援 2K/4K；doubao-seedream-4.0 支援 1K/2K/4K；doubao-seedream-3.0-t2i 與 doubao-seededit-3.0-i2i 不支援預設，僅接受方式 2。方式 2 | 指定生成圖像的寬高像素值：預設 2048x2048，總像素與寬高比取值範圍隨模型不同（例如 5.0 / 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 支援該參數。
sequential_image_generation: 組圖：基於您輸入的內容，生成的一組內容關聯的圖片。doubao-seedream-5.0-lite、doubao-seedream-4.5、doubao-seedream-4.0 支援該參數，預設 disabled。
stream: 控制是否開啟串流輸出模式。doubao-seedream-5.0-lite、doubao-seedream-4.5、doubao-seedream-4.0 支援該參數，預設是 false。
guidance_scale: 模型輸出結果與 prompt 的一致程度，值越大相關性越強。取值範圍 [1, 10]。doubao-seedream-3.0-t2i 預設值 2.5，doubao-seededit-3.0-i2i 預設值 5.5，其他模型不支援。
response_format: 指定生成圖像的返回格式。預設是 url，也支援 b64_json。
watermark: 是否在生成的圖片中添加浮水印。預設是 true。
output_format: 指定生成圖像的檔案格式，支援 jpeg（預設）和 png。僅 doubao-seedream-5.0-lite 支援。
tools: 配置模型要調用的工具，目前支援 web_search（聯網搜尋）。僅 doubao-seedream-5.0-lite 支援。
callback_url：需要回調結果的 URL。

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

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

{
  "success": true,
  "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}

返回結果一共有多個欄位，介紹如下：

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

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

curl -X POST 'https://api.xhuoapi.ai/v1/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-4-0-250828",
  "prompt": "a white siamese cat"
}'

編輯圖片任務

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

model：此次編輯圖片任務所採用的模型，doubao-seedream-5.0-lite、doubao-seedream-4.5、doubao-seedream-4.0 支援單圖或多圖輸入，doubao-seededit-3.0-i2i 僅支援單圖輸入。
image：上傳需要編輯的圖片，一張或者多張

填寫範例如下：

對應的程式碼：

import requests

url = "https://api.xhuoapi.ai/v1/flux/images"

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

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "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": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.xhuoapi.ai/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 關聯起來了。下面我們透過範例來了解下具體怎樣操作。點擊執行，可以發現會立即得到一個結果，如下：

{
  "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": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

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

錯誤處理

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

400 token_mismatched：Bad request，可能由於缺少或無效參數。
400 api_not_implemented：Bad request，可能由於缺少或無效參數。
401 invalid_token：Unauthorized，無效或缺少授權令牌。
429 too_many_requests：Too many requests，您已超過速率限制。
500 api_error：Internal server error，伺服器端發生錯誤。

錯誤響應範例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

透過本文檔，您已經了解了如何使用 SeeDream Images Generation API 可透過輸入提示詞來生成圖片。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支援團隊。

Documentation Index

​申請流程

​基本使用

​編輯圖片任務

​非同步回調

​錯誤處理

​錯誤響應範例

​結論