> ## 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.
# SeeDance Videos Generation API 接続説明
> ByteDance Seedance Video Generation API guide - Ace Data Cloud
本文では、SeeDance Videos Generation API の接続説明を紹介します。これは、カスタムパラメータを入力することで SeeDance の公式動画を生成することができます。
## 申請プロセス
SeeDance Videos Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API トークンを取得し、保管してください。
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。
**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で一般残高をチャージできます。
> 📘 完全なドキュメント：[SeeDance Videos Generation API →](https://platform.acedata.cloud/documents/seedance-videos)
## 基本使用
まず、基本的な使用方法を理解します。これは、プロンプト `content.text`、タイプ `content.type=text`、およびモデル `model` を入力することで、処理された結果を得ることができます。具体的な内容は以下の通りです：
ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：
* `accept`：受け取りたいレスポンスの形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
さらに、リクエストボディを設定しています。これには以下が含まれます：
* `model`：生成する動画のモデル。
* **Seedance 1.x シリーズ**：`doubao-seedance-1-0-pro-250528`、`doubao-seedance-1-0-pro-fast-251015`、`doubao-seedance-1-5-pro-251215`、`doubao-seedance-1-0-lite-t2v-250428`、`doubao-seedance-1-0-lite-i2v-250428`。
* **Seedance 2.0 シリーズ**（顔/キャラクター参照などのマルチモーダル入力をサポート）：`doubao-seedance-2-0-260128`（標準）、`doubao-seedance-2-0-fast-260128`（高速）、`doubao-seedance-2-0-mini-260615`（軽量）。詳細は下記「顔とキャラクター参照（Seedance 2.0）」のセクションを参照してください。
* `content`：入力内容の配列、`type` は `text`（プロンプト）、`image_url`（参照画像）、`audio_url`（参照音声、2.0）、`video_url`（参照動画、2.0）であることができます。画像は `role` を通じて用途を指定できます：`first_frame`（初フレーム）/ `last_frame`（終フレーム）/ `reference_image`（顔/キャラクター/主体参照）。
* `resolution`：出力解像度、選択肢は `480p` / `720p` / `1080p`（2.0 標準モデルは `4k` もサポート；2.0 の `fast` / `mini` は最大 `720p`）。
* `ratio`：アスペクト比、選択肢は `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`。
* `duration`：動画の長さ（秒）、1.x の範囲は 2–12、2.0 の範囲は 2–15。
* `seed`：ランダムシード、整数、-1 から 4294967295。
* `camerafixed`：カメラを固定するかどうか、`true` / `false`。
* `watermark`：ウォーターマークを追加するかどうか、`true` / `false`。
* `generate_audio`：音声付き動画を生成するかどうか、`true` / `false`、**のみ `doubao-seedance-1-5-pro-251215` がサポート**。
* `return_last_frame`：結果に動画の最後のフレーム画像の URL を返すかどうか。
* `execution_expires_after`：タスクのタイムアウト時間（秒）、範囲は 3600–259200。
* `callback_url`：非同期コールバックアドレス、設定後 API はすぐに `task_id` を返し、タスクが完了した際に結果をそのアドレスに POST します。
* `async`：オプション、`true` に設定するとインターフェースはすぐに `task_id` を返し、`callback_url` を提供する必要はなく、その後対応するタスククエリインターフェースを通じて結果をポーリングして取得します。
選択後、右側にも対応するコードが生成されていることがわかります。以下のように示されています：
「Try」ボタンをクリックするとテストが行えます。上の図のように、以下のような結果が得られました：
```json theme={null}
{
"success": true,
"task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
"trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
"data": {
"task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
"status": "succeeded",
"model": "doubao-seedance-2-0-fast-260128",
"duration": 5,
"resolution": "720p",
"ratio": "16:9",
"video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
}
}
```
返された結果には複数のフィールドがあり、以下のように説明されます：
* `success`、この時点での動画生成タスクの状態。
* `task_id`、この時点での動画生成タスクの ID。
* `trace_id`、この時点での動画生成トラッキング ID。
* `data`、この時点での動画生成タスクの結果リスト。
* `task_id`、この時点での動画生成タスクのサーバー側 ID。
* `video_url`、この時点での動画生成タスクの動画リンク。
* `status`、この時点での動画生成タスクの状態。
* `model`、生成動画に使用されたモデル。
満足のいく動画情報が得られたことがわかります。結果の `data` の動画リンクアドレスに基づいて生成された SeeDance 動画を取得するだけです。
また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURL のコードは以下の通りです：
```shell theme={null}
curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
"content": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}],
"model": "doubao-seedance-2-0-fast-260128",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}'
```
## インラインパラメータ説明
`content[].text` プロンプトの末尾に、`--parameter value` の形式で生成パラメータを追加して渡すことができます（旧方式、弱い検証、誤って記入した場合は自動的にデフォルト値が使用されます）。完全なパラメータリストは以下の通りです：
| 内联参数 | 对应字段 | 说明 | 取值范围 |
| ---------- | ----------------- | -------------- | ------------------------------------------------------------- |
| `--rs` | `resolution` | 出力解像度 | `480p` / `720p` / `1080p` |
| `--rt` | `ratio` | アスペクト比 | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` |
| `--dur` | `duration` | 動画の長さ（秒） | 2–12 |
| `--frames` | `frames` | 動画のフレーム数 | \[29, 289] の中で 25+4n の整数 |
| `--fps` | `framespersecond` | フレームレート | `24` のみ |
| `--seed` | `seed` | ランダムシード | -1 から 4294967295 |
| `--cf` | `camerafixed` | カメラを固定するか | `true` / `false` |
| `--wm` | `watermark` | ウォーターマークを追加するか | `true` / `false` |
> **推奨される方法**：リクエストボディ内で対応するトップレベルフィールド（例：`resolution`、`ratio` など）を直接使用し、強い検証モードを適用します。パラメータに誤りがある場合は明確なエラーメッセージが返され、問題の特定が容易になります。
## 音声付き動画の生成
`doubao-seedance-1-5-pro-251215` は `generate_audio` パラメータを使用して音声付きの動画を生成することをサポートしています：
```json theme={null}
{
"model": "doubao-seedance-1-5-pro-251215",
"content": [
{
"type": "text",
"text": "女の子が狐を抱いていて、風が彼女の髪を吹き抜け、風の音が聞こえます"
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 5
}
```
他のモデルはこのパラメータをサポートしておらず、渡された場合は無視されます。
## 画像から動画の最初のフレーム
画像から動画を生成するタスクを行いたい場合、まず `content` パラメータには `type` が `image_url` の項目を含める必要があります。`image_url` フィールドはオブジェクト形式でなければなりません：`{"url": "https://..."}` または Base64 形式 `{"url": "data:image/png;base64,..."}`。
> **注意**：`image_url` は文字列形式（例： `"image_url": "https://..."`）で直接渡すことはできず、オブジェクト形式 `"image_url": {"url": "https://..."}` を使用する必要があります。そうしないと 400 エラーが返されます。
対応するコード：
```python theme={null}
import requests
url = "https://api.acedata.cloud/seedance/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
}
},
{
"type": "text",
"text": "女の子が狐を抱いています。彼女は目を開けてカメラを優しく見つめ、狐は愛情を持って彼女を抱き返します。カメラがゆっくりと引いていくと、彼女の髪は風に優しく吹かれます。 --ratio adaptive --dur 5"
}
],
"model": "doubao-seedance-1-0-pro-250528"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
実行すると、すぐに結果が得られます：
```
{
"success": true,
"task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
"trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
"data": {
"task_id": "cgt-20251222072003-x2259",
"status": "succeeded",
"video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
生成された効果は画像から動画を生成したもので、結果は上記と似ています。
## 画像から動画の最初と最後のフレーム
画像から動画の最初と最後のフレームを生成したい場合、まず `content` パラメータには `type` が `image_url` の項目を渡し、それぞれの `role` を `first_frame` と `last_frame` に設定することで、以下の内容を指定できます：
* role：最初のフレームまたは最後のフレームを指定します。
* image\_url
* url 画像リンク
同時に `content` には `text` タイプを入力してプロンプトのヒントを提供する必要があります。
対応するコード：
```python theme={null}
import requests
url = "https://api.acedata.cloud/seedance/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedance-1-0-pro-250528",
"content": [
{
"type": "text",
"text": "360度ショット"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
},
"role": "first_frame"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
},
"role": "last_frame"
}
]
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
実行すると、すぐに結果が得られます：
```
{
"success": true,
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
"trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
"data": {
"task_id": "cgt-20251222073134-54qcw",
"status": "succeeded",
"video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
生成された効果はキャラクター生成動画で、結果は上記と似ています。
## 顔とキャラクターの参考（Seedance 2.0）
**Seedance 2.0 シリーズ**（`doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`、`doubao-seedance-2-0-mini-260615`）は「**実在の人物 / キャラクター**」の参考素材を渡すことをサポートしています：`content` に `type` が `image_url`、`role` が `reference_image` の項目を追加し、人物の写真を参考として使用します。モデルは生成された動画内で**その人物の外見的特徴を保持**し、同じ人物を「新しいシーン、動作、またはショット」に配置します。
> 📌 実在の人物の写真はプラットフォームによって自動的に基盤素材として登録され、その後生成に使用されます。このプロセスは呼び出し側にとって完全に透明です：**リクエストとレスポンスの形式は変わらず**、追加のパラメータは不要で、最初の生成時に素材処理に数秒余分にかかります。
使用の要点：
* **Seedance 2.0 シリーズ**モデルのみが `reference_image` をサポートします；1.x モデルでは `first_frame` / `last_frame`（画像から動画の最初と最後のフレーム）を使用してください。
* `reference_image` **は** `first_frame` / `last_frame` と混用できず、どちらか一方のみを選択する必要があります。
* マルチモーダル参照の数の上限：`image_url` は最大 **9** 枚；2.0 では `audio_url`（`role` は `reference_audio`、最大 3 件）および `video_url`（`role` は `reference_video`、最大 3 件）もサポートされています。
* 参考画像は**一人、正面、鮮明、遮蔽なし**の写真を使用することをお勧めします。顔が鮮明であればあるほど、類似度が高くなります。
### 例1：人物の外見を保持したクローズアップ
顔写真を渡し、その人物がカメラに向かって微笑み手を振るようにします。対応するコード：
```python theme={null}
import requests
url = "https://api.acedata.cloud/seedance/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{
"type": "text",
"text": "The woman looks at the camera, gives a warm natural smile and waves her hand, soft studio lighting, gentle camera push-in."
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
}
}
],
"resolution": "480p",
"ratio": "9:16",
"duration": 5
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
返された結果は以下の通りで、生成された動画の中の人物は参考写真と一致しています：
```json theme={null}
{
"success": true,
"task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
"trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
"data": {
"task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
"status": "succeeded",
"video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
"model": "doubao-seedance-2-0-fast-260128",
"resolution": "480p",
"ratio": "9:16",
"duration": 5
}
}
```
### 例2：同じ人物を新しいシーンに配置
`reference_image` の強力な点は：**人物のアイデンティティ**を保持しつつ、シーン、服装、動作は完全にプロンプトによって決定されることです。以下は同じ顔写真を使用し、その人物がベージュのコートを着て秋の公園を歩く様子です：
```json theme={null}
{
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{
"type": "text",
"text": "The same woman wearing a beige coat walks through a sunny autumn park, golden leaves falling around her, she smiles softly at the camera, cinematic tracking shot."
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
}
}
],
"resolution": "720p",
"ratio": "9:16",
"duration": 5
}
```
返された結果は以下の通りで、人物の外見は保持されつつ、シーンは秋の公園に切り替わっています：
```json theme={null}
{
"success": true,
"task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
"trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
"data": {
"task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
"status": "succeeded",
"video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
"model": "doubao-seedance-2-0-fast-260128",
"resolution": "720p",
"ratio": "9:16",
"duration": 5
}
}
```
> 💡 人物が写真の構図を正確に再現するようにしたい場合（「異なるシーンの同じ人物」ではなく）、`first_frame`（画像から動画の最初のフレーム）を使用して、この写真から動画が動き始めるようにしてください。
## 非同期コールバック
SeeDance Videos Generation API の生成時間は長いため（約 1-2 分）、`callback_url` フィールドを使用して非同期モードを利用することで、HTTP 接続が長時間占有されるのを避けることができます。
全体の流れ：クライアントがリクエストを発行する際に `callback_url` を指定し、API はすぐに `task_id` を含むレスポンスを返します；タスクが完了すると、プラットフォームは生成結果を POST JSON 形式で `callback_url` に送信し、結果にも `task_id` が含まれているため、関連付けが可能です。
```json theme={null}
{
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```
タスクが完了した際に、プラットフォームが `callback_url` にプッシュする内容は以下の通りです：
```json theme={null}
{
"success": true,
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
"trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
"data": {
"task_id": "cgt-20251222073134-54qcw",
"status": "succeeded",
"video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
結果の `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"
}
```
## 結論
この文書を通じて、SeeDance Videos Generation API を使用してプロンプト、参考画像、および Seedance 2.0 の顔/キャラクター参照を通じて動画を生成する方法を理解しました。この文書が API の接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。