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

Tạo công việc Seedance 2.5 bất đồng bộ. Với Seedance 2.0, 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.5.

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/video tham chiếu. Bỏ khi tái sử dụng draft_task. Mục văn bản metadata.content bị bỏ; prompt cấp cao nhất là nguồn có thẩm quyền.

durationnumberMặc định: 5

Số nguyên từ 4 đến 30, hoặc -1 cho thời lượng tự động. seconds nguyên bản chấp nhận chuỗi số nguyên tương đương. Cũng chấp nhận metadata.duration. Bí danh thời lượng được cung cấp phải khớp. Bỏ mọi điều khiển thời lượng khi tái sử dụng draft_task.

resolutionstringMặc định: 720p

480p, 720p hoặc 1080p. size nguyên bản có thể chỉ định độ phân giải; metadata.resolution được ưu tiên. Không hỗ trợ 4k.

aspectRatiostringMặc định: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 hoặc adaptive. Chấp nhận aspect_ratio, ratio và metadata.ratio. Giá trị tỷ lệ hiện có trong size vẫn được chấp nhận để tương thích, nhưng giá trị độ phân giải trong size có nghĩa là độ phân giải. Đầu vào khung đầu/cuối yêu cầu adaptive; giá trị này được chọn khi có vai trò khung hình mà không có tỷ lệ rõ ràng.

metadataobject

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

imageUrlsstring[]

Ảnh tham chiếu. images, imageUrl, image_urls và image_url là bí danh. Dạng rút gọn images nguyên bản dùng hai ảnh đầu làm khung đầu/cuối; imageUrls giữ ngữ nghĩa ảnh tham chiếu.

imageWithRolesobject[]

Ảnh theo vai trò có url và role: first_frame, last_frame hoặc reference_image. image_with_roles là bí danh. 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 trong cùng yêu cầu.

outputFormatstringMặc định: mp4

Chỉ mp4. Chấp nhận output_format và metadata.output_format. Không hỗ trợ mov và watermark.

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

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 lồng	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`
`draft_task`	`draft_task.id`	Không có vai trò; chỉ tái sử dụng mẫu

Chấp nhận tối đa 30 ảnh, 10 video và 10 tệp âm thanh, tổng không quá 50 mục đa phương tiện, tính cả dạng rút gọn và nội dung có kiểu. Âm thanh yêu cầu ảnh hoặc video. Dùng prompt cấp cao nhất thay cho nội dung type: "text". Chỉ cung cấp một bí danh cho mỗi cài đặt. Điều khiển không được hỗ trợ bị từ chối. 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.

Tái sử dụng tác vụ nháp

draft_task chỉ có ở Seedance 2.5. Nó tái sử dụng mẫu hiện có đã hoàn tất và tương thích; trang này không định nghĩa điều khiển tạo mẫu.

metadata.content phải chứa đúng một mục draft_task.
Ưu tiên jobId Synapse dạng chuỗi thập phân của mẫu hiện có làm draft_task.id. Cũng chấp nhận mã định danh nền tảng task_... đã ghi nhận; không dùng ID tác vụ thượng nguồn thô hoặc tự tạo mã định danh.
Mẫu phải thuộc cùng tài khoản, dùng cùng mô hình và kênh xử lý, đã hoàn tất và được tạo chưa đầy 7 ngày trước.
Không cung cấp prompt, đầu vào ảnh/video/âm thanh, thời lượng, tỷ lệ, seed, generate_audio, định dạng đầu ra hoặc omni_reference_task_type. Cài đặt mẫu được tái sử dụng.
Có thể cung cấp độ phân giải đầu ra.

Kiểm tra tương thích và quyền sở hữu có thể từ chối tái sử dụng ngay cả khi tác vụ được tham chiếu đã hoàn tất thành công. Đừng giả định mọi lần tạo thông thường đều là mẫu có thể tái sử dụng.

Ví dụ yêu cầu

Tham chiếu đa phương thức

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

Khung đầu và cuối

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

Tái sử dụng mẫu hiện có

Thay EXISTING_SAMPLE_JOB_ID bằng jobId thực tế trả về của mẫu tương thích đã hoàn tất. Giá trị giữ chỗ bên dưới không phải mã định danh tác vụ hoạt động.

json

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

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ả giá trị chuỗi và mảng cho url của mỗi đối tượng kết quả.