> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えとして保存してください。
まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを促され、完了後に自動的に現在のページへ戻ります。
**1 つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、サービスごとに個別に申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は [コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。
> 📘 完全なドキュメント：[SeeDream Images Generation API →](https://platform.acedata.cloud/documents/seedream-images)
## 基本的な使用方法
まず基本的な使用方法を理解しましょう。プロンプト `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` を渡さずに自動分割することも、自然言語/`` を使用して要素を指定することもできます。`size` は `auto`/`1K`/`1.5K`/`2K` をサポートしています。このモードはグループ画像、ストリーミング、ウェブ検索、または `background` と併用できません。
* `callback_url`：結果をコールバックする必要がある URL。
* `async`：非同期モードで処理するかどうかです。`true` に設定すると、インターフェースは即座に `task_id` を返します。`callback_url` を指定する必要はなく、その後 `/seedream/tasks` を通じてポーリングして結果を取得します。
選択後、右側にも対応するコードが生成されていることが確認できます。図のとおりです。
「Try」ボタンをクリックするとテストできます。上図のとおり、ここで以下の結果を取得できます。
```json theme={null}
{
"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 のコードは以下の通りです：
```shell theme={null}
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 枚または複数枚
入力例は以下の通りです：
対応するコード：
```python theme={null}
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)
```
実行をクリックすると、すぐに以下のような結果が得られることがわかります：
```json theme={null}
{
"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` を追加できます。また、プロンプト内で正規化された `` 座標を使用することもできます。
```shell theme={null}
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"
}
```
内容は以下の通りです：
```json theme={null}
{
"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、サーバーで問題が発生しました。
### エラー応答の例
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 結論
本ドキュメントを通じて、SeeDream Images Generation API を使用してプロンプトを入力することで画像を生成する方法を理解できました。本ドキュメントが、API の連携と使用をより良く行う助けとなることを願っています。ご不明な点がございましたら、いつでも当社の技術サポートチームまでお問い合わせください。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.