Generowanie wideo Seedance 2.5 | Dokumentacja 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`.

Utwórz asynchroniczne zadanie Seedance 2.5. Dla Seedance 2.0 skorzystaj z oddzielnej dokumentacji parametrów.

Uwierzytelnianie

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Treść żądania

modelstringWymagane

seedance-2.5.

promptstring

Prompt wideo. Wymagany przy generowaniu wyłącznie z tekstu; można go pominąć lub pozostawić pusty, gdy dostarczono referencje obrazowe/wideo. Pomiń go przy ponownym użyciu draft_task. Elementy tekstowe metadata.content są odrzucane; wiążący jest prompt na najwyższym poziomie.

durationnumberWartość domyślna: 5

Liczba całkowita od 4 do 30 lub -1 dla automatycznego czasu trwania. Natywne seconds przyjmuje równoważny ciąg znaków liczby całkowitej. Akceptowane jest także metadata.duration. Podane aliasy czasu trwania muszą być zgodne. Przy ponownym użyciu draft_task pomiń wszystkie ustawienia czasu trwania.

resolutionstringWartość domyślna: 720p

480p, 720p lub 1080p. Natywne size może określać rozdzielczość; metadata.resolution ma pierwszeństwo. 4k nie jest obsługiwane.

aspectRatiostringWartość domyślna: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 lub adaptive. Akceptowane są aspect_ratio, ratio i metadata.ratio. Istniejące wartości proporcji w size nadal są przyjmowane dla zgodności, ale wartość rozdzielczości w size oznacza rozdzielczość. Wejście pierwszej/ostatniej klatki wymaga adaptive; ta wartość jest wybierana, gdy podano role klatek bez jawnych proporcji.

metadataobject

Przyjmuje resolution, ratio, duration, content, generate_audio i output_format. Ustaw generate_audio na wartość logiczną dla generowanego dźwięku. generateAudio / generate_audio na najwyższym poziomie są aliasami; używaj tylko jednego ustawienia dźwięku.

imageUrlsstring[]

Obrazy referencyjne. images, imageUrl, image_urls i image_url są aliasami. Natywny skrót images używa pierwszych dwóch obrazów jako pierwszej/ostatniej klatki; imageUrls zachowuje semantykę obrazów referencyjnych.

imageWithRolesobject[]

Obrazy o określonych rolach z url i role: first_frame, last_frame lub reference_image. image_with_roles jest aliasem. Akceptowane jest także metadata.content z określonymi typami.

videoUrlsstring[]

Referencyjne wideo. videoUrl, video_urls i video_url są aliasami.

audioUrlsstring[]

Referencyjny dźwięk. audioUrl, audio_urls i audio_url są aliasami. Wymaga obrazu lub wideo w tym samym żądaniu.

outputFormatstringWartość domyślna: mp4

Tylko mp4. Akceptowane są output_format i metadata.output_format. mov i watermark nie są obsługiwane.

callback_urlstring

Opcjonalny natywny adres URL wywołania zwrotnego. Dostępność zależy od wybranego kanału; traktuj GET https://api.apihop.ai/v1/jobs/{jobId} jako wiążący wynik.

Treść multimodalna

Adresy multimediów mogą używać publicznych adresów URL HTTP(S) lub istniejących identyfikatorów asset://.

Typ	Zagnieżdżone pole	Role
`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`	Bez roli; tylko ponowne użycie próbki

Akceptowanych jest do 30 obrazów, 10 plików wideo i 10 plików audio, maksymalnie 50 elementów multimedialnych łącznie, w skróconym zapisie i treści z określonym typem. Dźwięk wymaga obrazu lub wideo. Używaj prompt na najwyższym poziomie zamiast treści type: "text". Podawaj tylko jeden alias dla każdego ustawienia. Nieobsługiwane ustawienia są odrzucane. Pola najwyższego poziomu first_frame_url, last_frame_url, reference_image_urls, reference_video_urls i reference_audio_urls są skrótami dla określonych ról. Niewymienione pola wewnątrz elementów treści nie są przekazywane dalej.

Ponowne użycie zadania próbnego

draft_task jest dostępne wyłącznie w Seedance 2.5. Ponownie wykorzystuje istniejącą zgodną ukończoną próbkę; ta strona nie definiuje ustawień tworzenia próbek.

metadata.content musi zawierać dokładnie jeden element draft_task.
Preferuj jobId istniejącej próbki Synapse zapisany jako dziesiętny ciąg znaków w draft_task.id. Akceptowany jest także istniejący zapisany identyfikator platformy task_...; nie używaj surowego identyfikatora zadania dostawcy ani nie wymyślaj identyfikatora.
Próbka musi należeć do tego samego konta, używać tego samego modelu i kanału przetwarzania, być ukończona i utworzona mniej niż 7 dni temu.
Nie podawaj promptu, wejść obrazowych/wideo/audio, czasu trwania, proporcji, ziarna, generate_audio, formatu wyjściowego ani omni_reference_task_type. Ustawienia próbki są używane ponownie.
Można podać rozdzielczość wyjściową.

Kontrole zgodności i własności mogą odrzucić ponowne użycie nawet wtedy, gdy wskazane zadanie zakończyło się pomyślnie. Nie zakładaj, że każde zwykłe generowanie jest próbką nadającą się do ponownego użycia.

Przykłady żądań

Referencja multimodalna

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

Pierwsza i ostatnia klatka

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

Użyj ponownie istniejącej próbki

Zastąp EXISTING_SAMPLE_JOB_ID zwróconym jobId rzeczywistej, zgodnej i ukończonej próbki. Poniższy symbol zastępczy nie jest działającym identyfikatorem zadania.

json

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

Zgłoszenie i wynik

Pole data odpowiedzi zawiera jobId, status, model i message. Powodzenie zgłoszenia oznacza przyjęcie zadania, a nie jego zakończenie. Odpytuj GET https://api.apihop.ai/v1/jobs/{jobId} kluczem API tego samego konta. Zobacz pobieranie zadania asynchronicznego.

Gdy stan to COMPLETED, odczytaj data.outputResult. Akceptuj zarówno ciąg znaków, jak i tablicę jako wartość url w każdym obiekcie wyniku.