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 是別名，僅使用一個音訊控制欄位。

imageUrlsstring[]

參考圖像。images、imageUrl、image_urls 與 image_url 是別名。原生 images 簡寫將前兩張圖像作為首尾影格；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

選填的原生回呼網址。是否可用取決於所選通道；請以 GET https://api.apihop.ai/v1/jobs/{jobId} 作為權威結果。

多模態內容

媒體網址可使用公開 HTTP(S) 網址或既有的 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。音訊必須搭配圖像或影片。請使用頂層 prompt，不要使用 type: "text" 內容。每個設定僅提供一個別名。不支援的控制欄位會遭拒。頂層 first_frame_url、last_frame_url、reference_image_urls、reference_video_urls 與 reference_audio_urls 是特定角色的簡寫。內容項目內未列出的欄位不會被轉送。

草稿任務重用

draft_task 僅適用於 Seedance 2.5，用來重用既有、相容且已完成的樣本；本頁未定義建立樣本的控制欄位。

metadata.content 必須恰好包含一個 draft_task 項目。
建議使用既有樣本的 Synapse 十進位字串 jobId 作為 draft_task.id。也接受平台已記錄的 task_... 識別碼；請勿使用上游原始任務 ID 或虛構識別碼。
樣本必須屬於同一帳號，使用相同模型與處理通道，已完成，且建立時間距今不到 7 天。
請勿提供提示詞、圖像／影片／音訊輸入、時長、長寬比、seed、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 應同時接受字串與陣列值。