/ai/v1/videos para generar vídeos. Los clientes que ya usan /v1/videos pueden consultar el ejemplo del protocolo compatible.
Requisitos previos
- Prepara una API Key válida de AIHubMix y léela desde la variable de entorno
AIHUBMIX_API_KEY. - Antes de usar la nueva API de vídeo, activa las tareas asíncronas en la consola y confirma que la cuenta dispone de saldo suficiente y de permiso para usar el modelo de destino.
- La persona que aparece en los recursos debe consentir los usos correspondientes y completar personalmente el proceso de confirmación en la web. Añade a cada grupo únicamente recursos de una misma persona.
- Prepara un enlace directo a la imagen que el proveedor de modelos pueda leer y asegúrate de que siga siendo válido durante el procesamiento del recurso.
- Los ejemplos de línea de comandos requieren Bash, curl y jq. Ejecuta los pasos en la misma terminal y conserva los ID devueltos del grupo de recursos, la sesión de confirmación, el recurso y la tarea de vídeo.
La guía oficial de recursos de personas reales de BytePlus cubre Seedance 2.0 y Seedance 2.5. El ejemplo principal de la nueva API de vídeo de esta página utiliza el ID de modelo de AIHubMix
doubao-seedance-2-5-260628, que se ha verificado en producción; las versiones concretas, los tipos de medios de referencia y los parámetros dependen del Schema actual del modelo y de las capacidades disponibles para la cuenta. Consulta el alcance en Verificación de este flujo; no deduzcas de estos resultados que todas las versiones de Seedance admiten recursos de personas reales.
- Crear un grupo de recursos
name. El nombre no puede estar vacío y admite un máximo de 100 caracteres. Una creación correcta devuelve HTTP 201, con el estado inicial pending_auth.
Los campos públicos del grupo de recursos son id, object, name, status, created_at y updated_at. El valor de object es siempre asset_group y los campos de tiempo se expresan en segundos Unix. Posteriormente, comprueba que status=active para determinar si ya se pueden añadir recursos al grupo.
Si se pierde la respuesta de creación, consulta primero la lista para evitar una creación duplicada inmediata:
data, has_more y next_after. Para obtener la página siguiente, envía after con el valor de next_after de la página anterior; limit tiene un valor predeterminado de 20 y un máximo de 100. El nombre no es un identificador de idempotencia; identifica el grupo mediante su ID y su fecha de creación.
- Obtener el enlace de confirmación de la propia persona
Crea una sesión de confirmación sin cuerpo de solicitud:
201. Los campos públicos son id, object, group_id, status, created_at, expires_at y completed_at; object es siempre verification_session, los campos de tiempo se expresan en segundos Unix y completed_at es null mientras no se haya completado la sesión.
La propia persona abre verification_url, comprueba la entidad y el uso que muestra la página, lee y confirma los términos correspondientes y completa las operaciones indicadas. La guía oficial de BytePlus indica que este proceso requiere iniciar sesión con una cuenta personal de BytePlus; si la página solicita permiso para usar la cámara, la propia persona debe manejar el dispositivo y concederlo.
La página oficial puede incluir pasos como la carga de recursos; complétalos siguiendo las indicaciones que aparezcan. Aun así, debes ejecutar el siguiente paso de creación de recursos mediante la API y obtener el ID de recurso devuelto por AIHubMix; no sustituyas directamente ese ID en los ejemplos de la API por otros ID de recursos mostrados en la web.
- Consultar el resultado de la confirmación
El cliente puede consultar cada 10 a 15 segundos y establecer un límite local de espera. Este intervalo es una recomendación de uso. Aunque la web indique que el proceso ha finalizado o devuelva una página en blanco, confirma mediante la API que la sesión esté
verified y el grupo de recursos esté active antes de añadir recursos.
Si al crear otra sesión recibes 409 verification_session_active, consulta primero la sesión y el grupo existentes. No crees sesiones repetidamente mientras exista una sesión válida, el grupo ya haya completado la confirmación o el resultado anterior siga pendiente de confirmación. Si el proceso sigue sin completarse, contacta con soporte.
- Crear un recurso a partir de la dirección de una imagen
Preparar la imagen
Proporciona una dirección HTTP(S) absoluta que devuelva el archivo de imagen, preferiblemente HTTPS. El enlace debe poder leerse sin iniciar sesión ni añadir cabeceras de solicitud; las rutas locales, las direcciones de redes internas, Base64 y las URL con usuario y contraseña no son válidas para la API de creación de recursos. La URL no debe contener un fragmento#.
Según la guía de recursos de personas reales de BytePlus, se recomienda una fotografía frontal nítida que cumpla los siguientes requisitos de incorporación a la biblioteca:
Estos son los requisitos oficiales de la biblioteca de recursos; el modelo de vídeo puede tener restricciones adicionales para los recursos de referencia. Comprueba también los requisitos del modelo de destino antes de cargar el recurso; una creación HTTP correcta no significa que el recurso haya superado el procesamiento.
Solicitud de creación
SustituyeIMAGE_URL por el enlace directo a una imagen para cuyo uso hayas obtenido el consentimiento de la propia persona. El dominio del ejemplo es solo un marcador de posición y no proporciona imágenes de personas reales.
El cuerpo de la solicitud solo acepta estos tres campos.
Idempotency-Key se envía en la cabecera de solicitud, es opcional, admite un máximo de 128 bytes y no puede contener espacios en blanco al principio o al final ni caracteres de control. Consulta los límites de los archivos de audio y vídeo en la guía oficial anterior y comprueba los tipos y duraciones admitidos por el modelo de destino.
La primera creación suele devolver HTTP 201; reutilizar un recurso existente devuelve 200; si el resultado sigue pendiente de confirmación y el estado es reconciling, devuelve 202. Lee siempre el campo status del objeto.
Los campos públicos del recurso son id, object, group_id, asset_type, status, client_reference_id, created_at, updated_at y deleted_at. object es siempre asset; client_reference_id no se devuelve si no se proporcionó o si se ha eliminado, y deleted_at es null mientras el recurso no esté eliminado. Los campos de tiempo se expresan en segundos Unix y las consultas no devuelven la dirección original de la imagen; conserva tus propios registros en la aplicación.
- Esperar a que el recurso esté disponible
Puedes consultar cada 10 a 15 segundos y establecer un límite local de espera. Detener el sondeo local no cancela la operación en el servidor.
- Generar un vídeo con el recurso
Las referencias de vídeo usan el id completo de la respuesta de creación del recurso de AIHubMix, con el formato asset://<asset_id>. Todos los recursos referenciados en una misma solicitud deben pertenecer al mismo grupo y a la cuenta actual, y estar active. El grupo también debe mantenerse disponible.
El tipo de referencia debe coincidir con el
asset_type utilizado al crear el recurso. asset:// se utiliza en los campos de referencia de vídeo y no es una dirección de descarga para el navegador.
Nuevo protocolo de vídeo
Primero, comprueba el Schema actual del modelo según la ruta del endpoint:duration=4, resolution="480p", aspect_ratio="3:4" y generate_audio=false. La nueva API utiliza directamente input_references[].url, donde ASSET_ID es el ID del recurso devuelto anteriormente por AIHubMix:
duration para indicar la duración solicitada; consulta otros valores permitidos en el Schema del modelo. resolution="480p" indica el nivel de resolución solicitado y no garantiza que la anchura o la altura de salida sea exactamente de 480 píxeles; las dimensiones reales dependen del archivo generado. Para los fotogramas inicial y final puedes usar frame_images[].image_url.url junto con frame_type, únicamente si el modelo admite la capacidad correspondiente. Consulta todos los parámetros en Generación de vídeo.
Protocolo de vídeo compatible
Si tu cliente ya usa/v1/videos, coloca las referencias en content o extra_body.content, con la URL anidada en el objeto multimedia correspondiente. Este ejemplo utiliza extra_body.content:
El ejemplo compatible conserva
doubao-seedance-2-0-260128 y se basa en el contrato existente de la API compatible y en la documentación oficial de referencias a recursos de BytePlus. En esta ocasión no se probaron la generación de vídeo con Seedance 2.0 ni la creación compatible mediante /v1/videos; los resultados de la verificación de Seedance 2.5 con la nueva API no se pueden aplicar directamente a este ejemplo.input_references en una solicitud compatible. Si proporcionas content en ambos lugares, extra_body.content sustituye al content de nivel superior; se recomienda proporcionarlo solo en un lugar.
El id devuelto por la API compatible debe consultarse mediante GET /v1/videos/{id} y, una vez completada la tarea, descargarse mediante GET /v1/videos/{id}/content. No uses un ID de la API compatible para consultar /ai/v1/videos. Consulta los detalles en la API de vídeo compatible.
- Consultar periódicamente y descargar el vídeo de la nueva API
El siguiente ejemplo de Python continúa únicamente el paso de creación de la nueva API anterior, lee VIDEO_ID de las variables de entorno y no vuelve a crear la tarea. Requiere instalar requests.
200 no significa que la generación haya tenido éxito; debes comprobar status. El sondeo utiliza /ai/v1/videos/{id}; la API unificada de tareas /ai/v1/tasks/{id} proporciona una instantánea de solo lectura.
Para consultar y descargar el vídeo, utiliza la misma API Key con la que creaste la tarea. Descarga el resultado cuanto antes tras completarse y guárdalo por tu cuenta; los resultados tienen un periodo de retención determinado por expires_at y, una vez caducados, pueden devolver 410 artifact_expired.
Verificación de este flujo
La verificación en producción del 2026-09-07 utilizó un enlace directo HTTPS público a un archivo JPEG, la confirmación web completada por la propia persona y los parámetros de Seedance 2.5 anteriores. Se observaron los siguientes resultados:
El archivo de esta prueba tenía 1,558,358 bytes; ffprobe detectó H.264, 24 fps, 560 × 752 píxeles, 4.041667 segundos y ninguna pista de audio. Estos valores corresponden al resultado de esta generación y no significan que cada solicitud produzca las mismas dimensiones, duración o tamaño de archivo.
Al abrir por primera vez la página de confirmación apareció
internal error; la consulta posterior mediante la API seguía mostrando pending y la causa del error de la página aún no se ha confirmado. Después, en esta prueba se utilizó una página nueva de un grupo de prueba independiente; tras completar la propia persona las operaciones, se confirmó que la sesión estaba verified y el grupo active. El nuevo grupo fue únicamente la forma de proceder en esta prueba; no constituye una recomendación general de recrear grupos repetidamente ni indica que la sesión original haya terminado.
En esta ocasión no se probaron la generación de vídeo con Seedance 2.0, la creación mediante la API compatible, los recursos de audio y vídeo, los fotogramas inicial y final, la eliminación ni otras combinaciones de errores. Las explicaciones correspondientes mantienen como base el contrato de la API y la documentación oficial; esta verificación no cubre todos los escenarios de la guía.
Reintentos idempotentes
- Si se agota el tiempo de espera de creación de un recurso o se pierde la respuesta, conserva los valores originales de
Idempotency-Key,client_reference_id, URL yasset_typey reenvía la misma solicitud. Si cualquiera de los dos identificadores coincide con un recurso existente de la misma cuenta y del mismo grupo, se reutiliza ese recurso. - Si cambia la URL o el
asset_typeasociado al mismo identificador, se devuelve409 asset_idempotency_conflict. Actualizar una URL de imagen firmada también se considera un cambio de URL. - Si no proporcionas ninguno de los dos identificadores, no se garantiza la deduplicación entre solicitudes. Usa un identificador nuevo solo cuando hayas confirmado que deseas crear otro recurso.
- Una vez obtenido el ID del recurso, consulta preferentemente mediante
GET /ai/v1/assets/{id}.reconcilingno equivale a un fallo y no debes volver a crear el recurso con un identificador nuevo. - Una vez completada la eliminación del recurso, los identificadores de idempotencia originales dejan de conservarse. No dependas de ellos para recuperar recursos eliminados ni vuelvas a enviar solicitudes de creación antiguas.
- El contrato de idempotencia de esta sección solo se aplica a la creación de recursos. No se aplica a la creación de grupos, sesiones de confirmación ni vídeos. Si se pierde la respuesta de creación de vídeo de la nueva API, busca primero la tarea original mediante
GET /ai/v1/videos?limit=20&order=descpara evitar generar el vídeo de nuevo.
Eliminar recursos y grupos de recursos
Antes de eliminar un recurso, confirma que hayan finalizado todos los vídeos que lo referencian, incluidas las tareas enviadas mediante la API compatible. La eliminación no se puede deshacer; debes gestionar por tu cuenta los archivos de vídeo ya descargados. Eliminar un recurso individual:202 indica que la eliminación sigue en curso. Continúa consultando mediante GET /ai/v1/assets/{id} hasta que status=deleted. Repetir la eliminación devuelve el estado actual; si es reconciling, sigue comprobando el resultado y contacta con soporte si no se completa.
Eliminar un grupo completo también elimina sus recursos; debes enviar explícitamente cascade=true:
202; consulta mediante GET /ai/v1/asset-groups/{id}. deleting indica que el proceso está en curso, partially_deleted que todavía no se ha eliminado todo y solo deleted indica que ha finalizado. La lista no muestra los grupos eliminados de forma predeterminada.
409 asset_group_in_use indica que aún hay operaciones o tareas de vídeo sin finalizar. Espera, consulta los estados correspondientes y vuelve a intentarlo. Debes confirmar por tu cuenta que las tareas de vídeo compatibles hayan terminado; no dependas de la solicitud de eliminación para detectar automáticamente el uso de recursos por todas las tareas compatibles.
Preguntas frecuentes
¿Por qué no puedo añadir recursos después de completar las operaciones en la web?
Consulta primero la sesión de confirmación y el grupo de recursos; los estados que debes comprobar sonverified y active. Haz la misma comprobación si la web muestra internal error; no crees repetidamente sesiones para el mismo grupo mientras esté pending. Si el resultado sigue pendiente de confirmación, consulta más tarde; si no se completa, proporciona los ID a soporte. No es necesario enviar el enlace de confirmación ni fotografías de la persona.
¿Por qué falla la generación de vídeo si el recurso está disponible?
Comprueba que la referencia utilice el ID del recurso devuelto por AIHubMix, que todos los recursos pertenezcan al mismo grupo, que los tipos de medios coincidan y que el modelo actual admita las entradas correspondientes. El estadoactive indica que el recurso está disponible; aun así, debes comprobar por separado el estado de finalización y los mensajes de error de la tarea de vídeo.
¿Cómo resolver los errores habituales de la API?
Para otros errores de vídeo, consulta los códigos de error de tareas asíncronas. Al informar de un problema, proporciona la hora en que ocurrió, el estado HTTP,
error.code, el error.tid devuelto (si lo hay) y los ID de los recursos correspondientes; no proporciones la API Key, el enlace de confirmación ni direcciones de imágenes firmadas.
Referencias
- BytePlus: añadir recursos de personas reales
- BytePlus: generar vídeos de retratos con Seedance
- Generación de vídeo nativa de AIHubMix
- API de vídeo compatible con OpenAI
- Tareas asíncronas