> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedream 5.5

> 透過 MixRoute 呼叫 Seedream 5.5，支援文字生圖、參考圖編輯、透明 PNG 和圖層拆分。

Seedream 5.5 是字節跳動的圖像創作與編輯模型。使用 `doubao-seedream-5-5-261028` 呼叫文字生圖、參考圖編輯、透明背景生成及可編輯圖層拆分。

`POST https://api.mixroute.ai/v1/images/generations`

向圖片生成介面傳送 JSON，請求標頭為 `Authorization: Bearer $MIXROUTE_API_KEY` 和 `Content-Type: application/json`。參數直接放在頂層，不包進 `metadata`。參考圖編輯和圖層拆分也使用這個介面，不使用 `/v1/images/edits` 或 Chat Completions。

> [!WARNING]
>
> MixRoute 的所有請求都必須提供 `prompt`，圖層拆分也不例外。即使上游範例將其標為選填，也不能省略。

## 請求參數

| 欄位 | 型別 | 說明 |
| - | - | - |
| `model` | string | 必填，使用 `doubao-seedream-5-5-261028`。 |
| `prompt` | string | 必填的生圖描述或拆分指令。支援中文、英文、日文、韓文等多語言。建議中文不超過 300 字，這是建議長度，不是強制驗證上限。 |
| `image` | string / string\[] | 生成時選填，拆分時必填。可存取的圖片 URL 或 Base64 data URL，也可用字串陣列。生成最多接受 10 張參考圖；拆分只能傳 1 張。 |
| `size` | string | 生成：`1K`、`1.5K`、`2K`（預設）或 `寬x高`。拆分：`1K`、`1.5K`、`2K`、`auto`（預設），不支援自訂像素尺寸。 |
| `output_format` | string | `png`（預設）或 `jpeg`。拆分時僅控制底圖格式，各獨立圖層一律輸出 PNG。 |
| `background` | string | 僅用於生成：`auto`（預設）、`transparent` 或 `opaque`。透明輸出必須使用 PNG。拆分時必須省略整個欄位。 |
| `response_format` | string | `url`（預設）或 `b64_json`。生成連結有效期為 24 小時，請及時儲存圖片。 |
| `watermark` | boolean | 預設 `true`，在右下角加上 AI 生成浮水印；傳 `false` 關閉。 |
| `safety_identifier` | string | 選填的終端使用者識別碼，最多 64 個字元。建議使用雜湊識別碼，不直接傳個人資訊。 |
| `layer_decomposition` | boolean | 傳 `true` 將一張輸入圖拆成底圖與透明圖層。一般生成省略或設為 `false`。 |
| `layer_decomposition_options` | object | 選填的拆分設定，僅在 `layer_decomposition` 為 `true` 時傳入。 |
| `layer_decomposition_options.max_images` | integer | 2-100 的整數，預設 30。限制包含底圖的輸出總張數，不是僅限制圖層數。 |
| `layer_decomposition_options.text_recognition` | boolean | 傳 `true` 請求規整文字圖層的富文字 OCR；並非每個圖層都會回傳 OCR。 |

## 圖片、尺寸與限制

* 一般生成每次只回傳 1 張圖片，`n` 不控制輸出數量。不支援串流、組圖或連網搜尋，請省略 `stream`、`sequential_image_generation` 及搜尋工具欄位。
* 單張參考圖不超過 30 MB，寬高比為 1:16 至 16:1。Base64 data URL 的格式名稱必須小寫，例如 `data:image/png;base64,...`。
* 生成時使用解析度級別，可在 `prompt` 中描述寬高比；使用 `寬x高` 時用小寫 `x`，總像素須為 921,600-4,624,220，寬高比為 1:16 至 16:1，例如 `2880x1440`。像素限制指寬乘高，不是單邊長度。
* 拆分只能輸入 1 張 PNG 或 JPEG，總像素不少於 262,144（512 x 512）。`size: auto` 依輸入尺寸與寬高比調整，不保證每個輸出都維持原始像素尺寸，請讀取各項 `data[].size`。
* 任一圖層失敗，整個拆分請求失敗。提示詞要求的輸出數超過 `max_images` 時，部分要求拆出的元素可能缺失。

## 請求範例

將 `MIXROUTE_API_KEY` 設定為 MixRoute Key。傳送請求前，將下方 `example.com` 輸入網址替換為可存取的圖片。

### 文字生圖

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "A lake below snowy mountains in morning mist, realistic photography, 16:9 landscape.",
  "size": "2K",
  "watermark": false
}'
```

### 多圖參考

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "Replace the clothing of the person in image 1 with the outfit in image 2.",
  "image": [
    "https://example.com/person.png",
    "https://example.com/outfit.png"
  ],
  "size": "1K"
}'
```

### 透明 PNG

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "A red ceramic mug as a clean product cutout with a transparent background.",
  "size": "1.5K",
  "output_format": "png",
  "background": "transparent",
  "response_format": "url",
  "watermark": false
}'
```

### 圖層拆分與 OCR

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "Decompose the image into separate layers: title text, person, and background.",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 8,
    "text_recognition": true
  },
  "size": "2K",
  "output_format": "png",
  "response_format": "url",
  "watermark": false
}'
```

## Python OpenAI SDK

安裝 `openai` 套件，設定 `MIXROUTE_API_KEY` 和 `SEEDREAM_IMAGE_URL`。Seedream 專有欄位及解析度值放在 SDK 的 `extra_body` 中；傳送時會合併為頂層 JSON 欄位，不會產生 `extra_body` 或 `metadata` 包裝物件。範例關閉自動重試，避免盲目重複生圖請求。

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.mixroute.ai/v1",
    api_key=os.environ["MIXROUTE_API_KEY"],
    max_retries=0,
    timeout=180.0,
)
response = client.images.generate(
    model="doubao-seedream-5-5-261028",
    prompt="Decompose the image into separate layers: title text, person, and background.",
    response_format="url",
    extra_body={
        "image": os.environ["SEEDREAM_IMAGE_URL"],
        "size": "auto",
        "layer_decomposition": True,
        "layer_decomposition_options": {"max_images": 8, "text_recognition": True},
        "output_format": "png",
        "watermark": False,
    },
)
result = response.model_dump()
if result.get("error"):
    raise RuntimeError(result["error"])
images = result.get("data")
if not images:
    raise ValueError("No output images returned")
for item in images:
    if item.get("error") or not item.get("url"):
        raise ValueError("An output image is missing or failed")
    print(item.get("z_index"), item["url"], item.get("size"))
print(result.get("usage", {}))
```

## 回傳欄位

| 欄位 | 說明 |
| - | - |
| `data[].url / data[].b64_json` | 圖片 URL 或 Base64 資料，由 `response_format` 決定。 |
| `data[].size` | `寬x高` 格式的實際像素尺寸，不同圖層可能不同。 |
| `data[].output_format` | 實際 `png` 或 `jpeg` 格式；拆出的獨立圖層一律為 PNG。 |
| `data[].background` | 實際透明狀態：`transparent` 或 `opaque`，不是請求值 `auto`。 |
| `data[].z_index` | 僅拆分回傳。底圖為 0，圖層從 1 開始，數字越大越靠上。 |
| `data[].name / data[].description` | 僅拆分回傳，由模型生成的圖層名稱和描述。 |
| `data[].bounding_box` | 僅圖層回傳，底圖不包含。`absolute` 是底圖像素座標 `[left, top, right, bottom]`，`normalized` 使用相同順序、0-1000 的相對座標。 |
| `data[].text_recognition` | 開啟 OCR 且圖層包含規整文字時回傳。包括完整文字、逐行位置與樣式，如近似字型、顏色、粗體和斜體。 |
| `usage.input_images / usage.generated_images` | 輸入圖數量和成功生成的圖片數量。拆分的生成數量包含底圖與每個獨立圖層。 |

以下為包含 1 張底圖和 1 個圖層的示意回應節錄：

```json theme={null}
{
  "data": [
    {
      "url": "https://example.com/base.png",
      "size": "2048x2048",
      "output_format": "png",
      "z_index": 0,
      "background": "opaque"
    },
    {
      "url": "https://example.com/person-layer.png",
      "size": "1647x2546",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [
          474,
          372,
          1544,
          2048
        ],
        "normalized": [
          231,
          182,
          754,
          1000
        ]
      },
      "name": "Person",
      "description": "The person standing in the center.",
      "background": "transparent"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 2
  }
}
```

## 還原圖層

以 `z_index: 0` 的底圖為畫布，依 `bounding_box.absolute` 將各圖層縮放到 `(right - left) x (bottom - top)`，放置在 `(left, top)`，再按 `z_index` 由小到大進行透明合成。圖層原生 `size` 可能與放置尺寸不同。OCR 提供文字資訊，實際文字編輯仍由你的應用程式完成。

## 計費

輸入圖和成功輸出圖分別按張計費。輸出級別依每張圖實際寬乘高決定，不只看請求中的尺寸名稱。以下美元標準價與目前公開報價一致，帳號及路由實際價格以[模型廣場](https://console.mixroute.ai/models)為準。

| 計價項 | 標準價：美元/張 |
| - | - |
| 輸入圖 | 0.0075 |
| 輸出圖不超過 2,610,000 像素 | 0.0195 |
| 輸出圖超過 2,610,000 像素 | 0.0345 |

* 每張參考圖或待拆分圖都算輸入圖。底圖和每個成功生成的圖層各算一張輸出圖，依各自像素級別計價；未成功輸出的圖不計費。
* 圖層拆分會按 `max_images` 預扣額度，完成後依實際輸出張數結算，退回未使用的預扣部分。餘額有限時可調小該上限。
* 例如：1 張輸入圖，成功輸出 3 張且每張均超過 2,610,000 像素，標準價為 `0.0075 + 3 * 0.0345 = 0.111` 美元。不同尺寸的圖層可能屬於不同價格級別，實際扣費請查看消費紀錄。

## 常見錯誤

| 欄位 | 說明 |
| - | - |
| `prompt is required` | 補上非空 `prompt`，圖層拆分也必須傳。 |
| `layer_decomposition_options.max_images must be an integer between 1 and 128` | 傳 2-100 的整數。閘道錯誤可能寫 1-128，但這不是上游實際支援範圍。 |
| `layer_decomposition must be a boolean` | 使用 JSON 布林值 `true` 或 `false`，不要傳字串。 |
| `stream: true` | 省略 `stream`，Seedream 5.5 不支援串流輸出。 |
| `output_format: jpeg + background: transparent` | 透明生成使用 PNG；拆分時省略 `background`。 |

[模型介紹](https://mixroute.ai/docs/zh-Hant/model-api/bytedance/doubao-seedream-5-5.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.