Idempotência Seedance e recuperação de envios

Use Idempotency-Key com seedance-2.0, seedance-2.0-fast, seedance-2.0-mini e seedance-2.5. POST /v1/videos, POST /v1/videos/generations e POST /v1/video/generations compartilham as chaves. Imagens, estimativas, remix e outros modelos de vídeo não são cobertos. Sem chave, não há garantia geral de deduplicação.

Escopo e chaves

A chave pertence à conta APIMaster e à operação de vídeo Seedance, não a uma API Key ou modelo individual. Use uma nova chave aleatória de 8–128 caracteres ASCII visíveis por geração. Uma credencial válida da mesma conta pode consultar o recibo. Tokens esgotados podem consultar ou repetir recibos existentes; chaves expiradas, revogadas ou excluídas e contas bloqueadas não. Novas gerações exigem autenticação válida e cota suficiente.

Repetição atômica e conflitos

Um registro atômico é salvo antes do roteamento, cobrança e contato com o fornecedor. Mesma chave e conteúdo retornam HTTP 202, recibo original e ID pré-alocado, sem novo envio ou reserva, inclusive com concorrência e reinícios. Conteúdo diferente retorna HTTP 409 (idempotency_conflict). Ordem dos objetos JSON e espaços são ignorados; ordem de arrays, números, valores omitidos ou padrões explícitos, modelo, notificações e grupo/canal são comparados. multipart compara bytes e ordem dos arquivos, não limites ou nomes. Mantenha corpo e roteamento; JSON e multipart são distintos. Retenção mínima de 30 dias; esta versão não exclui automaticamente nem reutiliza chaves.

Respostas

A primeira requisição mantém a resposta normal. Salve X-Video-Submission-Id, ID de requisição e tarefa. Repetições retornam recibos e podem ter outro formato. O ID pré-alocado não comprova aceitação pelo fornecedor. accepted não significa geração concluída. Consulte a tarefa somente com task_ready=true; caso contrário, contate o suporte sem reenviar.

Estados de envio

pending: registrado no gateway, ainda não enviado. submitting: envio iniciado, resultado pendente. accepted: ID do fornecedor recebido. not_accepted: nenhum envio ao fornecedor; corrija e crie com nova chave. acceptance_unknown: possivelmente aceito, sem confirmação; não gere novamente. Após falha, a consulta classifica registros inacabados depois de 30 minutos: antes do envio not_accepted, depois acceptance_unknown. Não há reenvio automático. São estados de envio, não financeiros; reservas, liquidação e conciliação de reembolsos continuam aplicáveis.

Recuperação

Após timeout ou 5xx consulte a mesma chave, mesmo sem ID. Repetir conteúdo idêntico é seguro, mas não reinicia envios falhos. 404, lista vazia ou ausência de cobranças não comprovam não aceitação: requisição em trânsito, sem chave ou anterior à função. same_key_replay_safe refere-se ao recibo; new_submission_safe=true apenas para not_accepted. Para resultado incerto ou accepted com task_ready=false, envie ao suporte IDs de recibo/requisição, modelo e horário UTC, nunca a API Key. Não há promessa de idempotência no fornecedor oficial. Recibos antigos de retratos mantêm o fluxo e podem usar o esquema anterior.

Exemplos

curl --fail-with-body 'https://apimaster.ai/v1/videos' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: seedance-order-20261014-001' \
  -d '{"model":"seedance-2.0","prompt":"A paper boat on a pond","duration":4,"resolution":"480p","generate_audio":false}'

curl --fail-with-body 'https://apimaster.ai/v1/video-submissions/by-key' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Idempotency-Key: seedance-order-20261014-001'

{
  "code": 200,
  "data": {
    "submission_id": "HASH",
    "task_id": "task_PUBLIC_ID",
    "request_id": "ORIGINAL_REQUEST_ID",
    "model": "seedance-2.0",
    "status": "accepted",
    "task_ready": true,
    "created_at": 1791936000,
    "updated_at": 1791936001,
    "next_action": "query_task",
    "same_key_replay_safe": true,
    "new_submission_safe": false,
    "retention": "at_least_30_days_no_automatic_key_reuse"
  }
}

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"