> ## 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 Images Generation API 接続説明について紹介します。これは、カスタムパラメータを入力することで SeeDream の公式画像を生成することができます。
## 申請プロセス
SeeDream Images Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして、API トークンを取得し、保管してください。
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。
**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で一般残高をチャージできます。
> 📘 完全なドキュメント：[SeeDream Images Generation API →](https://platform.acedata.cloud/documents/seedream-images)
## 基本的な使用法
まず、基本的な使用方法を理解します。これは、プロンプト `prompt`、生成アクション `action`、画像サイズ `size` を入力することで、処理された結果を得ることができます。まず、`action` フィールドを単純に渡す必要があり、その値は `generate` です。その後、プロンプトを入力する必要があります。具体的な内容は以下の通りです：
ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：
* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
さらに、リクエストボディを設定しています。これには以下が含まれます：
* `prompt`：プロンプト。
* `model`：生成モデル。デフォルトは `doubao-seedream-5-0-260128`（SeeDream 5.0 Lite、最新）。`doubao-seedream-5-0-pro-260628`、`doubao-seedream-5-0-260128`、`doubao-seedream-4-5-251128`、`doubao-seedream-4-0-250828`、`doubao-seedream-3-0-t2i-250415`、`doubao-seededit-3-0-i2i-250628` をサポートしています。`doubao-seedream-5-0-pro-260628`（SeeDream 5.0 Pro）はフラッグシップの単一画像モデルで、単一画像のみを生成し、**グループ画像（`sequential_image_generation`）、ストリーミング（`stream`）、およびオンライン検索（`tools`）はサポートしていません。** **`model` には完全なモデル文字列（例：`doubao-seedream-5-0-260128`）を渡す必要があり、`doubao-seedream-5.0-lite` のような省略形を渡すと 400 が返されます。**
* `image`：入力画像情報。URL または Base64 エンコードをサポートしています。`doubao-seedream-5-0-pro-260628` は単一画像または複数画像の入力をサポート（複数画像は 2-10 枚で、2 枚目以降は枚数に応じて課金）、`doubao-seedream-5-0-260128`、`doubao-seedream-4-5-251128`、`doubao-seedream-4-0-250828` は単一画像または複数画像の入力をサポート、`doubao-seededit-3-0-i2i-250628` は単一画像の入力のみをサポートし、`doubao-seedream-3-0-t2i-250415` はこのパラメータをサポートしていません。
* `size`：生成する画像のサイズ情報を指定します。以下の 2 つの方法をサポートし、混在させることはできません。方法 1 | 生成する画像の解像度を指定し、プロンプト内で自然言語で画像のアスペクト比を説明します。**各モデルがサポートするプリセットは異なります**：`doubao-seedream-5-0-pro-260628` は `1K`/`2K` をサポート；`doubao-seedream-5-0-260128` は `2K`/`3K`/`4K` をサポート；`doubao-seedream-4-5-251128` は `2K`/`4K` のみをサポート；`doubao-seedream-4-0-250828` は `1K`/`2K`/`4K` をサポート；`doubao-seedream-3-0-t2i-250415` と `doubao-seededit-3-0-i2i-250628` **はプリセットをサポートしておらず、方法 2 のみを受け入れます。** 方法 2 | 生成する画像の幅と高さのピクセル値を指定します：デフォルトは `2048x2048` で、総ピクセル数と幅高さ比の範囲はモデルによって異なります（例えば、5.0 Pro の総ピクセル範囲は \[921600, 4194304]、5.0 Lite / 4.5 の総ピクセル下限は 3,686,400、4.0 の下限は 921,600、3.0-t2i / seededit-3.0-i2i の範囲は \[512x512, 2048x2048]）。
* `seed`：ランダム数シードで、モデルが生成する内容のランダム性を制御します。値の範囲は \[-1, 2147483647] です。**`doubao-seedream-3-0-t2i-250415` のみがこのパラメータをサポートします。**
* `sequential_image_generation`：グループ画像：入力した内容に基づいて生成される関連する一連の画像。`doubao-seedream-5-0-260128`、`doubao-seedream-4-5-251128`、`doubao-seedream-4-0-250828` がこのパラメータをサポートし、デフォルトは `disabled` です。
* `stream`：ストリーミング出力モードを有効にするかどうかを制御します。`doubao-seedream-5-0-260128`、`doubao-seedream-4-5-251128`、`doubao-seedream-4-0-250828` がこのパラメータをサポートし、デフォルトは `false` です。
* `guidance_scale`：モデルの出力結果とプロンプトの一致度。値が大きいほど関連性が強くなります。値の範囲は \[1, 10] です。`doubao-seedream-3-0-t2i-250415` のデフォルト値は 2.5、`doubao-seededit-3-0-i2i-250628` のデフォルト値は 5.5、他のモデルはサポートしていません。
* `response_format`：生成された画像の返却形式を指定します。デフォルトは `url` で、`b64_json` もサポートしています。
* `watermark`：生成された画像にウォーターマークを追加するかどうか。デフォルトは `true` です。
* `output_format`：生成された画像のファイル形式を指定します。`jpeg`（デフォルト）と `png` をサポートしています。`doubao-seedream-5-0-pro-260628` と `doubao-seedream-5-0-260128` のみがサポートしています。
* `tools`：モデルが呼び出すツールを設定します。現在は `web_search`（オンライン検索）をサポートしています。`doubao-seedream-5-0-260128` のみがサポートしています。
* `callback_url`：結果をコールバックする必要がある URL。
* `async`：非同期モードで処理するかどうか。`true` に設定すると、インターフェースはすぐに `task_id` を返し、`callback_url` を提供する必要はなく、その後 `/seedream/tasks` を通じて結果をポーリングして取得します。
選択後、右側にも対応するコードが生成されていることがわかります。以下のように：
「Try」ボタンをクリックするとテストが行えます。上の図のように、ここで次の結果を得ることができました：
```json theme={null}
{
"success": true,
"task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
"trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
"data": [
{
"prompt": "湿った黒いスレートの上にある霜のかかったガラスの香水瓶のフォトリアリスティックなスタジオ製品ショット、シングルソフトボックスのキーライト、水滴、暗いムーディーな背景、85mmマクロ。",
"size": "2048x2048",
"image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.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-260128",
"prompt": "湿った黒いスレートの上にある霜のかかったガラスの香水瓶のフォトリアリスティックなスタジオ製品ショット、シングルソフトボックスのキーライト、水滴、暗いムーディーな背景、85mmマクロ。"
}'
```
## 画像編集タスク
特定の画像を編集したい場合、まずパラメータ `image` に編集する必要がある画像のリンクを渡す必要があります。
* model：今回の画像編集タスクで使用されるモデル、`doubao-seedream-5-0-260128`、`doubao-seedream-4-5-251128`、`doubao-seedream-4-0-250828` は単一または複数の画像入力をサポートし、`doubao-seededit-3-0-i2i-250628` は単一画像入力のみをサポートします。
* image：編集する必要がある画像をアップロードします。1枚または複数枚。
記入例は以下の通りです：
対応するコード：
```python theme={null}
import requests
url = "https://api.acedata.cloud/flux/images"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedream-4-0-250828",
"prompt": "モデルのポーズと液体の衣服の流れる形状を変更せずに保つ。衣服の素材を銀の金属から完全に透明な水（またはガラス）に変更する。液体の流れを通して、モデルの肌の詳細が見える。光と影の効果が反射から屈折にシフトする。",
"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": "モデルのポーズと液体の衣服の流れる形状を変更せずに保つ。衣服の素材を銀の金属から完全に透明な水（またはガラス）に変更する。液体の流れを通して、モデルの肌の詳細が見える。光と影の効果が反射から屈折にシフトする。",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
生成された効果は元の画像を編集したものであり、結果は前述のものと似ています。
## 非同期コールバック
SeeDream Images Generation API の生成時間は比較的長く、約1〜2分かかります。APIが長時間応答しない場合、HTTPリクエストは接続を維持し続け、追加のシステムリソースを消費する可能性があります。そのため、このAPIは非同期コールバックのサポートも提供しています。
全体の流れは次の通りです：クライアントがリクエストを開始する際に、追加で `callback_url` フィールドを指定します。クライアントがAPIリクエストを開始すると、APIはすぐに結果を返し、現在のタスクIDを示す `task_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`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。
* `401 invalid_token`：未認証、無効または不足している認証トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_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との接続や使用をより良くする手助けとなることを願っています。ご不明な点がございましたら、いつでも当社の技術サポートチームにお問い合わせください。
```