> ## 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 は ByteDance の画像生成・編集モデルです。`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`。生成 URL の有効期間は 24 時間です。早めに画像を保存してください。 |
| `watermark` | boolean | 既定値は `true`。右下に AI 生成の透かしを付けます。`false` で無効にします。 |
| `safety_identifier` | string | 任意のエンドユーザー識別子。最大 64 文字です。個人情報ではなくハッシュ化した識別子を推奨します。 |
| `layer_decomposition` | boolean | `true` で 1 枚の画像をベース画像と透過レイヤーに分解します。通常の生成では省略するか `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 リクエスト 1 枚です。`n` では出力数を変更できません。ストリーミング、連続画像生成、ウェブ検索は非対応のため、`stream`、`sequential_image_generation`、検索ツールのフィールドは省略します。
* 参照画像は 1 枚 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` は有効です。制限は幅と高さの積であり、各辺の長さではありません。
* 分解には総ピクセル数 262,144（512 x 512）以上の PNG または JPEG を 1 枚指定します。`size: auto` は入力の寸法とアスペクト比に応じて調整するため、全出力が元のピクセル寸法を保つとは限りません。各 `data[].size` を確認してください。
* いずれかのレイヤー生成に失敗すると分解リクエスト全体が失敗します。`max_images` を超える出力を指示すると、指定した要素の一部が欠けることがあります。

## リクエスト例

`MIXROUTE_API_KEY` に MixRoute のキーを設定します。送信前に、以下の `example.com` の入力 URL をアクセス可能な画像 URL に置き換えてください。

### テキストから画像を生成

```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` | `response_format` に応じた画像 URL または Base64 データ。 |
| `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 は文字情報を返すもので、実際の文字編集はアプリケーション側で行います。

## 課金

入力画像と正常に出力された画像を、それぞれ枚数で課金します。出力の料金区分は、指定したサイズ名だけでなく各画像の実際の幅と高さの積で決まります。以下は現在の公開価格と一致する標準 USD 料金です。アカウントとルートの実際の価格は[モデルマーケットプレイス](https://console.mixroute.ai/models)を優先してください。

| 項目 | 標準 USD / 枚 |
| - | - |
| 入力画像 | 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` USD です。サイズが異なるレイヤーには別の料金区分が適用される場合があります。実際の請求額は使用ログで確認してください。

## よくあるエラー

| フィールド | 説明 |
| - | - |
| `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/ja/model-api/bytedance/doubao-seedream-5-5.md)


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