Seedance : idempotence et récupération des soumissions

Ajoutez Idempotency-Key pour seedance-2.0, seedance-2.0-fast, seedance-2.0-mini et seedance-2.5. Les chemins POST /v1/videos, POST /v1/videos/generations et POST /v1/video/generations partagent le même espace de clés. Images, devis, remix et autres modèles vidéo sont exclus. Sans clé, aucune garantie générale de déduplication des soumissions.

Portée et clés

La clé appartient au compte APIMaster et à l’opération de génération vidéo Seedance, pas à une API Key ni à un modèle particulier. Utilisez une nouvelle clé aléatoire de 8–128 caractères ASCII visibles par génération. Une clé d’authentification valide du même compte peut consulter le reçu. Les jetons épuisés peuvent consulter ou rejouer les reçus existants ; les clés expirées, révoquées ou supprimées et les comptes bloqués ne le peuvent pas. Une nouvelle génération exige une authentification valide et un quota suffisant.

Rejeu atomique et conflits

Un reçu atomique est enregistré avant routage, facturation et appel du fournisseur. Même clé et contenu : HTTP 202 avec le reçu original et l’ID de tâche préattribué, sans nouvelle soumission ni réservation, même en concurrence ou après redémarrage. Un contenu différent donne HTTP 409 (idempotency_conflict). Ordre des objets JSON et espaces ignorés ; ordre des tableaux, nombres, valeurs omises ou explicitement par défaut, modèle, notifications et groupe/canal de routage sont comparés. En multipart, les octets et l’ordre des fichiers comptent, pas les frontières ou noms. Conservez corps et routage ; JSON et multipart sont distincts. Les reçus restent au moins 30 jours ; cette version ne les supprime pas automatiquement et ne réutilise pas les clés.

Réponses

La première requête garde la réponse normale. Enregistrez X-Video-Submission-Id, l’ID de requête et de tâche. Un rejeu renvoie un reçu, pas nécessairement le format initial. L’ID préattribué ne prouve pas l’acceptation du fournisseur. accepted ne signifie pas génération terminée. Consultez la tâche uniquement si task_ready=true, sinon contactez le support sans soumettre à nouveau.

États de soumission

pending : enregistré à la passerelle, non envoyé. submitting : envoi commencé, résultat attendu. accepted : ID fournisseur reçu. not_accepted : aucun envoi fournisseur ; corrigez puis créez avec une nouvelle clé. acceptance_unknown : acceptation possible sans confirmation ; aucune nouvelle génération. Après un arrêt anormal, les reçus inachevés sont classés à la consultation après 30 minutes : avant envoi not_accepted, après envoi acceptance_unknown. Aucun renvoi automatique. Ces états concernent la soumission, pas la facturation ; réservation, règlement et rapprochement des remboursements restent applicables.

Récupération

Après délai dépassé ou 5xx, consultez avec la même clé, même sans ID de tâche. Rejouer à l’identique est sûr mais ne relance pas une soumission échouée. Un 404, une liste vide ou l’absence de frais ne prouvent pas la non-acceptation : requête encore en transit, sans clé ou antérieure à cette fonction. same_key_replay_safe concerne le reçu ; new_submission_safe=true uniquement pour not_accepted. Pour un résultat inconnu ou accepted avec task_ready=false, transmettez au support les ID de reçu/requête, le modèle et l’heure UTC, jamais votre API Key. Aucune promesse d’idempotence officielle en amont. Les anciens reçus de portraits conservent leur procédure et peuvent utiliser l’ancien schéma.

Exemples

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"