跳轉到主要內容
本文將介紹一種 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-4.0。
  • image: 輸入的圖片信息，支持 URL 或 Base64 編碼。其中，doubao-seedream-4.5、doubao-seedream-4.0 支持單圖或多圖輸入，doubao-seededit-3.0-i2i 僅支持單圖輸入，doubao-seededit-3.0-t2i 不支持該參數。
  • size: 指定生成圖像的尺寸信息，支持以下兩種方式，不可混用。方式 1 | 指定生成圖像的分辨率，並在prompt中用自然語言描述圖片寬高比、圖片形狀或圖片用途，最終由模型判斷生成圖片的大小。方式 2 | 指定生成圖像的寬高像素值：默認值：2048x2048 根據模型不同默認值不同。
  • seed: 隨機數種子，用於控制模型生成內容的隨機性。取值範圍為 [-1, 2147483647]。僅 doubao-seedream-3.0-t2i、doubao-seededit-3.0-i2i 支持該參數。
  • sequential_image_generation: 組圖：基於您輸入的內容，生成的一組內容關聯的圖片。僅 doubao-seedream-4.5、doubao-seedream-4.0 支持該參數，默認 disabled。
  • stream: 控制是否開啟流式輸出模式。僅 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。
  • 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.acedata.cloud/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.acedata.cloud/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-4.5、doubao-seedream-4.0 支持單圖或多圖輸入，doubao-seededit-3.0-i2i 僅支持單圖輸入。
  • 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": "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": "保持模型姿势和液体服装流动形状不变。将衣物材料从银色金属更改为完全透明的水（或玻璃）。通过液体流动，可以看到模型皮肤的细节。光影效果从反射转变为折射。",
            "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 关联起来了。 下面我们通过示例来了解下具体怎样操作。 点击运行，可以发现会立即得到一个结果，如下： 
{
  "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。如有任何问题，请随时联系我们的技术支持团队。