Idempotenza Seedance e recupero degli invii

Usare Idempotency-Key per 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 condividono le chiavi. Immagini, preventivi, remix e altri modelli video sono esclusi. Senza chiave non esiste garanzia generale di deduplicazione.

Ambito e chiavi

La chiave è relativa all’account APIMaster e all’operazione video Seedance, non a una singola API Key o modello. Per ogni nuova generazione usare una nuova chiave casuale di 8–128 caratteri ASCII visibili. Una credenziale valida dello stesso account può consultare la ricevuta. I token esauriti possono consultare o ripetere ricevute esistenti; chiavi scadute, revocate o eliminate e account bloccati no. Nuove generazioni richiedono credenziali valide e quota sufficiente.

Ripetizione atomica e conflitti

Una registrazione atomica precede routing, addebito e contatto con il fornitore. Stessa chiave e contenuto restituiscono HTTP 202, ricevuta originale e ID preassegnato, senza nuovo invio o prenotazione, anche con concorrenza e riavvii. Contenuto diverso restituisce HTTP 409 (idempotency_conflict). Ordine degli oggetti JSON e spazi ignorati; ordine degli array, numeri, valori omessi o predefiniti espliciti, modello, notifiche e gruppo/canale vengono confrontati. multipart confronta byte e ordine dei file, non nomi e delimitatori. Mantenere corpo e routing; JSON e multipart sono distinti. Conservazione minima 30 giorni; questa versione non elimina automaticamente né riutilizza chiavi.

Risposte

La prima richiesta conserva la risposta normale. Salvare X-Video-Submission-Id, ID richiesta e task. Le ripetizioni restituiscono la ricevuta, non necessariamente il formato iniziale. Un ID preassegnato non prova l’accettazione del fornitore. accepted non significa generazione completata. Consultare il task solo con task_ready=true, altrimenti contattare il supporto senza reinviare.

Stati di invio

pending: registrato nel gateway, non inviato. submitting: invio iniziato, esito in attesa. accepted: ID del fornitore ricevuto. not_accepted: nessun invio al fornitore; correggere e creare con nuova chiave. acceptance_unknown: possibile accettazione senza conferma; non generare di nuovo. Dopo un arresto anomalo, la consultazione classifica dopo 30 minuti: prima dell’invio not_accepted, dopo acceptance_unknown. Nessun reinvio automatico. Sono stati di invio, non contabili; prenotazioni, liquidazione e riconciliazione rimborsi restano applicabili.

Recupero

Dopo timeout o 5xx consultare la stessa chiave anche senza ID task. Ripetere identicamente è sicuro ma non riavvia l’invio fallito. 404, elenco vuoto o assenza di addebiti non provano mancata accettazione: richiesta in transito, senza chiave o precedente alla funzione. same_key_replay_safe riguarda la ricevuta; new_submission_safe=true solo per not_accepted. Per esito incerto o accepted con task_ready=false, fornire al supporto ID ricevuta/richiesta, modello e ora UTC, mai API Key. Nessuna garanzia di idempotenza ufficiale a monte. Le vecchie ricevute dei ritratti mantengono procedura e possibile schema precedente.

Esempi

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"