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
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
Consulte capacidades con su clave APIMaster. Use el channel_id devuelto para vincular el contexto. La disponibilidad depende de permisos, proyecto y ruta del modelo. Los flujos no compatibles se rechazan sin cambiar canal ni modelo. SD1.0, SD1.5 y alias personalizados requieren comprobar su protocolo por separado.
| 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 |
2. Elegir el flujo
official_h5 requiere una sesión y la verificación personal desde el móvil. channel_material_review utiliza un grupo purpose=channel_portrait, envío y consulta de recursos; owner_verified=false no demuestra verificación oficial. purpose=ordinary sirve para recursos normales cuando existe esa capacidad. virtual_or_ordinary no admite verificación oficial; unverified indica capacidad sin verificar. Omitir purpose conserva el comportamiento existente de grupos virtuales.
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\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"purpose\":\"channel_portrait\",\"name\":\"Authorized portrait materials\"}"
3. Verificación desde el móvil
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
POST /uploads solo aloja el original; POST /assets es el punto compartido de registro y revisión. POST /v1/seedance2/private-avatar es un alias compatible del mismo procesamiento. Solo Active permite generar; Processing, Pending y Failed no. Cada foto nueva de un grupo oficial real_person pasa revisión de identidad consistente; channel_portrait sigue siendo revisión de recursos. Un éxito parcial conserva los recursos aceptados. Tras un timeout consulte lo ya enviado, no repita POST automáticamente ni invente asset_id.
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=virtual / ordinary / channel_portrait / real_person |
| assets | public asset_id; status=Pending / Processing / Active / Failed |
| channel_material_review | verification_method, owner_verified=false, material_purpose, review.scope_model |
| 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; hourly cleanup ≤25 h; private files 0600 |
| 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 |