Idempotencia de Seedance y recuperación de envíos

Use Idempotency-Key con seedance-2.0, seedance-2.0-fast, seedance-2.0-mini y seedance-2.5. POST /v1/videos, POST /v1/videos/generations y POST /v1/video/generations comparten las claves. No cubre imágenes, presupuestos, remix ni otros modelos de vídeo. Sin clave no hay garantía general de deduplicación.

Ámbito y claves

La clave se limita a la cuenta APIMaster y a la operación de generación de vídeo Seedance, no a una API Key o modelo individual. Use una nueva clave aleatoria de 8–128 caracteres ASCII visibles por generación. Una credencial válida de la misma cuenta puede consultar el recibo. Los tokens agotados pueden consultar o repetir recibos existentes; las claves caducadas, revocadas o eliminadas y cuentas bloqueadas no. Las nuevas generaciones requieren credenciales válidas y cuota suficiente.

Repetición atómica y conflictos

Se guarda un registro atómico antes del enrutamiento, cobro y contacto con el proveedor. La misma clave y contenido devuelve HTTP 202, el recibo original y el ID preasignado, sin otro envío ni reserva, incluso con reintentos concurrentes o reinicios. Un cambio devuelve HTTP 409 (idempotency_conflict). Se ignoran orden de objetos JSON y espacios, pero se comparan orden de arrays, números, valores omitidos o predeterminados explícitos, modelo, notificaciones y grupo/canal. En multipart se comparan bytes y orden de archivos, no límites ni nombres. Mantenga cuerpo y ruta; JSON y multipart son distintos. Se conservan al menos 30 días; esta versión no elimina registros automáticamente ni reutiliza claves.

Respuestas

La primera petición conserva la respuesta habitual. Guarde X-Video-Submission-Id, ID de petición y tarea. Las repeticiones devuelven un recibo con formato posiblemente distinto. El ID preasignado no demuestra aceptación del proveedor. accepted no significa generación completada. Consulte la tarea solo con task_ready=true; de lo contrario contacte con soporte sin reenviar.

Estados de envío

pending: registrado en la pasarela, aún sin enviar. submitting: envío iniciado, resultado pendiente. accepted: ID del proveedor recibido. not_accepted: no se envió al proveedor; corrija y cree con nueva clave. acceptance_unknown: posiblemente aceptado, sin confirmación; no genere otra vez. Tras una caída, la consulta clasifica registros sin terminar después de 30 minutos: antes del envío not_accepted, después acceptance_unknown. No hay reenvío automático. Son estados de envío, no de facturación; siguen aplicándose reservas, liquidación y conciliación de devoluciones.

Recuperación

Tras timeout o 5xx consulte la misma clave, aunque no tenga ID. Repetir idénticamente es seguro pero no reinicia envíos fallidos. Un 404, lista vacía o ausencia de cargos no demuestra falta de aceptación: puede haber una petición en tránsito, sin clave o anterior a esta función. same_key_replay_safe permite recuperar el recibo; new_submission_safe=true solo aparece para not_accepted. En resultado desconocido o accepted con task_ready=false, dé a soporte los ID de recibo/petición, modelo y hora UTC, nunca la API Key. No se garantiza idempotencia del proveedor oficial. Los recibos antiguos de retratos mantienen su proceso y pueden devolver el esquema anterior.

Ejemplos

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"