Generación de vídeo Seedance 2.5 | Documentación de 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`.

Crea una tarea asíncrona de Seedance 2.5. Para Seedance 2.0, usa su referencia de parámetros independiente.

Autenticación

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Cuerpo

modelstringobligatorio

seedance-2.5.

promptstring

Instrucción de vídeo. Obligatoria para generar solo con texto; puede omitirse o estar vacía si hay referencias de imagen/vídeo. Omítela al reutilizar draft_task. Los elementos de texto de metadata.content se descartan; prevalece prompt de nivel superior.

durationnumberPredeterminado: 5

Entero de 4 a 30, o -1 para duración automática. El campo nativo seconds acepta la cadena entera equivalente. También se admite metadata.duration. Los alias de duración proporcionados deben coincidir. Omite todos los controles de duración al reutilizar draft_task.

resolutionstringPredeterminado: 720p

480p, 720p o 1080p. El campo nativo size puede indicar la resolución; metadata.resolution tiene prioridad. 4k no se admite.

aspectRatiostringPredeterminado: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 o adaptive. Se aceptan aspect_ratio, ratio y metadata.ratio. Los valores de relación de aspecto en size siguen aceptándose por compatibilidad, pero un valor de resolución en size significa resolución. La entrada de fotogramas inicial/final requiere adaptive; se elige automáticamente si hay roles de fotogramas sin relación explícita.

metadataobject

Acepta resolution, ratio, duration, content, generate_audio y output_format. Establece generate_audio en un booleano para el audio generado. generateAudio / generate_audio de nivel superior son alias; usa un único control de audio.

imageUrlsstring[]

Imágenes de referencia. images, imageUrl, image_urls e image_url son alias. La forma nativa abreviada images usa las dos primeras imágenes como fotogramas inicial/final; imageUrls conserva la semántica de imágenes de referencia.

imageWithRolesobject[]

Imágenes por roles con url y role: first_frame, last_frame o reference_image. image_with_roles es un alias. También se acepta metadata.content tipado.

videoUrlsstring[]

Vídeos de referencia. videoUrl, video_urls y video_url son alias.

audioUrlsstring[]

Audio de referencia. audioUrl, audio_urls y audio_url son alias. Requiere una imagen o vídeo en la misma solicitud.

outputFormatstringPredeterminado: mp4

Solo mp4. Se aceptan output_format y metadata.output_format. mov y watermark no se admiten.

callback_urlstring

URL opcional de callback nativo. La disponibilidad depende del canal elegido; usa GET https://api.apihop.ai/v1/jobs/{jobId} como resultado de referencia.

Contenido multimodal

Las URL multimedia pueden ser direcciones HTTP(S) públicas o identificadores asset:// existentes.

Tipo	Campo anidado	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`	Sin rol; solo reutilización de muestras

Se aceptan hasta 30 imágenes, 10 vídeos y 10 archivos de audio, con un máximo de 50 elementos multimedia en total, sumando formas abreviadas y contenido tipado. El audio requiere una imagen o vídeo. Usa prompt de nivel superior en lugar de contenido type: "text". Proporciona un único alias por ajuste. Los controles no compatibles se rechazan. Los campos de nivel superior first_frame_url, last_frame_url, reference_image_urls, reference_video_urls y reference_audio_urls son formas abreviadas por rol. Los campos no listados dentro del contenido no se reenvían.

Reutilización de tareas de muestra

draft_task es exclusivo de Seedance 2.5. Reutiliza una muestra compatible existente y completada; esta página no define controles de creación de muestras.

metadata.content debe contener exactamente un elemento draft_task.
Prefiere el jobId de Synapse de la muestra existente, como cadena decimal, para draft_task.id. También se acepta un identificador de plataforma task_... existente y registrado; no uses el ID bruto del proveedor ni inventes identificadores.
La muestra debe pertenecer a la misma cuenta, usar el mismo modelo y canal de procesamiento, estar completada y haberse creado hace menos de 7 días.
No proporciones instrucciones, entradas de imagen/vídeo/audio, duración, relación de aspecto, semilla, generate_audio, formato de salida ni omni_reference_task_type. Se reutilizan los ajustes de la muestra.
Se puede proporcionar la resolución de salida.

Las comprobaciones de compatibilidad y propiedad pueden rechazar la reutilización aunque la tarea referenciada se completara correctamente. No supongas que toda generación normal es una muestra reutilizable.

Ejemplos de solicitudes

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

Fotogramas inicial y final

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

Reutilizar una muestra existente

Sustituye EXISTING_SAMPLE_JOB_ID por el jobId devuelto de una muestra real compatible y completada. El marcador siguiente no es un identificador de tarea funcional.

json

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

Envío y resultado

El campo data de la respuesta contiene jobId, status, model y message. Un envío correcto significa que la tarea se ha aceptado, no que haya terminado. Consulta periódicamente GET https://api.apihop.ai/v1/jobs/{jobId} con una clave de la misma cuenta. Consulta Consultar tarea asíncrona.

Cuando el estado sea COMPLETED, lee data.outputResult. Acepta cadenas y matrices en el campo url de cada objeto de resultado.