# ¿Cómo evitar trabajos de video duplicados cuando una solicitud de API agota el tiempo? > Evita trabajos de video duplicados asignando a cada salida prevista una clave de operación estable, guardando la solicitud antes de enviarla, usando la idempotencia documentada del proveedor cuando exista y conciliando los timeouts ambiguos antes de reintentar. Un timeout significa que el resultado es desconocido, no que el proveedor haya rechazado el trabajo. # ¿Cómo evitar trabajos de video duplicados cuando una solicitud de API agota el tiempo? Un timeout de envío crea un resultado ambiguo. La solicitud puede haber fallado antes de llegar al servicio, haber llegado y sido rechazada o haber creado un trabajo remoto cuya respuesta nunca volvió al cliente. Reintentar de inmediato puede convertir un solo clip previsto en dos generaciones pagadas. La solución es una capa de operaciones idempotentes alrededor de la API de video. Crea y guarda primero la operación prevista, asígnale una clave estable, registra cada intento y usa la idempotencia o la consulta que el proveedor documente. Si no puede demostrarse el resultado remoto, mueve la operación a un estado desconocido explícito en vez de asumir que falló. ## Define un único efecto previsto Una clave de idempotencia debe identificar lo que el usuario pidió crear, no un intento HTTP individual. Si cada reintento recibe una clave nueva, el proveedor no puede reconocer el duplicado. En un flujo de catálogo, una operación puede definirse mediante: * ID del producto; * versión de la plantilla creativa; * huella del medio de origen; * versión del prompt; * locale; * relación de aspecto; * nombre de la variante. Crea una representación canónica con orden estable de claves y valores normalizados, y después calcula su hash. Guarda las dimensiones legibles junto al hash. Un usuario que solicite intencionalmente otra generación independiente debe crear una operación o variante nueva, aunque el prompt sea idéntico. No uses un UUID aleatorio generado dentro del bucle de reintentos. Genera la clave antes de la primera solicitud y reutilízala hasta que ese efecto previsto llegue a un estado terminal. ## Persiste antes de enviar La base de datos local debe conocer la operación antes de que comience la llamada de red. Es el principio de escritura anticipada aplicado a efectos de API. Un registro de operación puede incluir: | Campo | Propósito | |---|---| | Clave de operación | Evita intención local duplicada | | Hash de solicitud | Demuestra qué parámetros se enviaron | | Estado | Distingue preparada, enviada, desconocida y completa | | Número de intentos | Aplica una política de reintentos limitada | | Proveedor y modelo | Permite enrutamiento y conciliación | | ID de trabajo remoto | Reanuda consultas sin volver a enviar | | Último error | Conserva contexto de diagnóstico | | Checksum de salida | Detecta activos duplicados o modificados | Aplica una restricción única a la clave de operación. Dos workers que intenten crear la misma operación deben converger en un registro. Reclama el registro con una actualización atómica o un arrendamiento antes de enviar la solicitud. ## Usa la idempotencia del proveedor solo como esté documentada Algunas API aceptan una clave de idempotencia o token de solicitud y devuelven el resultado de la primera solicitud aceptada cuando se repite la clave. Es la vía más sólida cuando la documentación cubre claramente el endpoint, el periodo de retención, la comparación de parámetros y los errores. Comprueba cuatro detalles: * si el endpoint de video admite la clave; * cuánto tiempo la recuerda el proveedor; * si se rechaza la misma clave con parámetros diferentes; * si los reintentos devuelven el ID del trabajo remoto original. No supongas que un header admitido para pagos o solicitudes síncronas de texto también se aplica a trabajos asíncronos de video. Una forma de solicitud compatible con OpenAI no convierte automáticamente la creación de trabajos de cada proveedor en idempotente. ## Trata los timeouts como resultados desconocidos Usa estados que describan evidencia, no expectativas. | Estado | Evidencia | Siguiente acción | |---|---|---| | `prepared` | Existe el registro local y no comenzó el envío | Enviar | | `sending` | El worker inició la solicitud | Esperar resultado o timeout | | `accepted` | Se recibió el ID remoto | Consultar | | `unknown` | Hubo timeout sin resultado confirmado | Conciliar | | `failed` | El proveedor rechazó o terminó explícitamente | Aplicar política de fallo | | `complete` | La salida está guardada de forma duradera | Devolver el resultado existente | La diferencia entre `unknown` y `failed` es esencial. Una excepción de red aporta evidencia sobre la conexión del cliente, no necesariamente sobre el trabajo del proveedor. Adjunta la clave local a los metadatos del proveedor cuando la API ofrezca una referencia de cliente. Así, una consulta posterior o una solicitud de soporte tendrá un identificador estable. ## Concilia antes de reintentar Un worker de conciliación investiga una operación desconocida. La evidencia disponible depende del proveedor, pero el orden debe ser deliberado. 1. Comprueba si el intento original guardó un ID remoto antes de fallar el proceso. 2. Consulta por clave de idempotencia o referencia de cliente si existe esa función. 3. Busca en una lista acotada de trabajos por hora, modelo y huella de solicitud. 4. Inspecciona webhooks que puedan haber llegado después del timeout. 5. Compara eventos de facturación o uso si aparecen con suficiente rapidez. 6. Reintenta solo cuando puedas demostrar que no existe un trabajo o la idempotencia documentada haga seguro el reintento. Relacionar únicamente por tiempo y prompt puede producir falsos positivos. Usa varios atributos y envía las coincidencias inciertas a revisión. Si no existe consulta ni garantía de idempotencia, la política correcta puede ser esperar, aceptar la posible duplicación o pedir una decisión humana según el coste y el plazo. ## Separa los reintentos de transporte de los de operación Las bibliotecas HTTP suelen reintentar automáticamente los errores de red. Esto ayuda en lecturas seguras, pero es arriesgado para envíos con efectos secundarios. Desactiva los reintentos POST genéricos salvo que la operación esté protegida por una clave estable y el endpoint documente ese comportamiento. Usa dos contadores: * intentos de transporte para enviar la misma operación protegida; * intentos de generación para crear deliberadamente una salida de sustitución tras un fallo terminal o un rechazo de calidad. Representan costes distintos. El reintento de transporte debe converger en el mismo trabajo remoto. El de generación es un nuevo intento creativo facturable y necesita una identidad nueva, aunque siga relacionado con el trabajo de producción original. ## Gestiona workers concurrentes con un arrendamiento Los timeouts no son la única fuente de duplicados. Dos workers pueden elegir el mismo elemento o uno lento puede continuar después de vencer su bloqueo. Reclama el trabajo con un arrendamiento atómico que contenga propietario, hora de adquisición y vencimiento. Antes del envío, el worker confirma que conserva el arrendamiento y que no existe un trabajo remoto aceptado. Guarda el ID remoto con una transacción o actualización condicional que falle si otro worker ya avanzó la operación. Usa tokens de vallado cuando un worker antiguo todavía pueda escribir. Cada adquisición incrementa una versión y la base de datos solo acepta cambios de la versión más reciente, lo que impide que un proceso obsoleto sobrescriba un resultado nuevo. ## Haz que webhooks y consultas converjan Los trabajos de video son asíncronos, por lo que un webhook y una consulta pueden informar de la misma transición. Sus controladores también deben ser idempotentes. Deduplica eventos por ID cuando exista. Haz también condicionales las actualizaciones: un evento `processing` no debe mover un trabajo hacia atrás desde `complete`. Descargar dos veces la misma salida debe escribir en una clave temporal determinista, verificar el checksum y converger en un único objeto final. La ruta de finalización debe poder repetirse con seguridad: ```text recibir finalización buscar la operación por ID remoto copiar la salida a una clave determinista verificar el medio y el checksum registrar la URI duradera marcar la operación como completa si aún no lo está ``` Si cualquier paso falla, el siguiente controlador puede continuar sin generar otro video. ## Registra evidencia suficiente para auditar duplicados Conserva en cada intento las marcas de tiempo, el tipo de timeout, el hash, la clave de idempotencia, los headers de respuesta, el ID remoto y la decisión de reintento. Redacta credenciales y datos sensibles. Controla estas métricas: | Métrica | Qué revela | |---|---| | Envíos desconocidos | Ambigüedad de red o proveedor | | Conciliados sin reintento | Duplicados evitados correctamente | | Reintentos protegidos | Comportamiento idempotente bajo fallo | | Trabajos duplicados sospechosos | Riesgo financiero residual | | Checksum de salida duplicado | Resultado igual o repetido | | Tiempo en estado desconocido | Velocidad de recuperación | Alerta ante un aumento inusual de resultados desconocidos antes de subir límites. Una regresión de red combinada con reintentos agresivos puede multiplicar los costes. ## Encapsula el comportamiento del proveedor en un adaptador Una aplicación multimodelo debe exponer una interfaz interna de envío con indicadores de capacidad. El adaptador controla el schema del endpoint, la idempotencia, la consulta, la normalización de estados y la extracción de salida. [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=avoid-duplicate-video-jobs-api-timeout) puede reducir el trabajo de integración para equipos que usan texto, imagen y video en una plataforma compatible con OpenAI. Aun así, comprueba el comportamiento actual del modelo y endpoint exactos. La compatibilidad normaliza muchos patrones, pero no promete una idempotencia universal para trabajos asíncronos. Devuelve un resultado normalizado: aceptado con ID remoto, rechazo explícito o desconocido. No conviertas las excepciones de transporte en fallos del proveedor dentro del adaptador. ## Prueba deliberadamente los casos ambiguos La ruta correcta no demuestra seguridad ante duplicados. En preproducción, inyecta fallos antes de enviar, después de que salgan bytes, tras la aceptación, después de recibir la respuesta pero antes de guardar y durante la entrega del webhook. En cada caso, comprueba que una operación prevista produce como máximo un trabajo remoto si el proveedor admite idempotencia. Si no la admite, comprueba que entra en `unknown`, pausa el reenvío automático y ofrece evidencia suficiente para la política elegida. Prueba también workers simultáneos, arrendamientos vencidos, webhooks retrasados o repetidos, reinicios y reutilización de una clave antigua con parámetros cambiados. Estas pruebas cuestan menos que descubrir generaciones duplicadas en la factura. ## En resumen Evita trabajos de video duplicados dando a cada salida prevista una clave persistente y separando esa operación de sus intentos HTTP. Guarda la intención antes de enviar, usa la idempotencia documentada y trata el timeout como un resultado desconocido que debe conciliarse. Con arrendamientos, cambios condicionales, controladores idempotentes y registros duraderos, los reintentos se convierten en recuperación controlada en lugar de compras repetidas accidentales. ## FAQ ### ¿Un timeout HTTP significa que la API de video no creó un trabajo? No. El proveedor puede haber aceptado la solicitud y creado el trabajo aunque el cliente no recibiera la respuesta. Trata el resultado como desconocido hasta conciliarlo. ### ¿Qué debe representar una clave de idempotencia? Debe representar un único efecto previsto, como una combinación de producto, versión de plantilla, locale, relación de aspecto y variante. Reutilízala en los reintentos de esa operación y crea una nueva para una salida realmente nueva. ### ¿Puede una restricción única de base de datos evitar todos los duplicados? Evita operaciones locales duplicadas, pero no puede impedir por sí sola que el proveedor acepte dos solicitudes. Combínala con la idempotencia del proveedor o con un proceso de conciliación. ### ¿Debe el cliente reintentar automáticamente todos los timeouts? No. Los reintentos automáticos solo son seguros cuando la solicitud es idempotente o puede determinarse el resultado del proveedor. En caso contrario, coloca el trabajo en estado desconocido y concílialo primero. ### ¿Cuánto tiempo deben conservarse los registros de idempotencia? Consérvalos al menos durante la ventana de reintentos, la ventana de consulta del proveedor, el periodo de disputas de facturación y las necesidades de auditoría. Ajusta el periodo al comportamiento documentado y al riesgo empresarial. ### ¿Una API compatible con OpenAI garantiza la misma idempotencia en todos los modelos de video? No. La compatibilidad puede normalizar el transporte, pero la creación asíncrona de trabajos y la idempotencia pueden seguir siendo específicas del modelo o proveedor. Comprueba la documentación actual del endpoint.