Seedance 2.0 影片生成 | API 文件

# Seedance 2.0 Video Generation

Seedance 2.0 text, first/last-frame, multimodal, and audio generation parameters.

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

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

## Authentication

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

## Body

### `model` (string, required)

`seedance-2.0` or its alias `seedance-2-0`.

### `prompt` (string)

Video prompt. Required for text-only generation; may be omitted or blank when image or video references are supplied. Audio alone is not a valid input. Text items inside `metadata.content` are discarded; only this top-level prompt is used.

### `seconds` (string, Default: 5)

Integer string from `"4"` through `"15"`. The numeric `duration` alias is also accepted. If both are supplied, they must agree. Automatic duration (`-1`) is not supported.

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

Output resolution: `480p`, `720p`, `1080p`, or `4k`. Not an aspect ratio. Resolution precedence: `metadata.resolution`, `size`, then `resolution`.

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

`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, or `adaptive`. `aspect_ratio` and `ratio` are aliases; `metadata.ratio` takes precedence. Use one alias for each setting.

### `metadata` (object)

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

### `images` (string[])

Image shorthand: the first image is the first frame and the second is the last frame. For precise roles, use `metadata.content`. Existing `imageUrls`, `imageUrl`, `image_urls`, and `image_url` aliases remain accepted with the same frame semantics.

### `imageWithRoles` (object[])

Images with `url` and `role`: `first_frame`, `last_frame`, or `reference_image`. `image_with_roles` is an alias. Both versions also accept typed `metadata.content`.

### `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 reference in the same request.

### `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

Each `metadata.content` media item contains its matching nested URL object. Media URLs may use public HTTP(S) URLs or existing `asset://` identifiers.

| Type | URL 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` |

Up to 9 images, 3 videos, and 3 audio files are accepted, including shorthand and typed content. Audio requires an image or video. `draft_task` is not supported. Use top-level `prompt` instead of `type: "text"` content items. 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.

Unsupported controls such as `negativePrompt`, `seed`, `returnLastFrame`, `nsfwCheck`, `tools`, `webhook`, `watermark`, `outputFormat`, and their snake-case aliases are rejected. `width`, `height`, `fps`, `cfgScale`, `steps`, and `style` are not supported.

## Request Examples

### Text-to-Video

```json
{
  "model": "seedance-2.0",
  "prompt": "A quiet city street at dawn, slow forward camera movement",
  "seconds": "5",
  "size": "720p",
  "metadata": {"ratio": "16:9", "generate_audio": true}
}
```

### First and Last Frames

```json
{
  "model": "seedance-2.0",
  "seconds": "5",
  "metadata": {
    "resolution": "720p",
    "ratio": "9:16",
    "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"}
    ]
  }
}
```

### Image and Audio References

```json
{
  "model": "seedance-2.0",
  "prompt": "Animate the scene to match the rhythm",
  "metadata": {
    "resolution": "720p",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "asset://existing-image-id"}, "role": "reference_image"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/beat.mp3"}, "role": "reference_audio"}
    ]
  }
}
```

## 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 a string `url` and an array of URLs in each result object. Charges depend on actual completion tokens and output resolution; video references select the video-input rate, while image/audio-only references do not.

建立非同步 Seedance 2.0 任務。Seedance 2.5 請使用其獨立參數參考。

驗證

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

請求主體

modelstring必填

seedance-2.0 或其別名 seedance-2-0。

promptstring

影片提示詞。純文字生成時必填；提供圖像或影片參考時可省略或留空。只有音訊不構成有效輸入。metadata.content 中的文字項目會被捨棄，只使用此頂層提示詞。

secondsstring預設: 5

從 "4" 到 "15" 的整數字串。也接受數值別名 duration；若兩者皆提供，必須一致。不支援自動時長（-1）。

sizestring預設: 720p

輸出解析度：480p、720p、1080p 或 4k，不是長寬比。解析度優先順序為 metadata.resolution、size，再到 resolution。

aspectRatiostring預設: 16:9

16:9、9:16、1:1、4:3、3:4、21:9 或 adaptive。aspect_ratio 與 ratio 是別名；metadata.ratio 優先。每個設定僅使用一個別名。

metadataobject

接受 resolution、ratio、content 與 generate_audio。將 generate_audio 設為布林值以控制音訊生成。頂層 generateAudio / generate_audio 是別名，僅提供一個音訊控制欄位。

imagesstring[]

圖像簡寫：第一張圖像為首影格，第二張為尾影格。需要精確角色時請使用 metadata.content。既有的 imageUrls、imageUrl、image_urls 與 image_url 別名仍可使用，且具有相同影格語義。

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 是別名。同一請求中必須有圖像或影片參考。

callback_urlstring

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

多模態內容

每個 metadata.content 媒體項目都包含對應的巢狀 URL 物件。媒體網址可使用公開 HTTP(S) 網址或既有的 asset:// 識別碼。

類型	URL 欄位	角色
`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`

含簡寫與具類型內容在內，最多接受 9 張圖像、3 部影片與 3 個音訊檔案。音訊必須搭配圖像或影片。不支援 draft_task。請使用頂層 prompt，不要使用 type: "text" 內容項目。頂層 first_frame_url、last_frame_url、reference_image_urls、reference_video_urls 與 reference_audio_urls 是特定角色的簡寫。內容項目內未列出的欄位不會被轉送。

不支援的控制欄位會遭拒，包括 negativePrompt、seed、returnLastFrame、nsfwCheck、tools、webhook、watermark、outputFormat 及其蛇形命名別名。也不支援 width、height、fps、cfgScale、steps 與 style。

請求範例

文字轉影片

json

{
  "model": "seedance-2.0",
  "prompt": "A quiet city street at dawn, slow forward camera movement",
  "seconds": "5",
  "size": "720p",
  "metadata": {"ratio": "16:9", "generate_audio": true}
}

首尾影格

json

{
  "model": "seedance-2.0",
  "seconds": "5",
  "metadata": {
    "resolution": "720p",
    "ratio": "9:16",
    "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"}
    ]
  }
}

圖像與音訊參考

json

{
  "model": "seedance-2.0",
  "prompt": "Animate the scene to match the rhythm",
  "metadata": {
    "resolution": "720p",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "asset://existing-image-id"}, "role": "reference_image"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/beat.mp3"}, "role": "reference_audio"}
    ]
  }
}

提交與結果

回應的 data 包含 jobId、status、model 與 message。提交成功代表任務已受理，不代表已完成。請使用同一帳號的 API 金鑰輪詢 GET https://api.apihop.ai/v1/jobs/{jobId}。詳見查詢非同步任務。

狀態為 COMPLETED 時，讀取 data.outputResult。每個結果物件應同時接受字串 url 或網址陣列。費用取決於實際完成 token 與輸出解析度；使用影片參考會套用影片輸入費率，僅有圖像／音訊參考則不會。