Guía de integración GloopAPI
Tareas asíncronas e idempotencia
Recupera tareas y gestiona envíos desconocidos.
Una clave de idempotencia representa una operación de negocio de tu aplicación. Guarda de forma persistente el cuerpo de la solicitud, la identidad de la clave de API y la clave de solicitud antes de enviarla. Al repetirla, usa la misma clave y la misma entrada normalizada. Cambiar la solicitud con la misma clave provoca un conflicto; cambiar la clave crea una nueva operación facturable.
Cotización y creación
Para imágenes y vídeos persistentes, consulta primero el catálogo de capacidades, sube o importa las entradas, obtén una cotización y confirma explícitamente la creación. Las cotizaciones de imágenes y vídeos duran 60 segundos; las de herramientas, 300 segundos. El plazo real lo indica expires_at del servidor. Cotizar no envía nada al servicio ni genera cargos. Para llamadas nuevas aún no enviadas, solicita otra cotización si caduca o cambian las entradas o la configuración y verifica el nuevo coste antes de crear. Si ya se envió la solicitud pero el resultado es desconocido, no modifiques la cotización ni la solicitud originales.
Las cotizaciones de imágenes no bloquean los recursos de entrada; se vuelven a validar al crear. Los vídeos solo permiten un preset completo y fotogramas gestionados compatibles con el modo actual. Los vídeos persistentes envían explícitamente retention: "persistent"; los vídeos ordinarios siguen su propio contrato de entradas por URL.
Decisiones ante un envío desconocido
Tras obtener un ID de tarea, consulta solo la tarea original. Si se agota el tiempo de espera sin recibir un ID, usa el endpoint de recuperación con la clave de solicitud original para imágenes y vídeos persistentes. Si existe un registro original, continúa observándolo. Si su estado es unknown, submission_unknown, submission_state_unknown, billing_review o pendiente de revisión, no lo trates como fallo ni reembolso y no generes de nuevo con otra clave.
Para herramientas con run_id, consulta con la clave de API original. Si se pierde la respuesta de creación y no hay run_id, repite POST /v1/tool-runs con la clave de API, el Idempotency-Key y el cuerpo completo originales, conservando quote_id/version/input/max_cost_usd. Una ejecución aceptada recupera directamente su registro original sin depender de otra cotización ni de los interruptores actuales y sin reenviarse al servicio. El historial se ordena por created_at descendente e id descendente; devuelve next_cursor sin cambios. La paginación no es una instantánea; actualiza la primera página para ver registros nuevos que se sitúen antes del cursor. La clonación de audio no dispone de un endpoint equivalente de recuperación por clave de solicitud. Conserva las pruebas e investiga los envíos desconocidos; no les apliques la ruta de recuperación de imágenes.
Tres estados independientes
Evalúa por separado el éxito de la generación, la liquidación de cargos y la preparación del almacenamiento. Las imágenes pueden tener éxito parcial; las herramientas pueden terminar con éxito sin uso final confirmado; un vídeo puede generarse pero no guardarse. Los procesos en segundo plano continúan las tareas persistentes; cerrar el navegador o detener las consultas del cliente no las cancela.
La cancelación es solo una solicitud: puede no ser compatible o llegar demasiado tarde. Sigue observando el estado final y la facturación. retry/archive-retry del almacenamiento solo guarda el resultado original; no genera contenido nuevo. Eliminar una tarea exige un estado terminal y facturación finalizada; después se conservan la idempotencia y las pruebas de cargos.
Tras obtener un resultado, comprueba que el almacenamiento esté ready antes de solicitar una URL de descarga temporal. Si caducan las URL temporales del servicio, el archivado puede ser irrecuperable. No ocultes un error de guardado de la tarea original generando de nuevo. Consulta Facturación y Gestión de errores.