Skip to main content
Los recursos de personas reales permiten hacer referencia en vídeos a la imagen de una persona que ha completado su propia confirmación. El proceso consiste en crear un grupo de recursos, obtener la confirmación de la propia persona en la web, añadir recursos, esperar a que estén disponibles y enviar una tarea de generación de vídeo. Esta página utiliza recursos de imagen como ejemplo y la API de AIHubMix para gestionarlos, con preferencia por la nueva API /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.
Prepara el entorno de la terminal; tu entorno de ejecución debe haber proporcionado ya la API Key:

  1. Crear un grupo de recursos

El cuerpo de la solicitud solo acepta 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:
La lista devuelve 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.

  1. Obtener el enlace de confirmación de la propia persona

Crea una sesión de confirmación sin cuerpo de solicitud:
Una creación correcta devuelve HTTP 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.
verification_url solo se devuelve en la respuesta de creación correcta; las consultas posteriores no vuelven a devolver el enlace. Entrégalo cuanto antes a la persona que aparece en los recursos y no lo incluyas en registros públicos, repositorios de código ni capturas de pantalla enviadas como comentarios. Su validez está determinada por expires_at; una vez caducado, el enlace original ya no se puede usar.
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.

  1. 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.
Que la web muestre internal error no significa que la sesión de confirmación haya terminado. Ejecuta primero las dos solicitudes GET de esta sección para consultar la sesión y el grupo; si la sesión sigue pending, no crees repetidamente sesiones para el mismo grupo. Continúa añadiendo recursos solo cuando la sesión esté verified y el grupo esté active. El error de la web por sí solo no permite determinar la causa; si el proceso sigue sin completarse, conserva los ID y contacta con soporte.

  1. 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

Sustituye IMAGE_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.

  1. 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.
Si se desconoce el resultado de creación y sigue sin encontrarse un resultado coincidente, el recurso puede permanecer en reconciling y también puede verse afectada la eliminación del recurso o de su grupo. Conserva el ID y los identificadores originales de la solicitud y contacta con soporte; no crees recursos repetidamente cambiando los identificadores ni supongas que se limpiarán automáticamente tras un tiempo de espera.

  1. 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:
Envía la solicitud tras confirmar que el modelo admite imágenes de referencia. A continuación se usan los parámetros de Seedance 2.5 verificados correctamente en producción en esta prueba: 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:
La nueva API utiliza un entero 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.
Elige y ejecuta uno de los dos ejemplos; cada creación de vídeo es una solicitud independiente. No incluyas 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.

  1. 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.
Los 30 minutos son el límite local de espera del ejemplo y no representan el tiempo de espera máximo de la tarea en el servidor. Una consulta HTTP 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 y asset_type y 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_type asociado al mismo identificador, se devuelve 409 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}. reconciling no 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=desc para 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:
Una respuesta 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:
Tras aceptar la solicitud, se devuelve 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 son verified 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 estado active 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

Última actualización: 2026-09-07