API de Generación de Video Seedance 2.5

Guía detallada de APIMaster para los parámetros de Seedance 2.5, medios de referencia, primeros y últimos fotogramas, edición, resultados asíncronos, facturación y solución de problemas.

Generación de Video Seedance 2.5

Crea videos a partir de texto, imágenes, video o referencias de audio utilizando el ID de modelo público seedance-2.5. La generación es asíncrona: envía una solicitud, guarda su ID de tarea pública, sondea hasta que termine y descarga el resultado. Una envío exitoso significa que la tarea fue aceptada; no significa que ya se haya generado un video.

Importante para tareas de fotograma, edición y extensión: la relación de aspecto predeterminada es adaptive. Mantén ese valor u omite la relación; no envíes explícitamente una relación fija como 16:9. Para una tarea de primer/último fotograma solo con imagen, la salida sigue las proporciones de la primera imagen. Recorta o rellena tu imagen primero si necesitas una relación específica.

Cambios predeterminados — 2026-10-01: omitir duration ahora significa 5 segundos en lugar de 4; la relación predeterminada es adaptive en lugar de 16:9; el audio generado por defecto es true. Establece estos campos explícitamente si tu integración depende de una duración, relación o salida silenciosa fija.

Límites de duración (verificados el 2026-10-06)

duration es la duración del vídeo de salida en segundos: un entero de 4 a 30. La generación normal admite duration: -1 para duración automática. La edición (omni_reference_task_type: "edit") exige -1 y un vídeo de origen de 4–30 segundos.

Hasta 10 vídeos de referencia, cada uno de 2–30 segundos y un total máximo de 30 segundos; el audio de referencia tiene los mismos límites de duración y cantidad. Entrada y salida tienen límites separados. Los segundos facturables pueden incluir ambos, sin aumentar el límite de salida.

Compruebe los parámetros antes de enviar. HTTP 200 y task_id solo confirman la aceptación; un HTTP 400 / InvalidParameter posterior puede hacer fallar la tarea. Lea el error y corrija los parámetros antes de crear otra tarea. No repita la misma solicitud sin cambios. Las tareas fallidas reembolsan la reserva de generación.

Fuente de verificación: Seedance API.

Autenticación y endpoints

La URL base de la API es https://apimaster.ai/v1. Obtén una clave de APIMaster desde Claves de API y envía Authorization: Bearer YOUR_API_KEY. Las solicitudes JSON también necesitan Content-Type: application/json. Mantén las claves en tu servidor, no en código frontend público.

Método	Endpoint	Propósito
`POST`	`https://apimaster.ai/v1/videos/generations`	Envío de tarea JSON recomendado
`GET`	`https://apimaster.ai/v1/video/generations/{task_id}`	Estado de tarea en formato de compatibilidad
`GET`	`https://apimaster.ai/v1/videos/{task_id}`	Estado de video estilo OpenAI
`GET`	`https://apimaster.ai/v1/videos/{task_id}/content`	Descarga de video autenticada
`GET`	`https://apimaster.ai/v1/videos/{task_id}/last-frame`	Descarga autenticada del último fotograma, cuando se solicita

No uses un endpoint de tarea de imagen para sondear un video. Usa una clave perteneciente a la cuenta que creó la tarea.

Inicio rápido: texto a video

Comienza con un clip corto y una especificación explícita antes de solicitar 30 segundos o una resolución más alta. Reemplaza las URLs de medios de ejemplo en ejemplos posteriores con tus propios archivos descargables directamente.

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A lighthouse above a calm sea at sunrise. Slow camera push-in, natural lighting, no text.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "generate_audio": true,
    "watermark": false,
    "output_format": "mp4"
  }'

Ejemplo de respuesta de envío:

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_example"}],
  "error": null
}

Guarda el task_id devuelto y usa el endpoint de consulta para obtener el estado de la tarea y el video final.

Parámetros de solicitud y valores predeterminados

Campo	Tipo	Predeterminado	Contrato
`model`	string	Ninguno; obligatorio	`seedance-2.5`
`prompt`	string	Ninguno; obligatorio para generación	Intención de escena, movimiento, cámara y referencia; omitir al usar `draft_task_id`
`duration`	integer	`5`; si se omite en `edit` se convierte en `-1`	`4`–`30` segundos o `-1` para duración automática; la edición solo acepta `-1`
`resolution`	string	`720p`; vista previa `480p`; mejora de vista previa `1080p`	Generación ordinaria: `480p`, `720p`, `1080p`; la vista previa y la mejora solo aceptan su resolución respectiva
`aspect_ratio`	string	`adaptive`	`adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`; las tareas de fotograma/edición/extensión requieren `adaptive`
`ratio`	string	Igual que `aspect_ratio`	Alias; ambos valores deben coincidir si se proporcionan juntos
`size`	string	`adaptive` cuando se omite	Campo de conveniencia para tamaño/proporción heredado; se acepta `adaptive`. Se prefieren `resolution` y `aspect_ratio`
`image_urls`	string[]	Sin referencias	Como máximo `30` imágenes en total, incluyendo `image_with_roles`
`image_with_roles`	object[]	Sin referencias	Objetos con `url` y `role`; `first_frame`, `last_frame`, o `reference_image`
`first_frame_image` / `last_frame_image`	string	Sin fotograma	Alias para los roles de imagen correspondientes; usar HTTP(S) o una URL `asset://` aprobada
`video_urls`	string[]	Sin referencias	Como máximo `10`; duración total como máximo `30` segundos
`audio_urls`	string[]	Sin referencias	Como máximo `10`; duración total como máximo `30` segundos; se admiten referencias solo de audio
`generate_audio`	boolean	`true`	Si se debe generar sonido
`audio`	boolean	Igual que `generate_audio`	Alias; valores de audio conflictivos devuelven 400
`watermark`	boolean	`false`	Si se solicita una marca de agua de contenido generado
`seed`	integer	Seleccionado por el modelo	Conservar `0` como una semilla explícita; una semilla no garantiza una salida idéntica
`output_format`	string	`mp4`	`mp4` o `mov`; MOV es útil para flujos de trabajo de edición/extensión. El códec y la precisión del color dependen del archivo resultante
`omni_reference_task_type`	string	`auto`	`auto`, `reference`, `edit`, o `extend`; ver validación síncrona más abajo
`nsfw_check`	boolean	`false`	Moderación opcional de texto/imagen antes del envío
`return_last_frame`	boolean	`false`	Devolver `last_frame_url` tras el éxito cuando el fotograma esté disponible
`draft`	boolean	`false`	Generar una vista previa de 480p; solo `seedance-2.5`
`draft_task_id`	string	No establecido	ID público de APIMaster de una vista previa exitosa; la mejora a una nueva tarea de 1080p

Usar booleanos JSON, no strings como "false". Alias conflictivos, resoluciones no admitidas, duración inválida y restricciones específicas de la tarea devuelven HTTP 400 antes de crear una tarea o cargar su reserva. Los arrays opcionales omitidos significan sin referencias.

Campos adicionales y formas de entrada

Campo o entrada	Soporte de interfaz
`negative_prompt`	Aceptado como texto; incluido en la moderación cuando `nsfw_check` está activado
`first_frame_image` / `last_frame_image`	Alias de string admitidos; no duplicar el mismo fotograma en `image_with_roles`
Imágenes Base64 / data-URL	No admitidas como URLs de generación. Subir el archivo mediante `/v1/uploads/images` y usar la URL devuelta
`generation_type`	Aceptado como campo opcional para generación ordinaria; usar `omni_reference_task_type` para el contrato de tipo de tarea
`camerafixed`	Aceptado como booleano para generación ordinaria; describir el movimiento de cámara requerido en el prompt
`service_tier`	Opcional para generación ordinaria; rechazado tanto para vistas previas como para mejoras de vistas previas

No depender de generation_type, camerafixed o service_tier para garantizar un resultado visual específico o prioridad de programación. No son sustitutos de los requisitos documentados de tipo de tarea y prompt.

Seleccionar el tipo de tarea

Tarea	Entrada e intención	Configuraciones requeridas
Texto a video	Prompt sin medios de referencia	Elegir una relación de aspecto, resolución y duración compatibles
Generación con referencia	Imágenes/video/audio de referencia y una descripción de una nueva escena	Se pueden usar relaciones de aspecto fijas; el prompt debe describir claramente la generación con referencia
Generación de primer fotograma	Una imagen con rol `first_frame`	`aspect_ratio: "adaptive"`
Generación de primer y último fotograma	Un `first_frame` y un `last_frame`	`aspect_ratio: "adaptive"`; un último fotograma necesita un primer fotograma
Edición de video	Video fuente más un prompt que pida editar, eliminar, reemplazar o modificar contenido	`aspect_ratio: "adaptive"`, `duration: -1`; video fuente de `4`–`30` segundos
Extensión de video	Video fuente más un prompt que pida continuarlo o extenderlo	`aspect_ratio: "adaptive"`; mantener los medios de referencia dentro de los límites siguientes

omni_reference_task_type puede seleccionar explícitamente auto, reference, edit, o extend. Usa un prompt coincidente: declarar reference mientras se pide reemplazar un objeto aún puede llevar a una discrepancia en el tipo de tarea. Para edición, la duración omitida se normaliza a -1; la relación de aspecto omitida es adaptive. Los valores explícitos deben cumplir las mismas restricciones. Para generación con referencia, evita instrucciones de edición o extensión a menos que esa sea tu operación intencionada.

Validación síncrona del tipo de tarea

Tipo declarado	Validación antes de la aceptación
`edit`	Al menos una entrada `video_urls`; relación de aspecto omitida o `adaptive`; duración omitida o `-1`; video fuente de `4`–`30` segundos
`extend`	Al menos una entrada `video_urls`; relación de aspecto omitida o `adaptive`
`reference`	Se aplican los límites ordinarios de relación de aspecto y duración compatibles; sin restricción de edición/extensión
`auto`	La intención de la tarea se infiere del prompt y las referencias

La selección explícita detecta parámetros inválidos en el envío: HTTP 400, sin tarea, sin reserva de generación. La intención de la tarea también se evalúa durante la generación; un prompt inconsistente con el tipo declarado puede fallar asincrónicamente con InvalidParameter.TaskTypeMismatch. Escribe un prompt de edición para edit, un prompt de continuación para extend y un prompt de nueva escena para reference.

Roles de imagen y primer/último fotograma

Las entradas image_with_roles usan {"url": "https://example.com/frame.png", "role": "first_frame"}. Los roles son first_frame, last_frame y reference_image. Usa como máximo un primer fotograma y un último fotograma. Las imágenes de referencia guían la apariencia o composición; no fuerzan un fotograma inicial exacto. Evita mezclar definiciones superpuestas de image_urls y image_with_roles.

Si también se incluyen referencias de video o audio, los roles de fotograma pueden tratarse como imágenes de referencia generales en lugar de una tarea estricta de primer/último fotograma. Usa entrada solo de imágenes cuando necesites un anclaje preciso de fotograma.

{
  "model": "seedance-2.5",
  "prompt": "The camera moves smoothly from the first view to the last view. Preserve the building and lighting.",
  "image_with_roles": [
    {"url": "https://example.com/first.png", "role": "first_frame"},
    {"url": "https://example.com/last.png", "role": "last_frame"}
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": false
}

Para un solo fotograma inicial, elimina la entrada last_frame. Si necesitas una relación de aspecto de salida diferente, recorta o rellena la primera imagen a esa relación antes de enviar; cambiar solo aspect_ratio no es suficiente.

Referencias de imagen, video y audio

Da a cada referencia un propósito claro en el prompt. Las referencias se indexan desde 1 en orden de array; descripciones como @图片1, @视频1 y @音频1 pueden identificar referencias de imagen, video y audio. No te refieras a un índice que esté ausente de la solicitud.

{
  "model": "seedance-2.5",
  "prompt": "Create a new coastal scene using @图片1 for the color palette, @视频1 for camera movement, and @音频1 for the rhythm. Do not edit or extend the original video.",
  "image_urls": ["https://example.com/palette.png"],
  "video_urls": ["https://example.com/camera-reference.mp4"],
  "audio_urls": ["https://example.com/rhythm.mp3"],
  "omni_reference_task_type": "reference",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}

Para generación con referencia solo de audio, mantén audio_urls y elimina los arrays de imagen/video. Todos los medios deben ser accesibles para el servicio de generación sin inicio de sesión en navegador, cookies o cabeceras de autorización adicionales.

Editar un video

{
  "model": "seedance-2.5",
  "prompt": "Edit the video: replace the red umbrella with a blue umbrella while preserving the subject and camera motion.",
  "video_urls": ["https://example.com/source.mp4"],
  "omni_reference_task_type": "edit",
  "duration": -1,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": true,
  "output_format": "mov"
}

La edición sigue la duración del clip fuente. La duración automática puede requerir una reserva de saldo inicial mayor; consulta la facturación a continuación.

Extender un video

{
  "model": "seedance-2.5",
  "prompt": "Extend the video forward: the cyclist continues along the same path, keeping the lighting and camera direction consistent.",
  "video_urls": ["https://example.com/source.mp4"],
  "omni_reference_task_type": "extend",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": true
}

Requisitos de medios de referencia

Estos son límites de medios de entrada, no dimensiones de salida. Un archivo que se descarga con éxito aún puede ser rechazado porque su formato real, dimensiones, duración o contenido no es adecuado.

Entrada	Cantidad	Dimensiones y duración	Requisitos del archivo
Imágenes	Como máximo `30` imágenes de referencia; el modo de fotograma utiliza una o dos imágenes	Cada lado entre `300` y `6000` píxeles; relación ancho/alto entre `0.4` y `2.5`	Cada archivo por debajo de `30 MB`. Se recomienda JPEG/PNG; otros formatos aceptados incluyen WebP, BMP, TIFF, GIF, HEIC, HEIF, sujetos a soporte de decodificación
Videos	Como máximo `10`; duración combinada como máximo `30` segundos	Cada clip entre `2` y `30` segundos; fuente de edición entre `4` y `30` segundos. Cada lado entre `300` y `6000` píxeles; relación entre `0.4` y `2.5`; recuento de píxeles entre `409600` y `8295044`; entre `24` y `60` FPS	Cada archivo como máximo `200 MB`; MP4/MOV con video H.264 o H.265 y audio AAC o MP3; niveles de resolución soportados `480p`, `720p`, `1080p`
Audio	Como máximo `10`; duración combinada como máximo `30` segundos	Cada clip entre `2` y `30` segundos	Cada archivo como máximo `15 MB`; WAV o MP3

Utilice URLs de archivo HTTPS directas en lugar de la URL HTML de una página para compartir. Un nombre de archivo .png no convierte una página de error HTML en una imagen válida. Asegúrese de que las URLs firmadas temporales sigan siendo válidas el tiempo suficiente para que la tarea recupere los medios. Evite redirecciones a páginas de inicio de sesión y enlaces restringidos por IP o reglas anti-hotlink. Para la máxima compatibilidad de imágenes, convierta el archivo a JPEG o PNG RGB y verifique su ancho y alto reales.

Solo cargue medios que esté autorizado a usar. Las comprobaciones de contenido pueden rechazar imágenes de personas realistas u otro material restringido; no asuma que una URL públicamente accesible garantiza la aceptación.

Subir y revisar medios antes de la generación

APIMaster admite la carga de archivos de imagen y la biblioteca de medios Seedance. Estos son pasos separados: subir un archivo te proporciona una URL descargable; enviar esa URL a la biblioteca inicia la revisión de contenido. Solo un recurso de la biblioteca aprobado puede ser referenciado con asset:// en una solicitud de generación. Los medios de referencia ordinarios que no sean de personas aún pueden usar URLs públicas directas sin un envío a la biblioteca.

La biblioteca es especialmente útil cuando reutilizarás un material o su URL original es temporal. Después de que la revisión tenga éxito, reutiliza la dirección asset:// devuelta; las referencias futuras usarán el material aprobado en lugar de requerir que vuelvas a enviar su URL original. Mantén el material en tu biblioteca durante el tiempo que necesites referenciarlo.

Los medios de personas reales primero deben enviarse a la biblioteca de medios y pasar la revisión. Una carga de archivo exitosa, una URL accesible o un envío exitoso de tarea de revisión no significa que el material esté aprobado. Usa solo medios que estés autorizado a subir y utilizar. La aprobación de la revisión no garantiza que cada solicitud de generación posterior pase sus propias comprobaciones de contenido.

La secuencia recomendada es: subir una imagen si necesitas una URL de archivo pública → enviar material para revisión → consultar (poll) la tarea de revisión → seleccionar un recurso Active → enviar la generación de video → consultar (poll) la tarea de video. Guarda los IDs devueltos en cada paso; usa los endpoints de consulta de video documentados para la generación de video.

Especificaciones y preparación del material

La tabla de medios de referencia anterior también se aplica a los envíos a la biblioteca. Verifica el archivo decodificado real, no solo su extensión. Para Seedance 2.5:

Material	Formatos aceptados	Límite de archivo	Requisitos técnicos
Imagen	JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF; se recomienda JPEG/PNG RGB	Por debajo de `30 MB` por fuente de biblioteca	Ancho y alto cada uno entre `300` y `6000` píxeles; relación ancho/alto entre `0.4` y `2.5`
Video	MP4, MOV; video H.264/H.265; audio AAC/MP3 cuando esté presente	Como máximo `200 MB` por archivo	Cada clip entre `2` y `30` segundos; fuente de edición entre `4` y `30` segundos; cada lado entre `300` y `6000` píxeles; relación entre `0.4` y `2.5`; píxeles totales entre `409600` y `8295044`; tasa de cuadros entre `24` y `60` FPS; niveles admitidos `480p`, `720p`, `1080p`
Audio	WAV, MP3	Como máximo `15 MB` por archivo	Cada clip entre `2` y `15` segundos

Un envío de revisión contiene entre 1 y 20 recursos de un tipo. Este límite por lote difiere de los límites de generación: hasta 30 imágenes, 10 videos o 10 clips de audio; los videos referenciados juntos no deben exceder 30 segundos, y el audio referenciado junto no debe exceder 30 segundos. Subir 20 materiales no permite que los 20 videos o clips de audio se usen en una sola generación.

Envía explícitamente model: "seedance-2.5" para fuentes de video de hasta 30 segundos. El valor predeterminado del envío a la biblioteca es seedance-2.0, lo que limita las fuentes de video individuales a 15 segundos. La ingesta a la biblioteca de audio actualmente tiene un límite separado de 15 segundos, como se explica a continuación. Los materiales aprobados pueden reutilizarse entre Seedance 2.0 y 2.5 cuando el modelo solicitado esté disponible para tu clave y el material cumpla con los límites de ese modelo.

Ingesta a la biblioteca de audio: envía clips de audio individuales entre 2 y 15 segundos, incluso con model: "seedance-2.5". Esto es independiente del límite de referencia de audio de 2 a 30 segundos de la generación. Recorta o divide fuentes más largas; la solicitud de generación aún permite como máximo 10 referencias de audio que sumen como máximo 30 segundos.

Errores de revisión de video: la aceptación de una solicitud de revisión no establece que un video sea utilizable. Una revisión puede fallar con FormatUnsupported o Unsupported media format. Verifica el contenedor real, códec, dimensiones, tasa de cuadros, pista de audio y accesibilidad de la URL; referencia un video de la biblioteca solo después de que se convierta en Active. Los videos de personas reales requieren aprobación de revisión antes de la generación.

Usa una URL HTTP(S) que descargue el archivo directamente sin inicio de sesión, cookies, encabezados de autorización adicionales o restricciones anti-hotlink. Mantén las URLs firmadas válidas durante toda la recuperación y revisión, y mantén su contenido sin cambios. HTML de páginas de compartir, enlaces caducados, direcciones de red privada, códecs rotos o extensiones de archivo engañosas pueden causar rechazo. Sube video y audio a tu propio almacenamiento de archivos y envía sus URLs directas; el endpoint de carga de archivos de imagen a continuación no acepta video ni audio.

Paso 1: subir un archivo de imagen local

Envía datos de formulario multipart a POST https://apimaster.ai/v1/uploads/images con un campo llamado file. No establezcas manualmente un tipo de contenido JSON: tu cliente HTTP debe proporcionar el límite multipart.

curl --fail-with-body -sS "https://apimaster.ai/v1/uploads/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./reference.png"

Respuesta de ejemplo:

{
  "url": "https://apimaster.ai/imgs/media_upload_example.png",
  "filename": "reference.png",
  "content_type": "image/png",
  "bytes": 123456,
  "created_at": 1790812800
}

Este endpoint acepta solo JPEG, PNG, GIF y WebP, con un tamaño máximo de archivo de 20 MiB (20 × 1024 × 1024 bytes). Verifica el formato de imagen detectado y las dimensiones legibles de la imagen; una carga exitosa no valida todos los requisitos de Seedance ni aprueba el contenido. Las imágenes más grandes que este límite de carga, y los formatos compatibles con la biblioteca ausentes de esta lista, necesitan tu propio almacenamiento de archivos público.

La URL devuelta usa el dominio de APIMaster y es públicamente legible por cualquiera que conozca la URL. Está destinada a la entrada de medios de la API, en lugar de a un almacenamiento archivado permanente; guarda tu archivo original y no asumas un período de retención garantizado. No subas contenido confidencial que deba requerir autenticación de descarga. Reutiliza la URL en el siguiente paso, o directamente en una solicitud de generación cuando no se requiera revisión de biblioteca.

Paso 2: enviar materiales para revisión

Envía JSON a POST https://apimaster.ai/v1/seedance2/private-avatar/assets. Establece un nuevo group o un group_id existente de APIMaster, nunca ambos. Omitir ambos crea un nuevo grupo automáticamente.

curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "group": {"name": "My reference materials", "description": "Approved generation references"},
    "project_name": "default",
    "asset_type": "Image",
    "assets": [
      {"url": "https://apimaster.ai/imgs/media_upload_example.png", "name": "reference-portrait"}
    ]
  }'

Para video o audio, usa asset_type: "Video" o asset_type: "Audio" con URLs directas en la misma estructura assets. No mezcles tipos dentro de un mismo envío.

Campo	Tipo	Requisito y comportamiento
`model`	string	Usa `seedance-2.5` para esta guía; el valor predeterminado es `seedance-2.0`
`group`	object	Grupo nuevo opcional: `name` hasta 255 caracteres, `description` hasta 4000 caracteres
`group_id`	string	ID de grupo existente opcional devuelto por APIMaster; debe pertenecer a tu cuenta
`project_name`	string	Opcional; actualmente solo se admite `default`
`asset_type`	string	`Image`, `Video` o `Audio` sensible a mayúsculas; valor predeterminado `Image`
`assets`	object[]	Array requerido que contiene entre `1` y `20` materiales del tipo seleccionado
`assets[].url`	string	URL de archivo HTTP(S) pública requerida; máximo 8192 caracteres
`assets[].name`	string	Nombre para mostrar opcional, hasta 255 caracteres; se usa un nombre automático si se omite

Respuesta aceptada de ejemplo:

{
  "code": 200,
  "data": {
    "id": "asset_task_example",
    "object": "seedance.avatar.asset.task",
    "model": "seedance-2.5",
    "status": "processing",
    "progress": 0,
    "group_id": "group_example"
  }
}

Guarda data.id como el ID de la tarea de revisión y data.group_id para envíos posteriores. Una respuesta HTTP de éxito solo confirma la aceptación. No construyas un ID de recurso a partir de un nombre de archivo o del ID de la tarea.

Paso 3: consultar (poll) la tarea de revisión y seleccionar recursos aprobados

Consulta (poll) GET https://apimaster.ai/v1/tasks/{review_task_id} cada 5–10 segundos hasta que data.status se convierta en completed o failed. Este endpoint es para la tarea de revisión de material; usa los endpoints de video documentados en otra parte de esta página para la generación de video.

curl --fail-with-body -sS "https://apimaster.ai/v1/tasks/asset_task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

Respuesta completada de ejemplo; los campos de marca de tiempo y URL de origen se omiten aquí por brevedad:

{
  "code": 200,
  "data": {
    "id": "asset_task_example",
    "object": "seedance.avatar.asset.task",
    "model": "seedance-2.5",
    "status": "completed",
    "progress": 100,
    "group_id": "group_example",
    "result": {
      "assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
      "usable_assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
      "failed_assets": []
    }
  }
}

Los estados de la tarea de revisión son processing, completed y failed. Los estados del material son Pending, Active y Failed; solo los materiales Active pueden ser referenciados. Usa el asset_url devuelto sin cambios. Identifica un material de biblioteca aprobado y no es una URL de descarga HTTP.

Un lote puede tener éxito parcialmente. Un material rechazado puede hacer que la tarea de revisión general sea failed mientras que otros materiales ya están Active. Inspecciona result.usable_assets y result.failed_assets, en lugar de descartar cada elemento cuando la tarea falla. Un fallo antes de que los resultados del material estén disponibles puede devolver un mensaje seguro error sin un resultado. Corrige y reenvía solo las entradas rechazadas; evita repetir las aceptadas.

Consulta (poll) la tarea de revisión antes de confiar en la lista de la biblioteca: las listas no consultan automáticamente las tareas de revisión pendientes. Las consultas de tareas y los detalles de los recursos devuelven los IDs públicos de material utilizados por solicitudes posteriores.

Paso 4: generar con un material aprobado

Usa un asset_url aprobado en image_urls, image_with_roles[].url, video_urls o audio_urls, coincidiendo con el tipo de material. Este ejemplo de primer fotograma usa la imagen aprobada:

{
  "model": "seedance-2.5",
  "prompt": "The person slowly turns toward the camera, natural lighting, gentle camera movement.",
  "image_with_roles": [{"url": "asset://asset_example", "role": "first_frame"}],
  "aspect_ratio": "adaptive",
  "duration": 5,
  "resolution": "720p",
  "generate_audio": false
}

Envía este JSON a POST https://apimaster.ai/v1/videos/generations, luego consulta (poll) la tarea de video devuelta como se describe a continuación. Un recurso aprobado bajo una cuenta no puede ser usado por otra cuenta. Guarda los IDs devueltos por APIMaster; los IDs copiados de otro servicio no funcionarán. Los materiales combinados en una solicitud deben provenir de un contexto de biblioteca compatible; si no están disponibles, créalos juntos en el mismo grupo de APIMaster y reintenta después de la revisión. Eliminar un material impide que las solicitudes futuras lo referencien.

Si una solicitud que usa recursos de la biblioteca no se puede enviar, verifica su estado y tu historial de tareas antes de enviarla nuevamente. Evita solicitudes de generación duplicadas inmediatas, especialmente después de un tiempo de espera de red (timeout).

Listar, inspeccionar, renombrar y eliminar materiales

Todos los endpoints requieren una clave API de APIMaster. La biblioteca está limitada a tu cuenta, por lo que las claves pertenecientes a la misma cuenta pueden acceder a sus recursos; los recursos de otra cuenta devuelven HTTP 404. Las operaciones de listado devuelven solo los materiales y grupos de tu cuenta.

Método	Endpoint	Propósito
`POST`	`https://apimaster.ai/v1/seedance2/private-avatar/groups`	Crear un grupo usando `model`, `name` y opcionalmente `description`
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/groups`	Listar tus grupos
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	Inspeccionar un grupo
`PATCH`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	Actualizar `name` y/o `description`
`DELETE`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	Eliminar un grupo vacío
`POST`	`https://apimaster.ai/v1/seedance2/private-avatar/assets`	Enviar un lote de revisión
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/assets`	Listar tus materiales
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	Inspeccionar un material y actualizar su estado de revisión
`PATCH`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	Actualizar el `name` para mostrar
`DELETE`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	Eliminar un material
`GET`	`https://apimaster.ai/v1/tasks/{review_task_id}`	Consultar una tarea de revisión

Las consultas de listado aceptan page (valor predeterminado 1) y limit (valor predeterminado 20, rango 1–100). La lista de materiales también acepta tu group_id y un filtro status sensible a mayúsculas. Su respuesta es {"code":200,"data":{"items":[],"total":0,"page":1,"limit":20}}; los elementos usan los mismos campos públicos que los detalles de material/grupo. Los resultados de la lista no incluyen recursos creados fuera de APIMaster.

Ejemplos:

# List approved materials in a group.
curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_example&status=Active&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Rename one material without changing the source file.
curl --fail-with-body -sS -X PATCH "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"approved-reference"}'

# Delete a material before deleting its group.
curl --fail-with-body -sS -X DELETE "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

La creación de grupo tiene como valor predeterminado seedance-2.5; proporciona model explícitamente para mayor claridad. Los cambios de nombre para mostrar no reemplazan el archivo del material ni repiten la revisión. Para reemplazar medios, envía una nueva revisión. Los materiales pendientes que aún no tienen una revisión completada no se pueden renombrar ni eliminar y devuelven HTTP 409. Elimina cada material en un grupo antes de eliminar el grupo; los grupos no vacíos devuelven HTTP 409. Una eliminación exitosa devuelve {"code":200,"data":{"id":"asset_example","deleted":true}} (una eliminación de grupo devuelve su ID de grupo).

Cargos, límites de tasa y errores

La carga de archivos de imagen, la revisión de materiales y las operaciones CRUD de la biblioteca no tienen cargo de generación y no crean registros de facturación de uso de video. La generación de video que utiliza materiales aprobados se factura normalmente según el modelo seleccionado y las referencias. Las operaciones gratuitas de biblioteca aún requieren una clave autorizada válida y siguen sujetas a los límites de tasa de clave API/modelo. Los endpoints de carga y creación además limitan las solicitudes por IP; espacia las solicitudes en lugar de enviar grandes ráfagas.

Estado HTTP	Significado	Acción sugerida
`400`	JSON, campos, URL, datos de imagen, tipo o tamaño de lote inválidos	Verifica el esquema y las propiedades reales del archivo
`401` / `403`	Clave faltante/inválida o permiso de modelo insuficiente	Verifica tu clave APIMaster y los modelos permitidos
`404`	Material/grupo/tarea de revisión desconocido, eliminado o inaccesible	Usa IDs devueltos a la misma cuenta
`400` / `409`	Material aún no listo, contexto de material incompatible o grupo no vacío	Termina la revisión, usa un grupo compatible o elimina los miembros del grupo
`413`	La carga de imagen excede el límite de tamaño de archivo/cuerpo	Reduce el tamaño del archivo o usa tu propio almacenamiento público
`429`	Se alcanzó el límite de tasa de solicitud	Reduce la concurrencia y reintenta consultas con retroceso (backoff)
`502` / `503`	Servicio de revisión no disponible o respuesta inválida	Reintenta consultas primero; conserva los IDs de tarea y material existentes

Una tarea de revisión puede devolver HTTP 200 con data.status: "failed"; inspecciona el estado de la tarea y su mensaje de error seguro, en lugar de confiar solo en el código HTTP. Lee la explicación devuelta y guarda el ID público de la tarea de revisión para soporte.

Preguntas frecuentes sobre la biblioteca de medios

¿Cuánto tiempo tarda la revisión? Consulta (poll) cada 5–10 segundos. La duración varía según el material y la carga de trabajo del servicio; la revisión de video y de personas reales puede tardar más que la revisión de imagen. Un envío aceptado no es una aprobación.
¿Qué pasa si la revisión falla sin una explicación? Inspecciona la tarea de revisión y failed_assets; guarda sus IDs públicos de tarea/recurso para soporte. Verifica el formato y la accesibilidad de la URL antes de enviar el material corregido. Una consulta no reinicia una revisión fallida.
¿Debo subir de nuevo para 2.0 versus 2.5? Un recurso de APIMaster aprobado puede reutilizarse cuando tu clave tenga acceso al modelo objetivo y el material cumpla con los límites de ese modelo. Los IDs entre plataformas no se pueden reutilizar.
¿Puede un lote tener éxito parcialmente? Sí. Reutiliza solo los usable_assets cuyo estado sea Active; corrige los elementos rechazados individualmente.
¿Qué significa un error de material síncrono? HTTP 400 rechaza una entrada inválida. invalid_asset_material puede identificar assets[0], assets[1], etc.; los índices comienzan en cero. Corrige el formato o duración del elemento indicado antes de enviar nuevamente.

{
  "error": {
    "message": "invalid_asset_material: assets[0] video duration must be from 2 to 30 seconds",
    "type": "media_library_error"
  }
}

Modo de vista previa: borrador de 480p a final de 1080p

Una vista previa es una generación facturable normal con draft: true. Es válida para mejoras durante 7 días a partir de la hora de creación de la tarea de vista previa. Cada mejora es una tarea y cargo independiente; la misma vista previa exitosa y no caducada se puede mejorar varias veces.

Paso 1: generar y sondear una vista previa

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","prompt":"A colorful abstract pattern gently moves.","draft":true,"duration":5,"return_last_frame":true}'

La resolución omitida se convierte en 480p. Enviar 720p o 1080p con draft: true devuelve 400. Sondea el ID público devuelto a través de /v1/videos/{task_id} o /v1/video/generations/{task_id} y espera a que tenga éxito antes de mejorar. Los demás parámetros de generación y los límites de medios se aplican normalmente.

Paso 2: crear un video final a partir de la vista previa

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","draft_task_id":"task_preview_example","output_format":"mp4","return_last_frame":true,"watermark":false}'

La respuesta contiene un ID de tarea pública nuevo. La resolución omitida se convierte en 1080p; todos los demás valores de resolución devuelven 400. Usa una clave API perteneciente a la cuenta de la vista previa. Una tarea faltante, ajena, que no sea vista previa, incompleta, caducada o de un modelo diferente se rechaza sincrónicamente con 400, sin crear una tarea ni cargar una reserva.

Si la vista previa no está disponible temporalmente, reintenta más tarde con el mismo draft_task_id. No lo reemplaces con el ID de otra plataforma. Una mejora de vista previa no se puede redirigir a un contexto de generación diferente.

Campos heredados y cambios permitidos

No reenvíes los campos heredados, incluso cuando su valor sea idéntico, false, 0 o null:

prompt, image_urls, image_with_roles, video_urls, audio_urls, duration, size, aspect_ratio, ratio, seed, generate_audio, audio, omni_reference_task_type, generation_type, camerafixed, web_search, tools.

La misma restricción se aplica a los alias de entrada de APIMaster y al envoltorio heredado: seconds, images, image, input_reference, first_frame_image, last_frame_image, video_list, negative_prompt, metadata.

Además de model, draft_task_id y la resolución fija 1080p, los campos ajustables son solo output_format, return_last_frame y watermark. Los valores omitidos usan mp4, false y false, respectivamente. Las banderas de último fotograma y marca de agua no se heredan de la vista previa. No combines draft_task_id con draft: true. Tanto la creación de la vista previa como la mejora rechazan service_tier.

Reservas de vista previa y video final

Duración de la vista previa	Reserva de vista previa	Reserva de video final
Explícita `4`–`30` segundos	Duración especificada a 480p; el trabajo de video de referencia incluido normalmente	Misma duración en el nivel de 1080p sin entrada de video
`-1`, incluyendo duración omitida en `edit`	Hasta el máximo de 30 segundos	Hasta 30 segundos a 1080p sin entrada de video
Otra duración omitida	5 segundos a 480p	5 segundos a 1080p sin entrada de video

El trabajo de vista previa sigue el precio ordinario de 480p; la duración del video de referencia cuenta normalmente, con la duración facturable combinada limitada a 30 segundos. El trabajo de video final utiliza el nivel de 1080p sin entrada de video, excluyendo la duración del video de referencia de la vista previa. El éxito liquida el uso real y reembolsa o carga la diferencia; el fallo reembolsa la reserva completa. Los precios provienen de tu tarjeta de modelo y registros de cartera.

Moderación opcional de texto e imágenes

nsfw_check tiene como valor predeterminado false. En Seedance 2.0 y 2.5, establecerlo en true habilita comprobaciones previas al envío de prompt, negative_prompt y entradas de imagen: image_urls, image_with_roles[].url, alias de primer/último fotograma y activos de biblioteca de tipo imagen. Las URL de generación no aceptan imágenes en base64; sube primero un archivo de imagen. Los videos, audios y activos de tipo video/audio están fuera de esta comprobación de texto/imagen.

Una violación detectada devuelve HTTP 400 con la siguiente estructura de respuesta; no se crea ninguna tarea de video ni reserva de generación:

{
  "code": "nsfw_content_detected",
  "message": "Your request was rejected by content moderation (`nsfw_check` is enabled). Flagged categories: sexual.",
  "data": null
}

Esta comprobación opcional no tiene cargo de generación y no es una garantía absoluta de seguridad de contenido. Un fallo en la comprobación o la ausencia de detección no establece que una generación posterior sea aprobada. Usa solo contenido autorizado y conforme, independientemente de la bandera.

Consultar estado y descargar

La misma tarea se puede leer a través de cualquiera de los formatos de consulta. Sondea a un intervalo moderado, como cada 5–10 segundos, y detente en un estado terminal. El tiempo de generación depende de la carga de trabajo, la duración del clip, la resolución y las referencias; no trates una tarea lenta como motivo para crear tareas duplicadas.

curl --fail-with-body -sS "https://apimaster.ai/v1/video/generations/task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

Respuestas completadas

Formato de compatibilidad, GET /v1/video/generations/{task_id}:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_example",
    "status": "succeeded",
    "url": "https://apimaster.ai/v1/videos/task_example/content",
    "format": "mp4",
    "error": null,
    "metadata": null,
    "usage": {"completion_tokens": 108900},
    "actual_time": 160,
    "last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
  }
}

Formato estilo OpenAI, GET /v1/videos/{task_id}:

{
  "id": "task_example",
  "object": "video",
  "model": "seedance-2.5",
  "status": "completed",
  "progress": "100%",
  "url": "https://apimaster.ai/v1/videos/task_example/content",
  "usage": {"completion_tokens": 108900},
  "actual_time": 160,
  "last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
}

Significado	Ubicación en compatibilidad	Ubicación en estilo OpenAI
ID público de la tarea	`data.task_id`	`id`
En espera	`data.status: queued`	`status: queued`
Generando	`data.status: processing`	`status: in_progress`
Éxito	`data.status: succeeded`	`status: completed`
Fallo	`data.status: failed`	`status: failed`
URL de descarga del video	`data.url`	`url`
Tokens de finalización	`data.usage.completion_tokens`	`usage.completion_tokens`
Segundos transcurridos	`data.actual_time`	`actual_time`
URL de la imagen del último fotograma	`data.last_frame_url`	`last_frame_url`
Explicación del fallo	`data.error.message`	`error.message`
Contenedor de salida	`data.format`	Usa el `output_format` solicitado al guardar
Metadatos heredados	`data.metadata`, actualmente `null`	No se usa

actual_time es el tiempo de finalización menos el tiempo de envío, en segundos, incluyendo el tiempo de espera; no es la duración del video. usage.completion_tokens es la estadística de generación registrada y coincide con el recuento de tokens del registro de consumo. La liquidación monetaria de APIMaster utiliza la duración del video y su nivel aplicable; la estadística de tokens no es una fórmula de precio monetario. Las respuestas no contienen campos de cantidad; usa los registros de consumo de tu billetera para la liquidación.

El uso puede estar ausente justo después de la finalización; consulta de nuevo más tarde. last_frame_url se devuelve solo después del éxito cuando solicitaste return_last_frame: true y hay un último fotograma disponible. El campo se omite, en lugar de establecerse en null, cuando no se solicitó, aún está pendiente o falló. Las actualizaciones de vista previa usan su propio indicador.

Respuesta fallida

Una tarea fallida aún se consulta con HTTP 200. La respuesta estilo OpenAI puede contener:

{
  "id": "task_example",
  "object": "video",
  "model": "seedance-2.5",
  "status": "failed",
  "progress": "100%",
  "error": {"code": "task_failed", "message": "[upstream_error] Unsupported media format."}
}

El formato de compatibilidad coloca la explicación en data.error.message. Las tareas fallidas no tienen descarga de video ni de último fotograma. Conserva el ID público de la tarea y la explicación para soporte.

Descargar video y último fotograma

Envía Authorization: Bearer YOUR_API_KEY al descargar cualquiera de las URL. Usa una clave perteneciente a la cuenta de la tarea. El contenido del video es MP4 o MOV según la solicitud; guarda MOV con una extensión .mov. Un último fotograma es una imagen, así que usa el tipo de contenido devuelto al seleccionar su extensión.

curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/last-frame" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o last-frame.jpg

Descarga y guarda los archivos exitosos rápidamente. La disponibilidad no es indefinida; conservar un ID de tarea no garantiza que su archivo de salida siga siendo descargable. Si el archivo ya no está disponible, la descarga devuelve HTTP 410 con error.message: "Media has expired or is no longer available". Un último fotograma no disponible o no solicitado devuelve HTTP 404. La falta de autenticación para la descarga devuelve HTTP 401.

Python: enviar, sondear y guardar

import os
import time
import requests

base = "https://apimaster.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['APIMASTER_API_KEY']}"}
payload = {
    "model": "seedance-2.5",
    "prompt": "A lighthouse above a calm sea, slow camera push-in, no text.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "generate_audio": True,
    "watermark": False,
    "return_last_frame": True,
}
response = requests.post(f"{base}/videos/generations", headers=headers,
                         json=payload, timeout=60)
response.raise_for_status()
created = response.json()
data = created.get("data")
if isinstance(data, list) and data:
    task_id = data[0].get("task_id")
else:
    item = data if isinstance(data, dict) else created
    task_id = item.get("task_id") or item.get("id")
if not task_id:
    raise RuntimeError("No task ID returned; inspect the submission response.")
print("task_id:", task_id)

# Example client timeout, not a promised generation deadline.
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    response = requests.get(f"{base}/videos/{task_id}", headers=headers, timeout=60)
    response.raise_for_status()
    task = response.json()
    state = task.get("status")
    if state == "failed":
        error = task.get("error") or {}
        raise RuntimeError(error.get("message", "Video generation failed."))
    if state == "completed":
        result = requests.get(f"{base}/videos/{task_id}/content", headers=headers,
                              timeout=120, stream=True)
        result.raise_for_status()
        with open("output.mp4", "wb") as output:
            for chunk in result.iter_content(1024 * 1024):
                if chunk:
                    output.write(chunk)
        print("Saved output.mp4")
        print("usage:", task.get("usage"), "actual_time:", task.get("actual_time"))
        if task.get("last_frame_url"):
            frame = requests.get(task["last_frame_url"], headers=headers, timeout=60)
            frame.raise_for_status()
            with open("last-frame.jpg", "wb") as image:
                image.write(frame.content)
            print("Saved last-frame.jpg")
        break
    time.sleep(5)
else:
    raise TimeoutError(f"Task {task_id} is still pending; keep this ID and query it later.")

Un tiempo de espera de conexión durante el envío deja el resultado incierto: conserva cualquier ID de tarea devuelto y revisa tu historial de tareas antes de enviar de nuevo. Un tiempo de espera en el sondeo no cancela una tarea. Evita los reintentos automáticos de un envío facturable cuando no sepas si fue aceptado.

Facturación, reservas y reembolsos

La facturación utiliza la duración en segundos y depende de la resolución, el tipo de medio de entrada y el precio de cuenta aplicable. El audio generado versus el silencioso no selecciona un nivel de precios separado en la configuración actual de Seedance 2.5. Consulta la ficha del modelo y los precios de video/medios de la billetera antes del envío; esta página no codifica un precio cambiante.

El envío reserva un monto estimado. Si se omite la duración ordinaria, se reservan 5 segundos. Para duration: -1, la estimación usa el máximo de 30 segundos, por lo que se necesita saldo suficiente incluso si el resultado es más corto.
Con video de referencia, el trabajo facturable puede incluir la duración del video de referencia más la duración del video generado. Una salida de 5 segundos no necesariamente se factura como solo 5 segundos de trabajo.
Después de una generación exitosa, el uso final medido puede producir un cargo adicional o un reembolso de la diferencia. Usa los registros finales de la billetera para confirmar la liquidación.
Las tareas fallidas reembolsan la reserva de generación. Una tarea fallida aún puede mostrar su registro de consumo original junto con un reembolso correspondiente; cuenta ambos al verificar el cargo neto.
Corregir una solicitud inválida requiere un nuevo envío. Un ID de tarea fallida existente no se puede reiniciar continuando con su sondeo.

Ejemplos en JavaScript, Go, Java y PHP

Estos ejemplos envían una tarea de texto a video e imprimen su respuesta. Guarda data[0].task_id, luego usa el flujo de consulta/descarga anterior. Lee tu clave desde el entorno del servidor.

JavaScript (Node.js)

const response = await fetch("https://apimaster.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIMASTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.5", prompt: "A lighthouse at sunrise, slow camera push-in.",
    duration: 5, resolution: "720p", aspect_ratio: "adaptive",
    generate_audio: true, watermark: false, output_format: "mp4",
  }),
});
const body = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`);
console.log(JSON.parse(body));

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func main() {
    payload, err := json.Marshal(map[string]any{
        "model": "seedance-2.5", "prompt": "A lighthouse at sunrise, slow camera push-in.",
        "duration": 5, "resolution": "720p", "aspect_ratio": "adaptive",
        "generate_audio": true, "watermark": false, "output_format": "mp4",
    })
    if err != nil { panic(err) }
    req, err := http.NewRequest("POST", "https://apimaster.ai/v1/videos/generations", bytes.NewReader(payload))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + os.Getenv("APIMASTER_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    response, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
    if err != nil { panic(err) }
    defer response.Body.Close()
    body, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    if response.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, body)) }
    fmt.Println(string(body))
}

Java (JDK 11+)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class SeedanceExample {
    public static void main(String[] args) throws Exception {
        String json = "{\"model\":\"seedance-2.5\",\"prompt\":\"A lighthouse at sunrise.\","
            + "\"duration\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"adaptive\","
            + "\"generate_audio\":true,\"watermark\":false,\"output_format\":\"mp4\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://apimaster.ai/v1/videos/generations"))
            .timeout(Duration.ofSeconds(60))
            .header("Authorization", "Bearer " + System.getenv("APIMASTER_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json)).build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException("HTTP " + response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

PHP

<?php
$payload = [
    'model' => 'seedance-2.5', 'prompt' => 'A lighthouse at sunrise, slow camera push-in.',
    'duration' => 5, 'resolution' => '720p', 'aspect_ratio' => 'adaptive',
    'generate_audio' => true, 'watermark' => false, 'output_format' => 'mp4',
];
$handle = curl_init('https://apimaster.ai/v1/videos/generations');
curl_setopt_array($handle, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('APIMASTER_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);
$body = curl_exec($handle);
if ($body === false) { throw new RuntimeException(curl_error($handle)); }
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);
if ($status >= 400) { throw new RuntimeException("HTTP $status: $body"); }
print_r(json_decode($body, true, 512, JSON_THROW_ON_ERROR));

Migración desde otra integración de Seedance 2.5

Establece tu URL base a https://apimaster.ai/v1 y envía a POST /v1/videos/generations. Utiliza las definiciones de campos y valores predeterminados de APIMaster de esta página; mantén la duración, la relación de aspecto y el audio explícitos al migrar una integración existente.

Usa GET /v1/video/generations/{task_id} o GET /v1/videos/{task_id} para videos. /v1/tasks/{id} también sirve tareas de revisión de medios; para un ID de video de APIMaster devuelve la respuesta de video de compatibilidad. Prefiere los dos endpoints de video dedicados para mantener claro el manejo de video y revisión.

Otra integración	Compatibilidad APIMaster	Estilo OpenAI de APIMaster
`pending`	`data.status: queued`	`status: queued`
`processing`	`data.status: processing`	`status: in_progress`
`completed`	`data.status: succeeded`	`status: completed`
`failed`	`data.status: failed`	`status: failed`
`data.result.videos[].url[0]`	`data.url`	`url`
Resultado del último fotograma	`data.last_frame_url`	`last_frame_url`
Uso de generación	`data.usage.completion_tokens`	`usage.completion_tokens`
Tiempo transcurrido	`data.actual_time`	`actual_time`

Descarga las URLs de video y del último fotograma con la clave Bearer de tu cuenta. APIMaster no devuelve campos de cantidad; usa los registros de consumo de la cartera. Los IDs de tarea, los IDs de asset:// y draft_task_id son específicos de APIMaster y no se pueden copiar entre plataformas. Envía y revisa tus materiales nuevamente en APIMaster. Guarda las salidas de inmediato en lugar de asumir que se aplica el período de retención de otro servicio.

Diferencias entre Seedance 2.0 y 2.5

Usa la documentación específica del modelo al cambiar de modelos. Los límites no se infieren del número de versión de un modelo.

Capacidad	Seedance 2.0	Seedance 2.5
Modelo público	`seedance-2.0`	`seedance-2.5`
Duración predeterminada	`4` segundos	`5` segundos; la edición por defecto es `-1`
Duración de generación	`4`–`15` s	`4`–`30` segundos, o `-1`
Resolución	`480p`, `720p`, `1080p`, `4K`	`480p`, `720p`, `1080p`
Cantidad de imágenes/videos/audio y duración total	Sigue los límites de medios del modelo 2.0	`30` imágenes, `10` videos sumando como máximo `30` segundos, `10` clips de audio sumando como máximo `30` segundos
Referencia de audio puro	Sigue el modo documentado del modelo 2.0	Compatible
Formato de salida	`mp4`, `mov`	`mp4`, `mov`
Marca de agua	Sigue las opciones documentadas del modelo 2.0	`false` por defecto
Vista previa y actualización	No compatible con este flujo de trabajo	Vista previa 480p → final 1080p; válido por 7 días
Ingesta de video por defecto en biblioteca de medios	Límite de video individual `15` segundos	Límite de video individual `30` segundos cuando se selecciona explícitamente
Ingesta de audio en biblioteca de medios	`2`–`15` segundos	`2`–`15` segundos
Referencias `asset://` aprobadas	Activos aprobados de la misma cuenta, sujetos a permisos y límites del modelo	Misma regla; no se aceptan IDs entre plataformas

Estructuras de respuesta de error

La validación del envío devuelve HTTP 400 con un objeto error:

{
  "error": {
    "message": "draft resolution must be 480p",
    "type": "invalid_request_error"
  }
}

Algunas rutas de rechazo de solicitud usan un sobre code / message / data, incluyendo moderación y entradas de medios inválidas:

{
  "code": "invalid_request",
  "message": "Invalid format for image_with_roles[0].url. Only http/https URLs or asset:// private asset URLs are supported.",
  "data": null
}

La falta de autenticación para descarga devuelve HTTP 401:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: request_example)",
    "type": "new_api_error"
  }
}

Maneja ambos sobres de error: lee error.message cuando esté presente, de lo contrario message. No requieras un solo campo de código de error para detectar fallos. Una consulta de video HTTP 200 aún puede contener una tarea fallida.

Mensaje de envío	Significado
`unsupported seedance-2.5 resolution "4k"`	Usa una resolución compatible
`seedance-2.5 duration must be -1 or an integer from 4 to 30`	Duración fuera del rango permitido
`first/last frame aspect_ratio must be adaptive`	La tarea de fotograma solo de imagen usa una relación de aspecto fija
`edit requires at least one video_urls entry`	Falta la fuente de edición
`extend requires at least one video_urls entry`	Falta la fuente de extensión
`edit duration must be -1`	La duración de edición explícita no es automática
`draft resolution must be 480p`	La resolución de vista previa no es válida
`draft_task_id resolution must be 1080p`	La resolución de actualización no es válida
`draft and draft_task_id cannot be used together`	Campos de vista previa mutuamente excluyentes
`service_tier is not supported for draft tasks`	Campo de programación suministrado para vista previa o actualización
`draft_task_id was not found in your account`	Falta el ID de vista previa o es inaccesible
`draft_task_id is not a draft task`	Tarea ordinaria suministrada como vista previa
`draft_task_id has not completed successfully`	Vista previa pendiente o fallida
`draft_task_id has expired; drafts are valid for 7 days`	Vista previa anterior a 7 días
`draft_task_id model does not match`	El modelo fuente difiere
`Draft is temporarily unavailable; retry with the same draft_task_id later`	Reintenta más tarde sin cambiar el ID de vista previa
`prompt must not be supplied with draft_task_id`	Campo heredado reenviado; errores equivalentes nombran otros campos prohibidos

Solución de problemas

Distinguir un error de envío síncrono de un fallo asíncrono: un HTTP 200 con un ID de tarea solo confirma la aceptación. La tarea puede volverse más tarde failed.

Error o síntoma	Causa probable	Qué hacer
`ratio` no válido / la relación de aspecto del primer fotograma debe seguir la imagen	Se usó una relación fija en una tarea de fotograma	Establecer `aspect_ratio: "adaptive"`; recortar o rellenar la primera imagen si se necesita una relación específica
`content[1]` no válido / formato de imagen no válido	Una URL devuelve HTML, un enlace caducado o una imagen no compatible/indecodificable	Abrir la URL directa del archivo sin inicio de sesión; convertir a JPEG/PNG; verificar dimensiones y reintentar con una nueva tarea
Lado de la imagen o relación de aspecto fuera de rango	Una imagen es demasiado pequeña/grande o demasiado ancha/alta	Cada lado entre `300` y `6000` píxeles; ancho/altura entre `0.4` y `2.5`
`InvalidParameter.TaskTypeConstraint`	La configuración de edición/extensión/fotograma viola su contrato específico de tarea	Usar `adaptive`; la edición también necesita `duration: -1`
`InvalidParameter.TaskTypeMismatch`	El tipo de tarea declarado y la intención del prompt no coinciden	Reescribir el prompt y seleccionar un `omni_reference_task_type` que coincida
Contenido rechazado / bloqueado por moderación	La entrada o el prompt viola las reglas de contenido aplicables	Usar medios conformes y revisar el prompt; no reintentar el mismo contenido rechazado sin cambios
HTTP `400`	Falta el prompt, resolución/duración no soportada, medios no válidos o alias en conflicto	Verificar la solicitud contra esta página antes de reenviarla
HTTP `401` / `403`	Clave no válida o autorización insuficiente	Usar una clave APIMaster activa de la cuenta que posee la tarea
Saldo insuficiente, incluyendo HTTP `402` o un error de saldo/cuota	El saldo disponible o la asignación de la clave no pueden cubrir la reserva	Verificar el saldo de la billetera, la asignación de la clave y la reserva de duración automática
HTTP `429`	Límite de tasa o concurrencia	Retroceder; reutilizar el ID de tarea existente al consultar
HTTP `500` / `502` / tiempo de espera de red	Fallo temporal del servicio o de la conexión	Reintentar lecturas con retroceso; verificar el historial de tareas antes de reintentar un envío
Tarea completada pero la descarga falla	Descargar demasiado pronto, falta de autenticación o salida no disponible	Consultar el estado nuevamente, enviar la clave de la misma cuenta y conservar el ID de tarea para soporte

El registro de tareas del usuario y los detalles del registro de uso muestran explicaciones seguras de los fallos. Al contactar a soporte, incluir el ID de tarea público, la hora aproximada de envío, el modelo, la resolución, la duración y el mensaje de error relevante. Nunca envíes tu clave de API o el encabezado de autorización.

Relacionado: Descripción general de la API de video · Seedance 2.0