> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Guía de recursos de personas reales de Doubao > Crea recursos de personas reales mediante la confirmación web de la propia persona, genera vídeos con Doubao Seedance mediante referencias asset:// y consulta, reintenta y elimina recursos. 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](#compatible-video).

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](/es/api/async-tasks) 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](#verified-flow); 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: ```bash theme={null} set -euo pipefail : "${AIHUBMIX_API_KEY:?请先配置 AIHUBMIX_API_KEY 环境变量}" BASE_URL="https://aihubmix.com" MODEL="doubao-seedance-2-5-260628" ```

1. Crear un grupo de recursos

```bash theme={null} GROUP_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"我的真人素材"}') printf '%s\n' "$GROUP_JSON" | jq . GROUP_ID=$(printf '%s' "$GROUP_JSON" | jq -er '.id') ``` 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: ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 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.

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

Crea una sesión de confirmación sin cuerpo de solicitud: ```bash theme={null} SESSION_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY") SESSION_ID=$(printf '%s' "$SESSION_JSON" | jq -er '.id') printf '%s' "$SESSION_JSON" | jq '{id, status, expires_at, verification_url}' ``` 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.

3. Consultar el resultado de la confirmación

```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/verification-sessions/$SESSION_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups/$GROUP_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` | Estado de la sesión | Siguiente paso | | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | `creating` | La sesión sigue creándose; consulta más tarde y contacta con soporte si no se completa | | `pending` | Se espera a que la propia persona complete el proceso o a que se confirme el resultado; vuelve a consultar más tarde | | `verified` | La confirmación de la propia persona ha finalizado; comprueba que el grupo de recursos esté `active` | | `rejected` | Esta confirmación no se ha aprobado; revisa las indicaciones de la web e iníciala de nuevo | | `expired` | Esta confirmación ha caducado; inicia otra | | `failed` | Esta confirmación ha fallado; revisa el mensaje de error y contacta con soporte si es necesario | 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](/es/FAQs/Feedback). 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.

4. 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](https://docs.byteplus.com/en/docs/ModelArk/2315856), se recomienda una fotografía frontal nítida que cumpla los siguientes requisitos de incorporación a la biblioteca: | Elemento | Requisito | | ------------------- | ----------------------------------------------------------------------------------- | | Formato | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF | | Tamaño por imagen | Menos de 30 MB | | Relación de aspecto | Mayor que 0.4 y menor que 2.5 | | Anchura y altura | Ambas mayores que 300 píxeles y menores que 6000 píxeles | | Persona | Debe coincidir con la persona que completó la confirmación de ese grupo de recursos | 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. ```bash theme={null} IMAGE_URL="https://cdn.example.com/portrait.jpg" ASSET_KEY="portrait-image-001" ASSET_BODY=$(jq -n --arg url "$IMAGE_URL" --arg ref "$ASSET_KEY" \ '{url: $url, asset_type: "image", client_reference_id: $ref}') ASSET_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/assets" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $ASSET_KEY" \ -d "$ASSET_BODY") printf '%s\n' "$ASSET_JSON" | jq . ASSET_ID=$(printf '%s' "$ASSET_JSON" | jq -er '.id') ``` | Campo de la solicitud | Obligatorio | Descripción | | --------------------- | ----------- | ---------------------------------------------------------------------- | | `url` | Sí | Dirección accesible del archivo del recurso | | `asset_type` | Sí | `image`, `video` o `audio`; este ejemplo usa `image` | | `client_reference_id` | No | Identificador del recurso en tu aplicación, con un máximo de 128 bytes | 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.

5. Esperar a que el recurso esté disponible

```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` | Estado del recurso | Significado y acción | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `creating` | La creación aún no ha finalizado; conserva el ID y consulta más tarde | | `processing` | Se está procesando; sigue consultando | | `active` | Puede utilizarse como recurso de referencia para vídeos | | `failed` | El procesamiento del recurso ha fallado; revisa la imagen y los requisitos de coincidencia de la persona | | `reconciling` | El resultado de la creación o eliminación sigue pendiente de confirmación; sigue consultando y no lo uses aún en vídeos | | `deleting` | La eliminación está en curso; no lo uses aún en vídeos | | `deleted` | La eliminación ha finalizado; no vuelvas a usarlo en vídeos | 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.

6. 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://`. 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. | Tipo de recurso | Nueva API `input_references[].type` | Campo anidado de la API compatible | | --------------- | ----------------------------------- | ---------------------------------- | | `image` | `image_url` | `image_url.url` | | `video` | `video_url` | `video_url.url` | | `audio` | `audio_url` | `audio_url.url` | 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: ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \ | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema' ``` 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: ```bash theme={null} VIDEO_BODY=$(jq -n --arg model "$MODEL" --arg asset "asset://$ASSET_ID" \ '{model: $model, prompt: "The person in the reference image smiles and waves at the camera.", duration: 4, resolution: "480p", aspect_ratio: "3:4", generate_audio: false, input_references: [{type: "image_url", url: $asset}]}') VIDEO_JSON=$(curl --fail-with-body -sS --max-time 120 \ -X POST "$BASE_URL/ai/v1/videos" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d "$VIDEO_BODY") printf '%s\n' "$VIDEO_JSON" | jq . VIDEO_ID=$(printf '%s' "$VIDEO_JSON" | jq -er '.id') export VIDEO_ID ``` 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](/es/api/aihubmix-video-generation).

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. ```bash theme={null} COMPAT_MODEL="doubao-seedance-2-0-260128" COMPAT_BODY=$(jq -n --arg model "$COMPAT_MODEL" --arg asset "asset://$ASSET_ID" \ '{model: $model, prompt: "The person in the reference image smiles and waves at the camera.", extra_body: {content: [{type: "image_url", image_url: {url: $asset}, role: "reference_image"}]}}') curl --fail-with-body -sS --max-time 120 \ -X POST "$BASE_URL/v1/videos" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d "$COMPAT_BODY" | jq . ``` 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](/es/api/Video-Gen).

7. 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`. ```python theme={null} import os import time from pathlib import Path import requests base_url = "https://aihubmix.com" video_id = os.environ["VIDEO_ID"] headers = {"Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}"} deadline = time.monotonic() + 1800 while time.monotonic() < deadline: response = requests.get( f"{base_url}/ai/v1/videos/{video_id}", headers=headers, timeout=30 ) response.raise_for_status() task = response.json() status = task["status"] if status == "completed": break if status in {"failed", "cancelled"}: raise RuntimeError(f"视频任务未完成：{task.get('error') or status}") time.sleep(15) else: raise TimeoutError(f"本地等待已结束，请稍后继续查询原任务：{video_id}") temporary = Path("result.mp4.part") with requests.get( f"{base_url}/ai/v1/videos/{video_id}/content", headers=headers, timeout=120, stream=True, ) as response: response.raise_for_status() with temporary.open("wb") as output: for chunk in response.iter_content(chunk_size=1024 * 1024): if chunk: output.write(chunk) temporary.replace("result.mp4") print("视频已保存为 result.mp4") ``` 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: | Paso | Resultado de esta prueba | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Crear el grupo de recursos | HTTP `201`, `status=pending_auth` | | Crear la sesión de confirmación | HTTP `201`, `status=pending` | | Consultar tras la confirmación de la propia persona | Sesión HTTP `200`, `status=verified`; grupo de recursos `active` | | Crear y consultar el recurso de imagen | Creación HTTP `201`, `status=processing`; consulta posterior HTTP `200`, `status=active` | | Crear y consultar el vídeo con la nueva API | Creación HTTP `200`, `status=in_progress`; consulta posterior HTTP `200`, `status=completed`, `error=null` | | Descargar el vídeo | HTTP `200`, `Content-Type: video/mp4`; el archivo se decodificó por completo con ffmpeg | 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: ```bash theme={null} curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 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`: ```bash theme={null} curl --fail-with-body -sS -X DELETE \ "$BASE_URL/ai/v1/asset-groups/$GROUP_ID?cascade=true" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 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?

| HTTP | `error.code` | Acción | | ---- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | 400 | `invalid_request` | Comprueba los campos, la estructura de la solicitud y el protocolo de vídeo utilizado | | 400 | `asset_group_invalid` | Comprueba el nombre del grupo de recursos | | 400 | `asset_invalid` | Comprueba la URL, el tipo de recurso y los identificadores de la solicitud | | 400 | `asset_binding_mismatch` | En una misma solicitud de vídeo, referencia únicamente recursos de un mismo grupo | | 400 | `cascade_confirmation_required` | Envía `cascade=true` tras confirmar que deseas eliminar todo el grupo | | 401 | `authentication_failed` | Comprueba la variable de entorno de la API Key y la cabecera de autenticación | | 403 | `async_not_enabled` | Activa las tareas asíncronas antes de usar la nueva API de vídeo | | 404 | `asset_group_not_found`, `asset_not_found`, `verification_session_not_found` | Comprueba el ID del recurso y la cuenta a la que pertenece | | 409 | `asset_group_not_verified` | Consulta el resultado de la confirmación de la propia persona y espera a que el grupo esté disponible | | 409 | `verification_session_active` | Consulta la sesión o el grupo existentes para evitar iniciar el proceso de nuevo | | 409 | `asset_not_ready` | Consulta el estado del recurso y espera a que esté `active` antes de generar el vídeo | | 409 | `asset_idempotency_conflict` | Comprueba la URL y el tipo originales asociados al identificador | | 409 | `asset_group_in_use` | Espera a que finalicen las operaciones y tareas de vídeo correspondientes antes de eliminar | | 503 | `asset_group_unavailable`, `verification_unavailable`, `asset_unavailable` | Reintenta más tarde; si el servicio sigue sin estar disponible, contacta con soporte | Para otros errores de vídeo, consulta los [códigos de error de tareas asíncronas](/es/api/async-tasks#error-codes). 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](https://docs.byteplus.com/en/docs/ModelArk/2315856) * [BytePlus: generar vídeos de retratos con Seedance](https://docs.byteplus.com/en/docs/ModelArk/2608626) * [Generación de vídeo nativa de AIHubMix](/es/api/aihubmix-video-generation) * [API de vídeo compatible con OpenAI](/es/api/Video-Gen) * [Tareas asíncronas](/es/api/async-tasks) Última actualización: 2026-09-07