Seedance 2.5 の動画生成 | API ドキュメント

# Seedance 2.5 Video Generation

Seedance 2.5 multimodal content, generated audio, and draft-task reuse parameters.

POST https://api.apihop.ai/v1/video/seedance

Create an asynchronous Seedance 2.5 job. For Seedance 2.0, use its [separate parameter reference](https://apihop.ai/en/docs/api-reference/BytePlus/seedance-2-0).

## Authentication

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Body

### `model` (string, required)

`seedance-2.5`.

### `prompt` (string)

Video prompt. Required for text-only generation; may be omitted or blank when image/video references are supplied. Omit it for `draft_task` reuse. `metadata.content` text items are discarded; top-level `prompt` is authoritative.

### `duration` (number, Default: 5)

Integer from `4` through `30`, or `-1` for automatic duration. Native `seconds` accepts the equivalent integer string. `metadata.duration` is also accepted. Supplied duration aliases must agree. Omit all duration controls for `draft_task` reuse.

### `resolution` (string, Default: 720p)

`480p`, `720p`, or `1080p`. Native `size` may specify resolution; `metadata.resolution` has precedence. `4k` is not supported.

### `aspectRatio` (string, Default: 16:9)

`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, or `adaptive`. `aspect_ratio`, `ratio`, and `metadata.ratio` are accepted. Existing ratio values in `size` remain accepted for compatibility, but a resolution value in `size` means resolution. First/last-frame input requires `adaptive`; it is selected when frame roles are present without an explicit ratio.

### `metadata` (object)

Accepts `resolution`, `ratio`, `duration`, `content`, `generate_audio`, and `output_format`. Set `generate_audio` to a boolean for generated audio. Top-level `generateAudio` / `generate_audio` are aliases; use only one audio control.

### `imageUrls` (string[])

Reference images. `images`, `imageUrl`, `image_urls`, and `image_url` are aliases. Native `images` shorthand uses its first two images as first/last frames; `imageUrls` retains reference-image semantics.

### `imageWithRoles` (object[])

Role-based images with `url` and `role`: `first_frame`, `last_frame`, or `reference_image`. `image_with_roles` is an alias. Typed `metadata.content` is also accepted.

### `videoUrls` (string[])

Reference videos. `videoUrl`, `video_urls`, and `video_url` are aliases.

### `audioUrls` (string[])

Reference audio. `audioUrl`, `audio_urls`, and `audio_url` are aliases. Requires an image or video in the same request.

### `outputFormat` (string, Default: mp4)

`mp4` only. `output_format` and `metadata.output_format` are accepted. `mov` and `watermark` are not supported.

### `callback_url` (string)

Optional native callback URL. Availability depends on the selected channel; use `GET https://api.apihop.ai/v1/jobs/{jobId}` as the authoritative result.

## Multimodal Content

Media URLs may use public HTTP(S) URLs or existing `asset://` identifiers.

| Type | Nested field | Roles |
| --- | --- | --- |
| `image_url` | `image_url.url` | `first_frame`, `last_frame`, `reference_image` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |
| `draft_task` | `draft_task.id` | No role; sample reuse only |

Up to 30 images, 10 videos, and 10 audio files, with at most 50 media items total, are accepted across shorthand and typed content. Audio requires an image or video. Use top-level `prompt` instead of `type: "text"` content. Supply only one alias for each setting. Unsupported controls are rejected. Top-level `first_frame_url`, `last_frame_url`, `reference_image_urls`, `reference_video_urls`, and `reference_audio_urls` are role-specific shorthand. Unlisted fields inside content items are not forwarded.

## Draft-Task Reuse

`draft_task` is exclusive to Seedance 2.5. It reuses an existing compatible completed sample; this page does not define sample-creation controls.

- `metadata.content` must contain exactly one `draft_task` item.
- Prefer the existing sample's Synapse decimal-string `jobId` as `draft_task.id`.

An existing recorded platform `task_...` identifier is also accepted; do not use an upstream raw task ID or invent an identifier.

- The sample must belong to the same account, use the same model and processing

channel, be completed, and have been created less than 7 days ago.

- Do not supply prompt, image/video/audio inputs, duration, ratio, seed,

`generate_audio`, output format, or `omni_reference_task_type`. The sample's settings are reused.

- Output resolution may be supplied.

The compatibility and ownership checks may reject reuse even when the referenced task completed successfully. Do not assume every normal generation is a reusable sample.

## Request Examples

### Multimodal Reference

```json
{
  "model": "seedance-2.5",
  "prompt": "Keep the referenced character and camera movement in a coherent film",
  "seconds": "8",
  "size": "720p",
  "metadata": {
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/camera.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
    ]
  }
}
```

### First and Last Frames

```json
{
  "model": "seedance-2.5",
  "duration": 5,
  "metadata": {
    "ratio": "adaptive",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
    ]
  }
}
```

### Reuse an Existing Sample

Replace `EXISTING_SAMPLE_JOB_ID` with the actual compatible completed sample's returned `jobId`. The placeholder below is not a working task identifier.

```json
{
  "model": "seedance-2.5",
  "metadata": {
    "resolution": "1080p",
    "content": [
      {"type": "draft_task", "draft_task": {"id": "EXISTING_SAMPLE_JOB_ID"}}
    ]
  }
}
```

## Submission and Result

Response `data` contains `jobId`, `status`, `model`, and `message`. Submission success means the job was accepted, not completed. Poll `GET https://api.apihop.ai/v1/jobs/{jobId}` with the same account's API Key. See [Get Async Job](https://apihop.ai/en/docs/api-reference/jobs).

When status is `COMPLETED`, read `data.outputResult`. Accept both string and array values for each result object's `url`.

Seedance 2.5 の非同期ジョブを作成します。Seedance 2.0 については、専用のパラメータリファレンスを使用してください。

認証

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

リクエストボディ

modelstring必須

seedance-2.5 を指定します。

promptstring

動画のプロンプトです。テキストのみの生成では必須ですが、画像・動画の参照を指定する場合は省略または空欄にできます。draft_task を再利用する場合は省略してください。 metadata.content のテキスト項目は破棄され、最上位の prompt が正式な入力として使用されます。

durationnumber既定値: 5

4 から 30 までの整数、または長さを自動設定する -1 を指定します。ネイティブの seconds は、同等の整数文字列を受け付けます。metadata.duration も使用できます。長さの別名を複数指定する場合は、値を一致させる必要があります。 draft_task を再利用する場合は、長さに関する制御をすべて省略してください。

resolutionstring既定値: 720p

480p、720p、1080p のいずれかです。ネイティブの size でも解像度を指定できます。metadata.resolution が優先されます。4k には対応していません。

aspectRatiostring既定値: 16:9

16:9、9:16、1:1、4:3、3:4、21:9、adaptive のいずれかです。 aspect_ratio、ratio、metadata.ratio を受け付けます。互換性のため、既存の size 内の比率値は引き続き受け付けますが、size に解像度の値を指定した場合は解像度として扱われます。開始・終了フレームの入力には adaptive が必要です。フレームの役割を指定し、比率を明示しない場合は、自動的にこの値が選択されます。

metadataobject

resolution、ratio、duration、content、generate_audio、output_format を受け付けます。音声生成には generate_audio に真偽値を設定してください。最上位の generateAudio / generate_audio は別名です。音声の制御は 1 つだけ使用してください。

imageUrlsstring[]

参照画像です。images、imageUrl、image_urls、image_url は別名です。ネイティブの images の省略記法では、先頭 2 枚の画像を開始・終了フレームとして使用します。imageUrls は参照画像としての意味を維持します。

imageWithRolesobject[]

url と role を持つ、役割付きの画像です。役割は first_frame、last_frame、reference_image のいずれかです。image_with_roles は別名です。型を指定した metadata.content も受け付けます。

videoUrlsstring[]

参照動画です。videoUrl、video_urls、video_url は別名です。

audioUrlsstring[]

参照音声です。audioUrl、audio_urls、audio_url は別名です。同じリクエスト内に画像または動画が必要です。

outputFormatstring既定値: mp4

mp4 のみです。output_format と metadata.output_format を受け付けます。 mov と watermark には対応していません。

callback_urlstring

任意のネイティブコールバック URL です。利用可否は選択したチャネルによって異なります。結果の正式な判断基準には GET https://api.apihop.ai/v1/jobs/{jobId} を使用してください。

マルチモーダルコンテンツ

メディア URL には、公開 HTTP(S) URL または既存の asset:// 識別子を使用できます。

種類	入れ子のフィールド	役割
`image_url`	`image_url.url`	`first_frame`、`last_frame`、`reference_image`
`video_url`	`video_url.url`	`reference_video`
`audio_url`	`audio_url.url`	`reference_audio`
`draft_task`	`draft_task.id`	役割なし。サンプルの再利用のみ

省略記法と型付きコンテンツを合わせて、画像は最大 30 枚、動画は最大 10 本、音声は最大 10 ファイル、メディア項目の合計は最大 50 件まで受け付けます。音声には画像または動画が必要です。type: "text" のコンテンツではなく、最上位の prompt を使用してください。各設定には別名を 1 つだけ指定してください。未対応の制御は拒否されます。最上位の first_frame_url、last_frame_url、reference_image_urls、reference_video_urls、reference_audio_urls は、役割別の省略記法です。コンテンツ項目内の、一覧にないフィールドは転送されません。

ドラフトタスクの再利用

draft_task は Seedance 2.5 専用です。既存の互換性のある完了済みサンプルを再利用します。このページでは、サンプルを作成するための制御は定義しません。

metadata.content には、draft_task の項目をちょうど 1 つ含める必要があります。
draft_task.id には、既存のサンプルの Synapse の 10 進数文字列 jobId を優先して使用してください。プラットフォームに記録されている既存の task_... 識別子も受け付けます。上流の生のタスク ID を使用したり、識別子を作り上げたりしないでください。
サンプルは同じアカウントに属し、同じモデルと処理チャネルを使用し、完了済みで、作成から 7 日未満である必要があります。
プロンプト、画像・動画・音声の入力、長さ、比率、シード、generate_audio、出力形式、omni_reference_task_type を指定しないでください。サンプルの設定が再利用されます。
出力解像度は指定できます。

参照先のタスクが正常に完了していても、互換性や所有権の確認によって再利用が拒否される場合があります。通常の生成結果がすべて再利用可能なサンプルになるとは想定しないでください。

リクエスト例

マルチモーダル参照

json

{
  "model": "seedance-2.5",
  "prompt": "Keep the referenced character and camera movement in a coherent film",
  "seconds": "8",
  "size": "720p",
  "metadata": {
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/camera.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
    ]
  }
}

開始フレームと終了フレーム

json

{
  "model": "seedance-2.5",
  "duration": 5,
  "metadata": {
    "ratio": "adaptive",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
    ]
  }
}

既存サンプルの再利用

EXISTING_SAMPLE_JOB_ID を、実際の互換性のある完了済みサンプルから返された jobId に置き換えてください。以下のプレースホルダーは、実際に動作するタスク識別子ではありません。

json

{
  "model": "seedance-2.5",
  "metadata": {
    "resolution": "1080p",
    "content": [
      {"type": "draft_task", "draft_task": {"id": "EXISTING_SAMPLE_JOB_ID"}}
    ]
  }
}

送信と結果

レスポンスの data には jobId、status、model、message が含まれます。送信の成功は、ジョブが受け付けられたことを意味し、完了を意味するものではありません。同じアカウントの API キーで GET https://api.apihop.ai/v1/jobs/{jobId} をポーリングしてください。非同期ジョブの取得を参照してください。

状態が COMPLETED になったら data.outputResult を読み取ってください。各結果オブジェクトの url は、文字列と配列の両方を扱えるようにしてください。