SeeDream Images Generation API 連携説明

ByteDance Seedream Image Generation API guide - Ace Data Cloud

本記事では、カスタムパラメータを入力して SeeDream 公式の画像を生成できる SeeDream Images Generation API の連携説明を紹介します。

​

申請フロー

SeeDream Images Generation API を使用するには、まず Ace Data Cloud コンソール で API Token を取得し、控えとして保存してください。

まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを促され、完了後に自動的に現在のページへ戻ります。

1 つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、サービスごとに個別に申請する必要はありません。 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は コンソール で共通残高をチャージできます。

📘 完全なドキュメント：SeeDream Images Generation API →

​

基本的な使用方法

まず基本的な使用方法を理解しましょう。プロンプト prompt、生成アクション action、画像サイズ size を入力すると、処理後の結果を取得できます。まず action フィールドを簡単に渡す必要があり、その値は generate です。続いてプロンプトも入力する必要があります。具体的な内容は以下のとおりです。

ここでは Request Headers を設定していることが確認できます。内容は以下のとおりです。

• accept：受け取りたいレスポンス結果の形式です。ここでは application/json、つまり JSON 形式を指定します。
• authorization：API を呼び出すためのキーです。申請後、直接プルダウンから選択できます。

さらに Request Body を設定します。内容は以下のとおりです。

• prompt：プロンプト。
• model：生成モデル。デフォルトは doubao-seedream-5-0-lite-260128（SeeDream 5.0 Lite、最新）です。doubao-seedream-5-0-pro-260628、doubao-seedream-5-0-lite-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 をサポートしています。doubao-seedream-5-0-pro-260628（SeeDream 5.0 Pro）はフラッグシップの単一画像モデルであり、単一画像のみを生成します。グループ画像（sequential_image_generation）、ストリーミング（stream）、およびウェブ検索（tools）はサポートしていません。 model には完全なモデル文字列（例：doubao-seedream-5-0-lite-260128）を渡す必要があります。doubao-seedream-5.0-lite のような省略形を渡すと 400 が返されます。
• image: 入力する画像情報で、URL または Base64 エンコードをサポートしています。doubao-seedream-5-0-pro-260628 は単一画像または複数画像の入力（最大 10 枚）をサポートし、doubao-seedream-5-0-lite-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 は単一画像または複数画像の入力をサポートしています。
• size: 生成画像のサイズ情報を指定します。以下の 2 つの方法をサポートしており、混在させることはできません。方法 1 | 生成画像の解像度を指定し、prompt 内で自然言語を使用して画像のアスペクト比を記述します。各モデルでサポートされるプリセットは異なります：doubao-seedream-5-0-pro-260628 は 1K/1.5K/2K をサポートします。doubao-seedream-5-0-lite-260128 は 2K/3K/4K をサポートします。doubao-seedream-4-5-251128 は 2K/4K のみをサポートします。doubao-seedream-4-0-250828 は 1K/2K/4K をサポートします。方法 2 | 生成画像の幅と高さのピクセル値を指定します：デフォルトは 2048x2048 であり、総ピクセル数とアスペクト比の値の範囲はモデルによって異なります（例：5.0 Pro の総ピクセル数の範囲は [921600, 4624220]、5.0 Lite / 4.5 の総ピクセル数の下限は 3,686,400、4.0 の下限は 921,600）。
• sequential_image_generation: グループ画像：入力した内容に基づき、内容が関連する一連の画像を生成します。doubao-seedream-5-0-lite-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 はこのパラメータをサポートしており、デフォルトは disabled です。
• stream: ストリーミング出力モードを有効にするかどうかを制御します。doubao-seedream-5-0-lite-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 はこのパラメータをサポートしており、デフォルトは false です。
• response_format: 生成画像の返却形式を指定します。デフォルトは url で、b64_json もサポートしています。
• watermark: 生成画像にウォーターマークを追加するかどうかです。デフォルトは true です。
• output_format: 生成画像のファイル形式を指定します。jpeg（デフォルト）と png をサポートしています。doubao-seedream-5-0-pro-260628 と doubao-seedream-5-0-lite-260128 のみがサポートしています。
• tools: モデルが呼び出すツールを設定します。現在は web_search（ウェブ検索）をサポートしています。Seedream 5.0 Lite のみがサポートしています。
• optimize_prompt_options: プロンプト最適化設定。5.0 Pro は standard/fast をサポートします。5.0 Lite と 4.5 は standard のみをサポートします。4.0 は standard/fast をサポートします。
• background: 5.0 Pro の単一画像編集のみがサポートしています。transparent では透明チャンネルを含む PNG を 1 枚入力する必要があり、output_format は必ず png でなければなりません。opaque は通常の不透明な背景です。
• layer_decomposition: 5.0 Pro のみがサポートしています。true に設定する場合は PNG/JPEG を 1 枚入力する必要があり、prompt を渡さずに自動分割することも、自然言語/<bbox> を使用して要素を指定することもできます。size は auto/1K/1.5K/2K をサポートしています。このモードはグループ画像、ストリーミング、ウェブ検索、または background と併用できません。
• callback_url：結果をコールバックする必要がある URL。
• async：非同期モードで処理するかどうかです。true に設定すると、インターフェースは即座に task_id を返します。callback_url を指定する必要はなく、その後 /seedream/tasks を通じてポーリングして結果を取得します。

選択後、右側にも対応するコードが生成されていることが確認できます。図のとおりです。

「Try」ボタンをクリックするとテストできます。上図のとおり、ここで以下の結果を取得できます。

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.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-5-0-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

​

画像編集タスク

ある画像を編集したい場合、まずパラメータimageには編集する画像リンクを必ず渡す必要があります

• model：今回の画像編集タスクで使用するモデル。doubao-seedream-5-0-pro-260628、doubao-seedream-5-0-lite-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 はいずれも画像入力に対応しています。
• image：編集する画像をアップロードします。1 枚または複数枚

入力例は以下の通りです：

対応するコード：

import requests

url = "https://api.acedata.cloud/seedream/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.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

生成された効果は元の画像を編集した効果であり、結果は上記と類似していることがわかります。

​

レイヤー分解（Seedream 5.0 Pro）

レイヤー分解では、1 枚の入力画像を 1 枚の背景画像と、最大 16 個の個別に編集可能な透明 PNG レイヤーに分解します。以下のリクエストではモデルが主要な要素を自動認識します。要素を指定する必要がある場合は、prompt を追加できます。また、プロンプト内で正規化された <bbox> 座標を使用することもできます。

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

返される data は z_index に従って下から上へ並べられます。背景画像の z_index は 0 です。レイヤーにはさらに name、description、および bounding_box.absolute/normalized が含まれます。絶対座標を使用して再構成する場合、レイヤーを [right-left, bottom-top] に拡大・縮小し、[left, top] に配置した後、z_index の昇順で重ねます。いずれかのレイヤーの生成に失敗した場合、分解全体が失敗します。

​

ストリーミング出力

Lite/4.x で stream: true を設定する場合、リクエストヘッダーには accept: application/x-ndjson を使用してください。インターフェースは行ごとに image_generation.partial_succeeded または image_generation.partial_failed を返し、最後に唯一の image_generation.completed イベントと最終的な usage を返します。完了イベントでのみ 1 回課金されます。ストリーミングモードは async または callback_url と併用できません。

​

非同期コールバック

SeeDream Images Generation API の生成時間は比較的長く、およそ 1～2 分かかります。API が長時間応答しない場合、HTTP リクエストは接続を維持し続け、追加のシステムリソースを消費するため、本 API は非同期コールバックにも対応しています。

全体のフローは次の通りです：クライアントがリクエストを開始する際に、追加で callback_url フィールドを指定します。クライアントが API リクエストを開始した後、API は直ちに task_id フィールド情報を含む結果を返します。これは現在のタスク ID を表します。タスクが完了すると、生成画像の結果は POST JSON の形式でクライアントが指定した callback_url に送信され、そこにも task_id フィールドが含まれます。このようにして、タスク結果を ID によって関連付けることができます。

コールバックに使用できるパブリックなアドレスがない場合は、callback_url を指定せず、リクエスト内の async フィールドを true に設定することもできます。この場合もインターフェースは直ちに task_id を返しますが、結果はプッシュされません。最終結果を取得するには、この task_id を指定して /seedream/tasks インターフェースを呼び出し、タスクステータスをポーリングする必要があります。

以下では、例を通じて具体的な操作方法を確認します。

実行をクリックすると、すぐに以下のような結果が得られることがわかります：

{
  "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：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 の連携と使用をより良く行う助けとなることを願っています。ご不明な点がございましたら、いつでも当社の技術サポートチームまでお問い合わせください。