Tạo video Seedance 2.0 | Tài liệu 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.

Tạo công việc Seedance 2.0 bất đồng bộ. Với Seedance 2.5, dùng tham chiếu tham số riêng.

Xác thực

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Thân yêu cầu

modelstringbắt buộc

seedance-2.0 hoặc bí danh seedance-2-0.

promptstring

Prompt video. Bắt buộc khi chỉ tạo từ văn bản; có thể bỏ hoặc để trống khi cung cấp ảnh hoặc video tham chiếu. Chỉ âm thanh không phải đầu vào hợp lệ. Mục văn bản trong metadata.content bị bỏ; chỉ dùng prompt cấp cao nhất này.

secondsstringMặc định: 5

Chuỗi số nguyên từ "4" đến "15". Cũng chấp nhận bí danh số duration. Nếu cung cấp cả hai, chúng phải khớp. Không hỗ trợ thời lượng tự động (-1).

sizestringMặc định: 720p

Độ phân giải đầu ra: 480p, 720p, 1080p hoặc 4k. Không phải tỷ lệ khung hình. Thứ tự ưu tiên độ phân giải: metadata.resolution, size, rồi resolution.

aspectRatiostringMặc định: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 hoặc adaptive. aspect_ratio và ratio là bí danh; metadata.ratio được ưu tiên. Dùng một bí danh cho mỗi cài đặt.

metadataobject

Chấp nhận resolution, ratio, content và generate_audio. Đặt generate_audio thành boolean để điều khiển âm thanh được tạo. generateAudio / generate_audio cấp cao nhất là bí danh; chỉ cung cấp một điều khiển âm thanh.

imagesstring[]

Dạng rút gọn cho ảnh: ảnh đầu là khung đầu và ảnh thứ hai là khung cuối. Để chỉ định vai trò chính xác, dùng metadata.content. Các bí danh hiện có imageUrls, imageUrl, image_urls và image_url vẫn được chấp nhận với cùng ngữ nghĩa khung hình.

imageWithRolesobject[]

Ảnh có url và role: first_frame, last_frame hoặc reference_image. image_with_roles là bí danh. Cả hai phiên bản cũng chấp nhận metadata.content có kiểu.

videoUrlsstring[]

Video tham chiếu. videoUrl, video_urls và video_url là bí danh.

audioUrlsstring[]

Âm thanh tham chiếu. audioUrl, audio_urls và audio_url là bí danh. Yêu cầu ảnh hoặc video tham chiếu trong cùng yêu cầu.

callback_urlstring

URL gọi lại nguyên bản tùy chọn. Khả dụng phụ thuộc kênh được chọn; dùng GET https://api.apihop.ai/v1/jobs/{jobId} làm kết quả có thẩm quyền.

Nội dung đa phương thức

Mỗi mục đa phương tiện metadata.content chứa đối tượng URL lồng tương ứng. URL đa phương tiện có thể dùng URL HTTP(S) công khai hoặc mã định danh asset:// hiện có.

Loại	Trường URL	Vai trò
`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`

Chấp nhận tối đa 9 ảnh, 3 video và 3 tệp âm thanh, gồm dạng rút gọn và nội dung có kiểu. Âm thanh yêu cầu ảnh hoặc video. Không hỗ trợ draft_task. Dùng prompt cấp cao nhất thay cho mục nội dung type: "text". Các trường cấp cao nhất first_frame_url, last_frame_url, reference_image_urls, reference_video_urls và reference_audio_urls là dạng rút gọn theo vai trò. Trường không liệt kê trong mục nội dung không được chuyển tiếp.

Điều khiển không được hỗ trợ như negativePrompt, seed, returnLastFrame, nsfwCheck, tools, webhook, watermark, outputFormat và bí danh snake-case của chúng bị từ chối. Không hỗ trợ width, height, fps, cfgScale, steps và style.

Ví dụ yêu cầu

Văn bản thành 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}
}

Khung đầu và cuối

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"}
    ]
  }
}

Tham chiếu ảnh và âm thanh

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"}
    ]
  }
}

Gửi và nhận kết quả

data phản hồi chứa jobId, status, model và message. Gửi thành công nghĩa là công việc đã được chấp nhận, chưa hoàn tất. Truy vấn GET https://api.apihop.ai/v1/jobs/{jobId} bằng khóa API cùng tài khoản. Xem Lấy công việc bất đồng bộ.

Khi trạng thái là COMPLETED, đọc data.outputResult. Chấp nhận cả url dạng chuỗi và mảng URL trong mỗi đối tượng kết quả. Phí phụ thuộc token hoàn tất thực tế và độ phân giải đầu ra; video tham chiếu chọn giá đầu vào video, còn tham chiếu chỉ ảnh/âm thanh thì không.