Verificação do titular e recursos de retrato
Guia comum APIMaster para verificação, recursos e geração Seedance.
Verificação do titular e recursos de retrato
Os quatro modelos usam as mesmas interfaces APIMaster. O backend adapta endpoints, identificadores e estados do fornecedor. Verificação oficial do titular, revisão de retratos pelo canal e recursos comuns ou virtuais são processos distintos. Use apenas fotografias expressamente autorizadas.
1. Capacidades e âmbito
Consulte capacidades com a sua chave APIMaster. Use o channel_id devolvido para vincular o contexto. A disponibilidade depende das permissões, projeto e rota do modelo. Pedidos não suportados são rejeitados sem trocar canal ou modelo. SD1.0, SD1.5 e aliases personalizados exigem verificação separada do protocolo.
| 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. Escolher o fluxo
official_h5 exige sessão e verificação pessoal no telemóvel. channel_material_review usa um grupo purpose=channel_portrait, envio e consulta de recursos; owner_verified=false não prova verificação oficial. purpose=ordinary serve para material comum quando suportado. virtual_or_ordinary não oferece verificação oficial; unverified indica capacidade não verificada. Omitir purpose mantém o comportamento virtual existente.
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. Verificação no telemóvel
Para official_h5, crie uma sessão e peça ao titular que abra h5_link no seu telemóvel. APIMaster aloja o callback HTTPS; não é necessário servidor do cliente. Omita callback_url. Chaves permanentes e BytedToken ficam no servidor. O resultado do navegador não basta: o servidor confirma-o com o fornecedor. Callbacks repetidos não criam recursos adicionais.
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 o resultado
Após completed use o group_id público. Os estados e prazos abaixo são distintos da duração da autorização do retrato. Erros temporários de rede preservam o estado; não crie sessões automaticamente. A consola encontra-se em /console/seedance-materials. Sessão, grupo, recurso e tarefa de vídeo têm 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. Enviar e verificar recursos
POST /uploads aloja apenas o original; POST /assets é o endpoint comum de registo e revisão. POST /v1/seedance2/private-avatar é um alias compatível do mesmo processamento. Apenas Active permite gerar; Processing, Pending e Failed não. Cada nova foto num grupo oficial real_person passa revisão de correspondência da pessoa; channel_portrait continua a ser revisão de recursos. Sucessos parciais mantêm recursos aceites. Após timeout consulte o que já existe; não repita POST automaticamente nem 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. Gerar e descarregar
Antes de gerar consulte /v1/videos/quote: é uma estimativa, não um teto garantido. O servidor mantém canal, conta e projeto compatíveis. Combinações incompatíveis são rejeitadas. Trocar modelo exige validar os seus próprios limites; novas fotos exigem nova revisão. Depois do sucesso consulte o recibo e descarregue o 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. Privacidade e eliminação
Os links assinados são sensíveis: quem os detém pode descarregar durante a validade. Não registe links H5, URLs assinados ou credenciais de callback. Eliminar o original não elimina o recurso do fornecedor. A eliminação remove a associação APIMaster e usa eliminação remota quando suportada; não promete operações remotas indisponíveis. Elimine recursos antes do grupo. Vídeos já gerados não desaparecem automaticamente. Não são guardados modelos biométricos; aprovação não substitui autorização 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. Custos e erros
Verificado em 2026-10-07: a documentação oficial descreve a verificação como temporariamente gratuita. Custos reais de sessão, revisão, envio, armazenamento e gestão dependem do contexto e não estão todos confirmados. Nenhuma compra automática de pacotes. A geração mantém orçamento, reserva, liquidação e reembolso existentes; consulte o recibo real. Os erros distinguem permissões, capacidade indisponível, revisão pendente ou falhada, recursos incompatíveis e resposta incerta do fornecedor. Não é permitido aceder a recursos de outros utilizadores.
| HTTP | context |
|---|---|
| 400 | input / callback |
| 403 | permissions |
| 404 | resource |
| 409 | pending / failed review / incompatible context |
| 429 | rate limit |
| 502 / 503 | uncertain upstream result / unavailable |