Pembuatan Video Seedance 2.5 | Dokumentasi 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`.

Buat tugas Seedance 2.5 asinkron. Untuk Seedance 2.0, gunakan referensi parameter terpisahnya.

Autentikasi

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Isi

modelstringwajib

seedance-2.5.

promptstring

Prompt video. Wajib untuk pembuatan hanya dari teks; dapat dihilangkan atau dikosongkan jika referensi gambar/video disediakan. Hilangkan untuk penggunaan ulang draft_task. Item teks metadata.content dibuang; prompt tingkat atas menjadi acuan.

durationnumberBawaan: 5

Bilangan bulat dari 4 hingga 30, atau -1 untuk durasi otomatis. seconds native menerima string bilangan bulat yang setara. metadata.duration juga diterima. Alias durasi yang disediakan harus bernilai sama. Hilangkan semua kontrol durasi untuk penggunaan ulang draft_task.

resolutionstringBawaan: 720p

480p, 720p, atau 1080p. size native dapat menentukan resolusi; metadata.resolution diprioritaskan. 4k tidak didukung.

aspectRatiostringBawaan: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9, atau adaptive. aspect_ratio, ratio, dan metadata.ratio diterima. Nilai rasio yang ada dalam size tetap diterima demi kompatibilitas, tetapi nilai resolusi dalam size berarti resolusi. Masukan bingkai pertama/terakhir memerlukan adaptive; nilai ini dipilih ketika ada peran bingkai tanpa rasio eksplisit.

metadataobject

Menerima resolution, ratio, duration, content, generate_audio, dan output_format. Atur generate_audio ke boolean untuk audio yang dihasilkan. generateAudio / generate_audio tingkat atas adalah alias; gunakan hanya satu kontrol audio.

imageUrlsstring[]

Gambar referensi. images, imageUrl, image_urls, dan image_url adalah alias. Bentuk singkat images native menggunakan dua gambar pertamanya sebagai bingkai pertama/terakhir; imageUrls mempertahankan semantik gambar referensi.

imageWithRolesobject[]

Gambar berbasis peran dengan url dan role: first_frame, last_frame, atau reference_image. image_with_roles adalah alias. metadata.content bertipe juga diterima.

videoUrlsstring[]

Video referensi. videoUrl, video_urls, dan video_url adalah alias.

audioUrlsstring[]

Audio referensi. audioUrl, audio_urls, dan audio_url adalah alias. Memerlukan gambar atau video dalam permintaan yang sama.

outputFormatstringBawaan: mp4

Hanya mp4. output_format dan metadata.output_format diterima. mov dan watermark tidak didukung.

callback_urlstring

URL callback native opsional. Ketersediaan bergantung pada kanal yang dipilih; gunakan GET https://api.apihop.ai/v1/jobs/{jobId} sebagai hasil otoritatif.

Konten Multimodal

URL media dapat menggunakan URL HTTP(S) publik atau pengenal asset:// yang sudah ada.

Jenis	Kolom Bertingkat	Peran
`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`	Tanpa peran; hanya penggunaan ulang sampel

Hingga 30 gambar, 10 video, dan 10 file audio, dengan total maksimal 50 item media, diterima di seluruh bentuk singkat dan konten bertipe. Audio memerlukan gambar atau video. Gunakan prompt tingkat atas, bukan konten type: "text". Berikan hanya satu alias untuk setiap pengaturan. Kontrol yang tidak didukung ditolak. first_frame_url, last_frame_url, reference_image_urls, reference_video_urls, dan reference_audio_urls tingkat atas adalah bentuk singkat khusus peran. Kolom yang tidak tercantum dalam item konten tidak diteruskan.

Penggunaan Ulang Tugas Draf

draft_task khusus untuk Seedance 2.5. Fitur ini menggunakan ulang sampel kompatibel yang sudah selesai; halaman ini tidak menentukan kontrol pembuatan sampel.

metadata.content harus berisi tepat satu item draft_task.
Utamakan jobId Synapse berupa string desimal dari sampel yang ada sebagai draft_task.id.

Pengenal platform task_... yang sudah tercatat juga diterima; jangan gunakan ID tugas mentah upstream atau mengarang pengenal.

Sampel harus dimiliki akun yang sama, menggunakan model dan kanal pemrosesan

yang sama, telah selesai, dan dibuat kurang dari 7 hari yang lalu.

Jangan berikan prompt, masukan gambar/video/audio, durasi, rasio, seed,

generate_audio, format keluaran, atau omni_reference_task_type. Pengaturan sampel digunakan ulang.

Resolusi keluaran boleh disediakan.

Pemeriksaan kompatibilitas dan kepemilikan dapat menolak penggunaan ulang meskipun tugas yang dirujuk berhasil diselesaikan. Jangan menganggap setiap pembuatan normal merupakan sampel yang dapat digunakan ulang.

Contoh Permintaan

Referensi Multimodal

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

Bingkai Pertama dan Terakhir

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

Gunakan Ulang Sampel yang Ada

Ganti EXISTING_SAMPLE_JOB_ID dengan jobId yang dikembalikan oleh sampel kompatibel yang benar-benar selesai. Placeholder di bawah bukan pengenal tugas yang dapat digunakan.

json

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

Pengiriman dan Hasil

data respons berisi jobId, status, model, dan message. Keberhasilan pengiriman berarti tugas diterima, bukan selesai. Lakukan polling GET https://api.apihop.ai/v1/jobs/{jobId} dengan API Key akun yang sama. Lihat Ambil Tugas Asinkron.

Saat status COMPLETED, baca data.outputResult. Terima nilai string maupun larik untuk url setiap objek hasil.