Verificación del titular y recursos de retrato
Guía común de APIMaster para verificación, recursos y generación Seedance.
Verificación del titular y recursos de retrato
Use la biblioteca unificada para imágenes, vídeos y audio ordinarios. Cree el grupo solo con el modelo y el nombre, sin channel_id ni purpose. El servidor gestiona la revisión y las copias de los modelos de destino.
Importante: las celebridades y las personas no famosas siguen procesos distintos
Solo las celebridades necesitan el endpoint de verificación de personas reales para iniciar la prueba de vida:
POST /v1/seedance2/private-avatar/verifications.Las personas no famosas deben enviar sus recursos directamente a revisión mediante
POST /v1/seedance2/private-avatar/assets. No utilicen el endpoint de verificación de personas reales ni creen una sesión de prueba de vida. El recurso podrá referenciarse cuando su estado seaActive.
Los cuatro modelos utilizan las mismas interfaces de APIMaster. El servidor adapta las rutas, identificadores y estados del proveedor. La verificación oficial del titular, la revisión de retratos del canal y los recursos normales o virtuales son procesos distintos. Utilice únicamente fotos expresamente autorizadas.
1. Capacidades y alcance
Para la verificación oficial H5, consulte las capacidades y use un channel_id disponible con el método official_h5. El envío ordinario a la biblioteca unificada no requiere elegir un canal.
| model | duration | Image | Video | Audio |
|---|---|---|---|---|
| seedance-2.0 | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.0-fast | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.0-mini | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.5 | 4–30 s / -1 | ≤30 | ≤10 / ≤30 s | ≤10 / ≤30 s |
Materiales unificados: crear, guardar y reutilizar
Use la biblioteca unificada para imágenes, vídeos y audio ordinarios. Cree el grupo solo con el modelo y el nombre, sin channel_id ni purpose. El servidor gestiona la revisión y las copias de los modelos de destino.
export APIMASTER_KEY='<your APIMaster key>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/groups' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-d '{"model":"seedance-2.5","name":"My materials"}'
asset_type: Image / Video / Audio.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: unified-audio-001' \
-d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Audio","assets":[{"url":"https://your-storage.example/audio.mp3","name":"Reference audio"}]}'
Guarde group_id (data.id), asset_id y asset_url (la referencia asset://). Envíe los materiales a revisión y consulte la tarea, available_models y model_readiness antes de generar con un modelo preparado. El mismo ID puede reutilizarse mientras siga disponible; la eliminación, la caducidad o nuevas copias pueden requerir un original accesible. La verificación oficial H5 del titular es un proceso separado y no es un requisito para la revisión ordinaria.
3. Verificación desde el móvil
Esta sección se aplica únicamente a celebridades. Las personas no famosas deben omitir la prueba de vida y pasar directamente al envío y revisión de recursos.
Para official_h5, cree una sesión y haga que el titular abra h5_link en su teléfono. APIMaster aloja el callback HTTPS; el cliente no necesita su propio servidor. Omita callback_url. Las claves permanentes y BytedToken permanecen en el servidor. El resultado del navegador no basta: el servidor lo confirma con el proveedor. Los callbacks repetidos no crean recursos adicionales.
export APIMASTER_KEY='<your APIMaster key>'
export APIMASTER_CHANNEL_ID='<available channel ID from the capability API>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/capabilities?model=seedance-2.5' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-session-001' \
-d "{\"model\":\"seedance-2.5\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"name\":\"My portrait\"}"
4. Confirmar el resultado
Al llegar a completed, utilice el group_id público. Los estados y plazos siguientes son distintos de la duración de autorización del retrato. Los errores temporales de red conservan el estado; no cree sesiones nuevas automáticamente. La consola está en /console/seedance-materials. Sesión, grupo, recurso y tarea de vídeo tienen identificadores separados.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications/verification_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
| API | fields / values |
|---|---|
| capabilities | model, channel_id, method, configured, reason, hosted_callback, real_person_verified |
| verification | session_id (id), method, status, h5_link (verification_url), created_at, expires_at, group_id |
| verification.status | creating, pending, completed, failed, expired, failed_unconfirmed, submission_unknown |
| Idempotency-Key | 8–128; same request → original receipt; changed request → 409 |
| verification rate | ≤3 / user / minute; upstream limits also apply |
| H5 / BytedToken | single-use H5; query credential ≤30 min; expires_at ≠ portrait authorization expiry |
5. Subir y revisar recursos
Las personas no famosas solo necesitan el endpoint de envío de recursos de esta sección; no deben llamar primero al de verificación de personas reales.
POST /uploads aloja el original; POST /assets envía los materiales a revisión. Los grupos ordinarios usan unified_virtual. Genere solo cuando el modelo de destino esté preparado. Las fotos nuevas de un grupo oficial real_person siguen requiriendo comprobar que es la misma persona. Los éxitos parciales conservan los materiales aceptados. Si el envío no está confirmado, conserve los ID originales, consulte el estado y no vuelva a subir el archivo automáticamente.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/uploads' \
-H "Authorization: Bearer $APIMASTER_KEY" -F 'file=@authorized-owner.png'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-asset-001' \
-d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Image","assets":[{"url":"<signed upload URL>","name":"Owner"}]}'
curl --fail-with-body 'https://apimaster.ai/v1/tasks/asset_task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
| API | fields / values |
|---|---|
| uploads | JPEG / PNG ≤10 MB; upload_id, url, url_expires_at, delete_after |
| groups | public id; group_type=unified_virtual / real_person |
| assets | public asset_id; status=Pending / Processing / Active / Failed / SubmissionUnknown |
| review task | asset_task_*; GET /v1/tasks/{id} |
6. Generar y descargar
Antes de generar, solicite /v1/videos/quote: es una estimación, no un máximo garantizado. El servidor mantiene canal, cuenta y proyecto compatibles. Rechaza combinaciones incompatibles. Cambiar de modelo exige validar sus propios límites; añadir fotos exige nueva revisión. Después del éxito consulte el recibo y descargue el vídeo.
curl --fail-with-body 'https://apimaster.ai/v1/videos' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-video-001' \
-d '{"model":"seedance-2.5","prompt":"The person smiles naturally","image_urls":["asset://asset_PUBLIC_ID"],"resolution":"480p","duration":4,"generate_audio":false}'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/video-requests/video_request_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/billing' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/content' -H "Authorization: Bearer $APIMASTER_KEY" -o owner.mp4
| API | fields / values |
|---|---|
| generation | Idempotency-Key required; no automatic POST retry |
| receipt | video_request_*; X-Seedance-Request-Id; replay → 202 + original receipt |
| video task | task_*; separate from receipt, verification and asset IDs |
7. Privacidad y eliminación
Los enlaces firmados son sensibles: sus poseedores pueden descargar durante su vigencia. No registre enlaces H5, URL firmadas ni credenciales de callback. Eliminar el original alojado no elimina el recurso del proveedor. El borrado elimina la asociación APIMaster y usa el borrado remoto cuando existe; no promete operaciones remotas no compatibles. Elimine recursos antes del grupo. Los vídeos ya generados no desaparecen automáticamente. No se guardan plantillas biométricas; la aprobación no sustituye autorización de uso.
| API / storage | values |
|---|---|
| signed original URL | 1 h |
| hosted original | access ≤24 h; deletion ≤25 h |
| DELETE /uploads/{upload_id} | hosted original |
| DELETE /assets/{asset_id} | APIMaster mapping; upstream deletion if supported |
| DELETE /groups/{group_id} | empty group |
8. Costes y errores
Comprobado el 2026-10-07: la documentación oficial describe la verificación como temporalmente gratuita. Los costes reales de sesión, revisión, subida, almacenamiento y gestión dependen del contexto y no están todos confirmados. No se compran paquetes automáticamente. La generación conserva presupuesto, reserva, liquidación y reembolso existentes; consulte el recibo real. Los errores distinguen permisos, capacidad no disponible, revisión pendiente o fallida, recursos incompatibles y respuesta incierta del proveedor. No se permite acceder a recursos de otro usuario.
| HTTP | context |
|---|---|
| 400 | input / callback |
| 403 | permissions |
| 404 | resource |
| 409 | pending / failed review / incompatible context |
| 429 | rate limit |
| 502 / 503 | uncertain upstream result / unavailable |
Idempotencia de Seedance y recuperación de envíos
Materiales virtuales y recuperación automática
Un grupo virtual sin channel_id permite usar un ID asset:// con modelos compatibles. available_models, model_readiness y all_models_ready indican disponibilidad. Cada servicio revisa sus copias de forma independiente. Consulte la tarea de revisión; preparar copias requiere el original accesible. Los canales explícitos, grupos de materiales existentes y los materiales H5 oficiales conservan sus restricciones.
La generación requiere Idempotency-Key. Antes de la aceptación solo puede cambiarse de servicio tras un rechazo explícito por límite de tasa sin ID de tarea. Una tarea aceptada que termine por cuenta deshabilitada, credencial inválida o fallo de servicio confirmado puede recuperarse automáticamente una sola vez si hay un servicio compatible. Conserva el ID público y la tarifa del usuario fijada, sin segunda reserva de generación. Consulte la tarea original y su recibo de facturación.
El destino necesita copias compatibles aprobadas o completar su propia revisión. Las aprobaciones y la verificación H5 oficial no se transfieren entre servicios o cuentas. Se excluyen errores de parámetros, moderación, derechos de autor, tiempos de espera, desconexiones y aceptación incierta. Antes de reenviar manualmente consulte el recibo; clave nueva solo con new_submission_safe=true.
