Génération de vidéo Seedance 2.5 | Documentation des 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`.

Créez une tâche asynchrone Seedance 2.5. Pour Seedance 2.0, utilisez sa référence de paramètres distincte.

Authentification

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Corps

modelstringobligatoire

seedance-2.5.

promptstring

Consigne vidéo. Obligatoire pour une génération à partir de texte seul ; peut être omise ou vide avec des références d’images/vidéos. Omettez-la pour la réutilisation de draft_task. Les éléments textuels de metadata.content sont ignorés ; le champ prompt de premier niveau fait autorité.

durationnumberPar défaut: 5

Entier de 4 à 30, ou -1 pour une durée automatique. Le champ natif seconds accepte la chaîne entière équivalente. metadata.duration est aussi accepté. Les alias de durée fournis doivent correspondre. Omettez tous les contrôles de durée pour la réutilisation de draft_task.

resolutionstringPar défaut: 720p

480p, 720p ou 1080p. Le champ natif size peut indiquer la résolution ; metadata.resolution est prioritaire. 4k n’est pas pris en charge.

aspectRatiostringPar défaut: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 ou adaptive. aspect_ratio, ratio et metadata.ratio sont acceptés. Les anciennes valeurs de rapport dans size restent acceptées pour compatibilité, mais une valeur de résolution dans size désigne une résolution. Les images initiale/finale nécessitent adaptive, sélectionné automatiquement si des rôles d’images sont présents sans rapport explicite.

metadataobject

Accepte resolution, ratio, duration, content, generate_audio et output_format. Définissez generate_audio sur un booléen pour l’audio généré. generateAudio / generate_audio de premier niveau sont des alias ; utilisez un seul contrôle audio.

imageUrlsstring[]

Images de référence. images, imageUrl, image_urls et image_url sont des alias. La forme native abrégée images utilise ses deux premières images comme images initiale/finale ; imageUrls conserve la sémantique d’images de référence.

imageWithRolesobject[]

Images par rôle avec url et role : first_frame, last_frame ou reference_image. image_with_roles est un alias. metadata.content typé est également accepté.

videoUrlsstring[]

Vidéos de référence. videoUrl, video_urls et video_url sont des alias.

audioUrlsstring[]

Audio de référence. audioUrl, audio_urls et audio_url sont des alias. Nécessite une image ou une vidéo dans la même requête.

outputFormatstringPar défaut: mp4

mp4 uniquement. output_format et metadata.output_format sont acceptés. mov et watermark ne sont pas pris en charge.

callback_urlstring

URL facultative de rappel natif. La disponibilité dépend du canal choisi ; utilisez GET https://api.apihop.ai/v1/jobs/{jobId} comme référence pour le résultat.

Contenu multimodal

Les URL multimédias peuvent être des adresses HTTP(S) publiques ou des identifiants asset:// existants.

Type de média	Champ imbriqué	Rôles
`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`	Aucun rôle ; réutilisation d’échantillon uniquement

Jusqu’à 30 images, 10 vidéos et 10 fichiers audio sont acceptés, dans une limite totale de 50 éléments multimédias, formes abrégées et contenu typé compris. L’audio nécessite une image ou une vidéo. Utilisez prompt de premier niveau au lieu du contenu type: "text". Fournissez un seul alias par réglage. Les contrôles non pris en charge sont rejetés. Les champs de premier niveau first_frame_url, last_frame_url, reference_image_urls, reference_video_urls et reference_audio_urls sont des formes abrégées propres aux rôles. Les champs non listés des éléments de contenu ne sont pas transmis.

Réutilisation de tâches d’échantillon

draft_task est propre à Seedance 2.5. Il réutilise un échantillon compatible existant et terminé ; cette page ne définit pas de contrôles de création d’échantillon.

metadata.content doit contenir exactement un élément draft_task.
Privilégiez le jobId Synapse de l’échantillon existant, sous forme de chaîne décimale, pour draft_task.id. Un identifiant de plateforme task_... existant et enregistré est aussi accepté ; n’utilisez pas d’ID brut du fournisseur et n’inventez pas d’identifiant.
L’échantillon doit appartenir au même compte, utiliser le même modèle et canal de traitement, être terminé et avoir été créé depuis moins de 7 jours.
Ne fournissez pas de consigne, d’entrées image/vidéo/audio, de durée, de rapport, de graine, de generate_audio, de format de sortie ni de omni_reference_task_type. Les réglages de l’échantillon sont réutilisés.
La résolution de sortie peut être fournie.

Les contrôles de compatibilité et de propriété peuvent rejeter la réutilisation même si la tâche référencée s’est terminée avec succès. Ne supposez pas que toute génération normale constitue un échantillon réutilisable.

Exemples de requêtes

Référence multimodale

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

Images initiale et finale

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

Réutiliser un échantillon existant

Remplacez EXISTING_SAMPLE_JOB_ID par le jobId renvoyé d’un échantillon réel compatible et terminé. L’espace réservé ci-dessous n’est pas un identifiant de tâche fonctionnel.

json

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

Soumission et résultat

Le champ data de la réponse contient jobId, status, model et message. Une soumission réussie signifie que la tâche est acceptée, pas terminée. Interrogez GET https://api.apihop.ai/v1/jobs/{jobId} avec une clé API du même compte. Consultez Consulter une tâche asynchrone.

Lorsque l’état est COMPLETED, lisez data.outputResult. Acceptez les chaînes et les tableaux dans le champ url de chaque objet de résultat.