Seedance 2.5 Videoerzeugung | API-Dokumentation

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

Erstellen Sie einen asynchronen Seedance-2.5-Auftrag. Für Seedance 2.0 verwenden Sie die separate Parameterreferenz.

Authentifizierung

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anfragekörper

modelstringerforderlich

seedance-2.5.

promptstring

Videoprompt. Für reine Texterzeugung erforderlich; bei Bild-/Videoreferenzen darf er fehlen oder leer sein. Lassen Sie ihn bei Wiederverwendung von draft_task weg. Textelemente in metadata.content werden verworfen; maßgeblich ist der oberste prompt.

durationnumberStandard: 5

Ganzzahl von 4 bis 30 oder -1 für automatische Dauer. Das native seconds akzeptiert die entsprechende Ganzzahlzeichenfolge. metadata.duration wird ebenfalls akzeptiert. Angegebene Daueraliase müssen übereinstimmen. Lassen Sie bei Wiederverwendung von draft_task sämtliche Dauersteuerungen weg.

resolutionstringStandard: 720p

480p, 720p oder 1080p. Das native size kann die Auflösung angeben; metadata.resolution hat Vorrang. 4k wird nicht unterstützt.

aspectRatiostringStandard: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 oder adaptive. aspect_ratio, ratio und metadata.ratio werden akzeptiert. Vorhandene Seitenverhältnisse in size bleiben aus Kompatibilitätsgründen gültig; ein Auflösungswert in size bezeichnet jedoch die Auflösung. Eingaben für erstes/letztes Bild erfordern adaptive; dies wird gewählt, wenn Bildrollen ohne ausdrückliches Seitenverhältnis vorliegen.

metadataobject

Akzeptiert resolution, ratio, duration, content, generate_audio und output_format. Setzen Sie generate_audio für erzeugtes Audio auf einen booleschen Wert. Die obersten Felder generateAudio / generate_audio sind Aliasse; verwenden Sie nur eine Audiosteuerung.

imageUrlsstring[]

Referenzbilder. images, imageUrl, image_urls und image_url sind Aliasse. Die native Kurzform images verwendet ihre ersten beiden Bilder als erstes/letztes Videobild; imageUrls behält die Bedeutung als Referenzbilder.

imageWithRolesobject[]

Rollenbasierte Bilder mit url und role: first_frame, last_frame oder reference_image. image_with_roles ist ein Alias. Typisierte metadata.content werden ebenfalls akzeptiert.

videoUrlsstring[]

Referenzvideos. videoUrl, video_urls und video_url sind Aliasse.

audioUrlsstring[]

Referenzaudio. audioUrl, audio_urls und audio_url sind Aliasse. Erfordert ein Bild oder Video in derselben Anfrage.

outputFormatstringStandard: mp4

Nur mp4. output_format und metadata.output_format werden akzeptiert. mov und watermark werden nicht unterstützt.

callback_urlstring

Optionale native Callback-URL. Die Verfügbarkeit hängt vom gewählten Kanal ab; verwenden Sie GET https://api.apihop.ai/v1/jobs/{jobId} als maßgebliches Ergebnis.

Multimodale Inhalte

Medien-URLs können öffentliche HTTP(S)-URLs oder vorhandene asset://-Kennungen sein.

Typ	Verschachteltes Feld	Rollen
`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`	Keine Rolle; nur Wiederverwendung einer Vorlage

Über Kurzformen und typisierte Inhalte hinweg werden bis zu 30 Bilder, 10 Videos und 10 Audiodateien mit insgesamt höchstens 50 Medienelementen akzeptiert. Audio erfordert ein Bild oder Video. Verwenden Sie den obersten prompt statt type: "text"-Inhalten. Geben Sie je Einstellung nur einen Alias an. Nicht unterstützte Steuerungen werden abgelehnt. Die obersten Felder first_frame_url, last_frame_url, reference_image_urls, reference_video_urls und reference_audio_urls sind rollenspezifische Kurzformen. Nicht aufgeführte Felder innerhalb von Inhaltselementen werden nicht weitergeleitet.

Entwurfsaufgabe wiederverwenden

draft_task gibt es nur in Seedance 2.5. Es verwendet eine vorhandene kompatible abgeschlossene Vorlage erneut; diese Seite definiert keine Steuerungen zur Vorlagenerstellung.

metadata.content muss genau ein draft_task-Element enthalten.
Verwenden Sie bevorzugt die dezimale Synapse-Zeichenfolge jobId der vorhandenen Vorlage als draft_task.id. Eine vorhandene gespeicherte Plattformkennung task_... wird ebenfalls akzeptiert; verwenden Sie keine rohe Anbieter-Aufgaben-ID und erfinden Sie keine Kennung.
Die Vorlage muss demselben Konto gehören, dasselbe Modell und denselben Verarbeitungskanal verwenden, abgeschlossen sein und vor weniger als 7 Tagen erstellt worden sein.
Geben Sie weder Prompt, Bild-/Video-/Audioeingaben, Dauer, Seitenverhältnis, Seed, generate_audio, Ausgabeformat noch omni_reference_task_type an. Die Einstellungen der Vorlage werden wiederverwendet.
Die Ausgabeauflösung darf angegeben werden.

Kompatibilitäts- und Eigentumsprüfungen können die Wiederverwendung auch bei erfolgreich abgeschlossener referenzierter Aufgabe ablehnen. Gehen Sie nicht davon aus, dass jede normale Generierung eine wiederverwendbare Vorlage ist.

Anfragebeispiele

Multimodale Referenz

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

Erstes und letztes Bild

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

Vorhandene Vorlage wiederverwenden

Ersetzen Sie EXISTING_SAMPLE_JOB_ID durch die tatsächlich zurückgegebene jobId einer kompatiblen abgeschlossenen Vorlage. Der folgende Platzhalter ist keine gültige Aufgabenkennung.

json

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

Übermittlung und Ergebnis

Die Antwort data enthält jobId, status, model und message. Erfolgreiche Übermittlung bedeutet Annahme, nicht Abschluss des Auftrags. Fragen Sie GET https://api.apihop.ai/v1/jobs/{jobId} mit dem API-Schlüssel desselben Kontos ab. Siehe Asynchronen Auftrag abrufen.

Lesen Sie bei Status COMPLETED den Wert data.outputResult. Akzeptieren Sie sowohl Zeichenfolgen als auch Arrays für url in jedem Ergebnisobjekt.