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

# Seedream-5.0-Pro 画像生成

> Seedream 5.0 Pro モデルで高品質な画像を生成します。1K/2K 解像度に対応

<Note>
  **中国本土のユーザー向け：** 中国本土のユーザーは `https://toapis.cn` を API エンドポイント（Base URL）としてご利用ください。本ドキュメント内の例では `https://toapis.com` を `https://toapis.cn` に置き換えてください。
</Note>

* ByteDance Seed チームが開発した Seedream 5.0 Pro 高品質画像生成モデル
* model パラメータで `doubao-seedream-5-0-pro` モデルを選択
* パラメータは `Seedream-5.0` とほぼ同じで、Pro は **1K** と **2K** の解像度に対応する点が異なります
* テキストから画像生成、画像から画像生成、複数参考画像などの生成モードに対応
* **課金ルール**：1 枚目の参考画像は無料で、2 枚目の参考画像から通常どおり課金されます
* 非同期タスク管理で、タスク ID から結果を照会

<Warning>
  **重要な変更**：より良いパフォーマンスとコスト管理のため、`image_urls` に base64 の画像データを直接渡すことはサポートしなくなりました。先に [Upload 画像API](../../uploads/images) で画像をアップロードし、URL を取得してから本エンドポイントを呼び出してください。
</Warning>

## Authorizations

<ParamField header="Authorization" type="string" required>
  すべてのエンドポイントで Bearer Token による認証が必要です

  API Key の取得：[API Key 管理ページ](https://toapis.com/console/token) から API Key を取得します

  使用時はリクエストヘッダーに次を追加します：

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" default="doubao-seedream-5-0-pro" required>
  画像生成モデル名

  例：`"doubao-seedream-5-0-pro"`
</ParamField>

<ParamField body="prompt" type="string" required>
  画像生成のテキスト記述
</ParamField>

<ParamField body="size" type="string" default="1:1">
  画像のアスペクト比

  `layer_decomposition` を有効にすると、このフィールドは解像度プリセット `1K` または `2K` を直接受け取ります。

  対応するアスペクト比：

  * `1:1` - 正方形（デフォルト）
  * `4:3` - 横向き 4:3
  * `3:4` - 縦向き 3:4
  * `16:9` - 横ワイド
  * `9:16` - 縦長
  * `3:2` - 横向き 3:2
  * `2:3` - 縦向き 2:3
  * `21:9` - 超ワイド
  * `9:21` - 超縦長
</ParamField>

<ParamField body="n" type="integer" default={1}>
  生成する画像の枚数

  範囲：1〜10（最小 1 枚、最大 10 枚）

  デフォルト：1

  **注意：**

  * 参考画像 + 生成画像の合計枚数は 15 枚以下にしてください
  * **必ず数値のみ（例：`1`）を入力し、引用符を付けないでください。引用符を付けるとエラーになります**

  生成枚数と参考画像の枚数に基づいて事前に課金されます。そのうち 1 枚目の参考画像は無料です
</ParamField>

<ParamField body="layer_decomposition" type="boolean" default={false}>
  Seedream 5.0 Pro 専用のレイヤー分解機能を有効にするかどうか。

  * `false`：通常のフラットな画像を返します（デフォルト）
  * `true`：ベース画像と、透明チャンネルを持つ複数の独立した PNG レイヤーを返します

  有効にすると、タスク照会結果の各 `result.data[]` 項目に `z_index` も返されます。独立したレイヤーではさらに `bounding_box`、`name`、`description` も返されます。このパラメータは Seedream 5.0 Pro のみに対応します。
</ParamField>

<ParamField body="image_urls" type="string[]">
  画像から画像生成または画像編集に使用する参考画像の URL リスト

  **⚠️ URL 形式のみ対応（base64 は非対応）**

  * 公開アクセス可能な画像 URL（http\:// または https\://）
  * [Upload 画像API](../../uploads/images) でローカル画像をアップロードし、URL を取得できます

  **制限：**

  * 画像枚数：1〜10 枚
  * 画像形式：jpeg、png
  * アスペクト比（幅/高さ）の範囲：\[1/3, 3]
  * 幅と高さ（px）> 14
  * サイズ：10MB 以下
  * 総ピクセル数：6000×6000 px 以下

  **課金について：**

  * 1 枚目の参考画像は無料
  * 2 枚目の参考画像から通常どおり課金
</ParamField>

<ParamField body="metadata" type="object">
  チャネル固有のパラメータ。Seedream 5.0 Pro モデルの高度な設定を渡すために使用します

  <Expandable title="metadata のプロパティ">
    <ParamField body="metadata.resolution" type="string" default="2K">
      画像の解像度

      対応する解像度：

      * `1K` - 基本解像度
      * `2K` - 標準解像度（デフォルト）

      > **注意：** Seedream 5.0 Pro は 3K と 4K の解像度に対応していません。Pro 以外の Seedream 5.0 は 2K と 3K に対応します
    </ParamField>

    <ParamField body="metadata.sequential_image_generation" type="string" default="disabled">
      順次画像生成モード（Doubao 専用機能）

      複数の画像を生成するかどうかを制御します：

      * `disabled`：順次モードを無効化。複数の参考画像があっても 1 枚のみ生成します（デフォルト）
      * `auto`：順次モードを有効化。複数の画像を生成できます

      **使用上の注意：**

      * ✅ `n: 3` を設定するか、`sequential_image_generation: "auto"` + `max_images: 3` を使用します
      * ✅ テキストから複数画像の生成に対応：テキストプロンプトのみで最大 10 枚を生成
      * ✅ 画像から画像生成／画像から複数画像の生成に対応：`image_urls` を指定し、参考画像に基づいて複数の画像を生成
      * ⚠️ `n > 1` の場合、自動的に `auto` に設定されます

      **注意：**

      * 入力参考画像数 + 最終的な生成画像数 ≤ 15 枚
    </ParamField>

    <ParamField body="metadata.sequential_image_generation_options" type="object">
      順次画像生成のオプション

      `sequential_image_generation` が `auto` に設定されている場合に使用できます

      **プロパティ：**

      * `max_images`（整数）：生成する画像数を指定。範囲：1〜10

      **例：**

      ```json theme={null}
      "sequential_image_generation_options": { "max_images": 3 }
      ```
    </ParamField>

    <ParamField body="metadata.watermark" type="boolean" default={false}>
      生成画像にウォーターマークを追加するかどうか

      * `true`：ウォーターマークを追加
      * `false`：ウォーターマークを追加しない（デフォルト）
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="id" type="string">
  ステータス照会に使用するタスクの一意な識別子
</ResponseField>

<ResponseField name="object" type="string">
  オブジェクトタイプ。常に `generation.task`
</ResponseField>

<ResponseField name="model" type="string">
  使用したモデル名
</ResponseField>

<ResponseField name="status" type="string">
  タスクステータス

  * `queued` - 処理待ち
  * `in_progress` - 処理中
  * `completed` - 正常に完了
  * `failed` - 失敗
</ResponseField>

<ResponseField name="progress" type="integer">
  タスクの進捗率（0〜100）
</ResponseField>

<ResponseField name="created_at" type="integer">
  タスク作成時刻のタイムスタンプ（Unix タイムスタンプ）
</ResponseField>

<ResponseField name="metadata" type="object">
  タスクのメタデータ
</ResponseField>

<ResponseField name="completed_at" type="integer">
  タスク完了時刻のタイムスタンプ（Unix タイムスタンプ）。タスク完了後にのみ返されます。
</ResponseField>

<ResponseField name="expires_at" type="integer">
  結果ファイルの有効期限のタイムスタンプ（Unix タイムスタンプ）。有効期限前に結果ファイルをダウンロードまたは転送してください。
</ResponseField>

<ResponseField name="result" type="object">
  タスク成功後の生成結果。`status` が `completed` の場合にのみ返されます。
</ResponseField>

<ResponseField name="result.type" type="string">
  結果のタイプ。画像タスクでは常に `image`。
</ResponseField>

<ResponseField name="result.data" type="array">
  画像結果のリスト。レイヤー分解を有効にした場合、通常は最初の要素がベース画像で、残りの要素が透明チャンネルを持つ独立した PNG レイヤーです。
</ResponseField>

<ResponseField name="result.data[].url" type="string">
  ベース画像または独立したレイヤーの公開アクセス URL。
</ResponseField>

<ResponseField name="result.data[].z_index" type="integer">
  レイヤーの重なり順。`layer_decomposition` を有効にした場合、通常はベース画像が `0` で、独立したレイヤーが順に増加します。
</ResponseField>

<ResponseField name="result.data[].size" type="string">
  現在のベース画像または独立したレイヤーのピクセルサイズ。例：`2048x2048`。
</ResponseField>

<ResponseField name="result.data[].output_format" type="string">
  現在の結果項目のファイル形式。ベース画像はリクエストした形式、透明な独立レイヤーは `png` です。
</ResponseField>

<ResponseField name="result.data[].bounding_box" type="object">
  ベース画像内での独立したレイヤーの位置。`absolute`（絶対座標）と `normalized`（正規化座標）を含みます。
</ResponseField>

<ResponseField name="result.data[].bounding_box.absolute" type="array">
  ベース画像内でのレイヤーの絶対ピクセル座標。形式は `[x1, y1, x2, y2]` で、それぞれ左上と右下の座標を表します。
</ResponseField>

<ResponseField name="result.data[].bounding_box.normalized" type="array">
  レイヤーの正規化座標。形式は `[x1, y1, x2, y2]` で、座標の範囲は `0-1000` です。
</ResponseField>

<ResponseField name="result.data[].name" type="string">
  レイヤー名。
</ResponseField>

<ResponseField name="result.data[].description" type="string">
  レイヤーの内容の説明。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "doubao-seedream-5-0-pro",
      "prompt": "A cute panda playing in a bamboo forest",
      "size": "1:1",
      "n": 1,
      "metadata": {
        "resolution": "2K"
      }
    }'
  ```

  ```bash cURL (画像から画像) theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "doubao-seedream-5-0-pro",
      "prompt": "A cute panda playing in a bamboo forest",
      "size": "1:1",
      "n": 1,
      "image_urls": [
        "https://example.com/panda.jpg"
      ],
      "metadata": {
        "resolution": "1K"
      }
    }'
  ```

  ```bash cURL (レイヤー分解) theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "doubao-seedream-5-0-pro",
      "prompt": "Precisely separate the image into a base image and independent transparent PNG layers.",
      "image_urls": [
        "https://example.com/office-desk.png"
      ],
      "size": "2K",
      "n": 1,
      "layer_decomposition": true
    }'
  ```

  <Note>
    `layer_decomposition` を有効にする場合、`size` には `1K` または `2K` の解像度プリセットを直接使用し、`WIDTHxHEIGHT` のような明示的なピクセルサイズは使用しないでください。送信に成功したら、`GET /v1/images/generations/{task_id}` で完全なレイヤー結果を照会します。
  </Note>

  ```bash cURL (複数画像生成) theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "doubao-seedream-5-0-pro",
      "prompt": "A cute panda playing in a bamboo forest",
      "size": "1:1",
      "n": 4,
      "metadata": {
        "resolution": "2K",
        "sequential_image_generation": "auto",
        "sequential_image_generation_options": { "max_images": 4 },
        "watermark": false
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://toapis.com/v1/images/generations",
      headers={
          "Authorization": "Bearer your-ToAPIs-key",
          "Content-Type": "application/json"
      },
      json={
          "model": "doubao-seedream-5-0-pro",
          "prompt": "A cute panda playing in a bamboo forest",
          "size": "1:1",
          "n": 1,
          "metadata": {
              "resolution": "2K"
          }
      }
  )

  task = response.json()
  print(f"任务 ID: {task['id']}")
  print(f"Status: {task['status']}")
  ```

  ```python Python (画像から画像) theme={null}
  import requests

  response = requests.post(
      "https://toapis.com/v1/images/generations",
      headers={
          "Authorization": "Bearer your-ToAPIs-key",
          "Content-Type": "application/json"
      },
      json={
          "model": "doubao-seedream-5-0-pro",
          "prompt": "A cute panda playing in a bamboo forest",
          "size": "1:1",
          "n": 1,
          "image_urls": ["https://example.com/panda.jpg"],
          "metadata": {
              "resolution": "1K"
          }
      }
  )

  task = response.json()
  print(f"任务 ID: {task['id']}")
  print(f"Status: {task['status']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://toapis.com/v1/images/generations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-ToAPIs-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'doubao-seedream-5-0-pro',
      prompt: 'A cute panda playing in a bamboo forest',
      size: '1:1',
      n: 1,
      metadata: {
        resolution: '2K'
      }
    })
  });

  const task = await response.json();
  console.log(`任务 ID: ${task.id}`);
  console.log(`Status: ${task.status}`);
  ```

  ```javascript JavaScript (画像から画像) theme={null}
  const response = await fetch('https://toapis.com/v1/images/generations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-ToAPIs-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'doubao-seedream-5-0-pro',
      prompt: 'A cute panda playing in a bamboo forest',
      size: '1:1',
      n: 1,
      image_urls: ['https://example.com/panda.jpg'],
      metadata: {
        resolution: '1K'
      }
    })
  });

  const task = await response.json();
  console.log(`任务 ID: ${task.id}`);
  console.log(`Status: ${task.status}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "task_img_abc123def456",
    "object": "generation.task",
    "model": "doubao-seedream-5-0-pro",
    "status": "queued",
    "progress": 0,
    "created_at": 1703884800,
    "metadata": {}
  }
  ```

  ```json 200 レイヤー分解完了 theme={null}
  {
    "completed_at": 1787128810,
    "created_at": 1787128650,
    "expires_at": 1787215210,
    "id": "tsk_img_example_layer_decomposition",
    "model": "doubao-seedream-5-0-pro",
    "object": "generation.task",
    "progress": 100,
    "result": {
      "type": "image",
      "data": [
        {
          "url": "https://files.toapis.com/images/example/base.jpg",
          "size": "1600x2848",
          "output_format": "jpeg",
          "z_index": 0
        },
        {
          "url": "https://files.toapis.com/images/example/layer-1.png",
          "size": "3040x955",
          "output_format": "png",
          "z_index": 1,
          "bounding_box": {
            "absolute": [0, 0, 1600, 503],
            "normalized": [0, 0, 999, 176]
          },
          "name": "Background office equipment",
          "description": "The monitor edge and file organizer extracted from the background"
        },
        {
          "url": "https://files.toapis.com/images/example/layer-2.png",
          "size": "1982x1162",
          "output_format": "png",
          "z_index": 2,
          "bounding_box": {
            "absolute": [800, 589, 1599, 1058],
            "normalized": [500, 207, 999, 371]
          },
          "name": "Stacked white papers",
          "description": "Several stacked white office papers extracted from the desk"
        }
      ]
    },
    "status": "completed"
  }
  ```
</ResponseExample>