> ## 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公式動画を生成できる SeeDance Videos Generation API の連携説明を紹介します。
## 申請フロー
SeeDance Videos Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。
まだログインまたは登録していない場合は、自動的にログインページへ移動し、登録とログインを促されます。完了後は自動的に現在のページに戻ります。
**1つの API Token でプラットフォーム上のすべてのサービスを呼び出すことができ、サービスごとに個別申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は [コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。
> 📘 完全なドキュメント：[SeeDance Videos Generation API →](https://platform.acedata.cloud/documents/seedance-videos)
## 基本的な使用方法
まず基本的な使用方法を見てみましょう。プロンプト `content.text`、タイプ `content.type=text`、およびモデル `model` を入力することで、処理後の結果を取得できます。具体的な内容は以下のとおりです。
ここでは Request Headers を設定していることがわかります。内容は以下のとおりです。
* `accept`：受信したいレスポンス結果の形式です。ここでは `application/json`、つまり JSON 形式を指定します。
* `authorization`：API を呼び出すためのキーです。申請後に直接プルダウンから選択できます。
さらに Request Body を設定します。内容は以下のとおりです。
* `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.5**：`doubao-seedance-2-5-260628`。最長30秒、純粋な音声参照、より多くの素材、動画編集および延長をサポートします。
* `content`：入力コンテンツ配列。`type` は `text`（プロンプト）、`image_url`（参照画像）、`audio_url`（参照音声）、`video_url`（参照動画）にできます。画像は `role` により用途を指定できます：`first_frame`（最初のフレーム）/ `last_frame`（最後のフレーム）/ `reference_image`（キャラクター / 主体参照）。
* `resolution`：出力解像度。`480p` / `720p` / `1080p` / `4k` から選択可能です。2.5 は 480p、720p、1080p をサポートし、2.0 Fast/Mini は 480p、720p をサポートし、2.0 Standard は最大 4k をサポートします。
* `ratio`：アスペクト比。`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` から選択可能です。
* `duration`：動画の長さ（秒、整数）。1.0 シリーズは 2～12、1.5 Pro は 4～12、2.0 シリーズは 4～15、2.5 は 4～30 です。1.5/2.x は `-1`（自動長さ）をサポートします。
* `seed`：ランダムシード。整数、-1～4294967295。
* `camerafixed`：カメラを固定するかどうか。`true` / `false`。
* `watermark`：ウォーターマークを追加するかどうか。`true` / `false`。
* `generate_audio`：音声付き動画を生成するかどうか。`true` / `false`。Seedance 1.5 Pro および 2.x シリーズでサポートされます。
* `return_last_frame`：結果内で動画の最後のフレーム画像 URL を返すかどうか。
* `omni_reference_task_type`：2.5 のみ。`auto` / `reference` / `edit` / `extend`。
* `output_format`：2.5 のみ。`mp4` / `mov`、デフォルトは `mp4`。
* `tools`：2.5 のみ。現在は `web_search` のインターネット検索ツールをサポートしており、結果数、キーワード数、検索ソースを制限できます。
* `priority`：2.5 で選択可能なタスク優先度。整数 0～9、デフォルトは 0。
* `safety_identifier`：最大64文字の安定した匿名エンドユーザー識別子。ハッシュまたは内部匿名 ID を使用し、氏名、メールアドレス、電話番号は渡さないでください。
* `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://cdn.acedata.cloud/assets/examples/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152-102bf9f98e35.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 を満たす整数（**1.0 シリーズのみ対応**） |
| `--fps` | `framespersecond` | フレームレート | `24` のみ対応 |
| `--seed` | `seed` | 乱数シード | -1 ～ 4294967295 |
| `--cf` | `camerafixed` | カメラを固定するか | `true` / `false` |
| `--wm` | `watermark` | ウォーターマークを追加するか | `true` / `false` |
> **推奨方法**：Request Body 内で対応するトップレベルフィールド（`resolution`、`ratio` など）を直接使用してください。これは強い検証モードであり、パラメータ入力に誤りがある場合は明確なエラーメッセージが返されるため、問題の切り分けがより容易になります。
## 音声付き動画の生成
Seedance 1.5 Pro および 2.x シリーズは、`generate_audio` パラメータにより音声付き動画の生成をサポートしています：
```json theme={null}
{
"model": "doubao-seedance-1-5-pro-251215",
"content": [
{
"type": "text",
"text": "A girl holds a fox, the wind blows her hair, you can hear the sound of the wind"
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 5
}
```
1.0 シリーズはこのパラメータをサポートしていません。
## Seedance 2.5 全モーダル生成、編集、延長
`doubao-seedance-2-5-260628` は 480p / 720p / 1080p、4～30 秒または自動長をサポートし、素材の上限を 30 枚の参照画像、10 本の参照動画、10 本の参照音声（合計最大 50 個）まで引き上げています。2.5 は参照音声のみの送信もサポートしており、画像または動画を同時に提供する必要はなくなりました。
通常の全モーダル生成では `omni_reference_task_type` を省略するか、`auto` に設定するか、明示的に `reference` に設定できます。動画の編集および延長では、必ず `reference_video` を渡す必要があります：
```json theme={null}
{
"model": "doubao-seedance-2-5-260628",
"content": [
{"type": "text", "text": "Replace the sky with a warm sunset while preserving the subject and camera motion."},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://cdn.acedata.cloud/input.mp4"}}
],
"resolution": "720p",
"ratio": "adaptive",
"duration": -1,
"omni_reference_task_type": "edit",
"output_format": "mov"
}
```
* `reference`：少なくとも 1 つの `reference_image`、`reference_video` または `reference_audio` を渡します；2.5 は参照音声のみの送信をサポートしています。
* `edit`：必ず `ratio: adaptive` と `duration: -1` を使用します；出力時間は実際の結果に応じて課金されます。
* `extend`：必ず `ratio: adaptive` を使用します；`duration` は 4～30 または `-1` にできます。
* `auto`：モデルがプロンプトと素材に基づいて、生成、編集、または延長を自動選択します。
* タスクタイプが素材またはプロンプトと一致しない場合、タスクは失敗し、特定可能なパラメータエラーが返されます；上記の制約に従って調整した後、再送信してください。
## 画像から動画の開始フレーム
画像から動画へのタスクを行いたい場合、まず `content` パラメータには `type` が `image_url` の項目を含める必要があり、`image_url` フィールドはオブジェクト形式でなければなりません：`{"url": "https://..."}` または Base64 形式 `{"url": "data:image/png;base64,..."}`。
> **注意**：`image_url` は文字列形式を直接渡すことをサポートしていません（例：`"image_url": "https://cdn.acedata.cloud/e724d7f13d.png"`）。必ずオブジェクト形式 `"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": "A girl holds a fox in her arms. She opens her eyes and gazes tenderly at the camera, while the fox affectionately holds her back. As the camera slowly pulls away, her hair is gently blown by the wind. --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` にタイプ `image_url` を渡し、それぞれ `role` を `first_frame` と `last_frame` に設定することで、以下の内容を指定できます：
* role：開始フレームまたは終了フレームを指定します。
* image\_url
* url 画像リンク
同時に、`content` には prompt プロンプトとしてタイプ `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-degree shot"
},
{
"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`）は `reference_image`、`reference_audio`、および `reference_video` をサポートしています。所有している、または使用許諾を得た素材を使用して、キャラクター、被写体、動き、カメラワーク、音声、リズムの一貫性を維持できます。
> 所有している、または使用許諾を得た実在人物およびキャラクターの素材のみをアップロードしてください。実在人物の素材に対するサポート方法はモデルごとに異なります。リクエスト形式は変わりませんが、素材が要件を満たさない場合は明確なエラーが返されます。
使用上のポイント：
* `reference_image` をサポートするのは **Seedance 2.0 シリーズ**モデルのみです。1.x モデルでは `first_frame` / `last_frame`（画像から動画への生成における開始・終了フレーム）を使用してください。
* 画像から動画への生成の開始フレーム、画像から動画への生成の開始・終了フレーム、全モダリティ参照は、3つの相互排他的なシナリオです：`first_frame` / `last_frame` は `reference_image` / `reference_video` / `reference_audio` と併用できません。
* 全モダリティ参照で開始・終了フレームを指定したい場合は、画像を `reference_image` として指定し、プロンプトに「画像1を開始フレームとして使用」または「画像2を終了フレームとして使用」と明記してください。開始・終了フレームを厳密に固定する必要がある場合は、`first_frame` / `last_frame` のみを使用してください。
* マルチモーダル参照の数の上限：`image_url` は最大 **9** 枚です。2.0 では `audio_url`（`role` は `reference_audio`、最大3件）および `video_url`（`role` は `reference_video`、最大3件）もサポートします。
* **参照音声（`audio_url`）の素材要件**：形式は `wav` / `mp3`；**1件あたりの長さは2～15秒**、最大3件かつ**合計時間は15秒を超えない**；1件あたり15 MB以下。時間範囲を超えると、素材処理段階で失敗します。
* **参照動画（`video_url`）の素材要件**：形式は `mp4` / `mov`；**1件あたりの長さは2～15秒**、最大3件かつ**合計時間は15秒を超えない**。
* 参照画像には、**1人、正面顔、鮮明、遮蔽物なし**の写真を使用することを推奨します。顔が鮮明であるほど、類似度が高くなります。
### 例1：人物の顔立ちを維持したクローズアップ
顔写真を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://cdn.acedata.cloud/assets/examples/nanobanana/8e075897-0f50-4443-8500-666751791c6c-4346f66287c0.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://cdn.acedata.cloud/assets/examples/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf-a56b2736a4e0.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://cdn.acedata.cloud/assets/examples/nanobanana/8e075897-0f50-4443-8500-666751791c6c-4346f66287c0.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://cdn.acedata.cloud/assets/examples/seedance/44f47593-556b-4fda-afa5-7a71eefcd228-2161efa5dd09.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.5 を使用して動画を編集または延長する方法をご理解いただけたと思います。本ドキュメントが API 連携の完了に役立つことを願っています。ご不明な点がございましたら、技術サポートまでお問い合わせください。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.