Guía de integración GloopAPI
Facturación
Comprende reservas, liquidación y almacenamiento.
Los catálogos de modelos, resúmenes públicos de precios y cargos reales de las llamadas son información distinta. Antes de iniciar una operación facturable, verifica el modelo o herramienta, las entradas y el presupuesto. Tener saldo suficiente no implica tener autorización.
Reserva y liquidación
Al aceptar una solicitud se puede reservar una cuota estimada. Al recibir el uso confirmado, se liquida con el precio congelado y se cobra o devuelve la diferencia. Las cotizaciones de vídeo por uso son estimaciones, no garantías de gasto máximo. La reserva máxima de herramientas se calcula con los límites de entrada y las reglas congeladas, y el límite de coste se comprueba al crear.
status=succeeded describe la ejecución; billing.status=reserved sigue indicando que el cargo espera confirmación. Un importe final nulo tampoco es cero. Los envíos desconocidos al servicio o los datos de uso contradictorios mantienen la reserva hasta su verificación. El reembolso de un fallo confirmado depende del endpoint y las pruebas de uso; no se garantiza que todos los fallos sean gratuitos.
En texto síncrono, consulta el consumo final en los registros de uso de la plataforma. En tareas asíncronas, consulta su estado de facturación. No generes de nuevo para intentar liquidar una tarea anterior.
Capacidades de precios de herramientas
pricing.mode distingue flat, precio constante por llamada; input, cálculo previo según entradas; y usage, precio según uso final. schema_version solo describe el formato de las reglas. En flat, amount es el precio constante completo, incluido cero; input/usage no exponen un importe constante que pueda inducir a error.
pricing.quote_required determina si las llamadas nuevas requieren cotización; requires_usage indica si la liquidación final requiere uso confirmado, incluidas las restricciones de liquidación de la plataforma. Incluso un precio de venta flat puede exigir cotización y uso final; decide con estos dos campos. Cuando requires_usage=true, max_cost_usd debe cubrir maximum_usd y la liquidación espera el uso confirmado tras el éxito. Las reglas input sin requisito de uso final pueden liquidarse por el importe de entrada tras cotizar, sin esperar el uso del servicio.
metered_pricing solo restringe nuevas llamadas que requieren uso final. No restringe reglas constantes o por entrada sin ese requisito ni bloquea consultas de ejecuciones aceptadas, repeticiones idempotentes de solicitudes originales o recuperación de cargos congelados. Las cotizaciones vinculan la clave, versión de herramienta, entrada normalizada y configuración de precios/origen. Si se envía quote_id para una herramienta de precio constante, también se valida siempre. El tramo más bajo mostrado en el catálogo no significa que la herramienta sea gratuita.
Retención de archivos y espacio
Los archivos ordinarios de API caducan según los días de retención del despliegue. Las imágenes y vídeos persistentes se conservan a largo plazo mediante protección por referencias; expires_at=0 indica que no hay caducidad fija. El espacio ocupado y los cargos de generación se contabilizan por separado; no se garantiza la descarga antes de ready.
Eliminar una tarea persistente vacía sus resultados y libera las referencias eliminables; la limpieza en segundo plano elimina archivos no compartidos. Se conservan las referencias compartidas, los registros de facturación y los de idempotencia. Eliminar archivos o fallar al guardarlos no reembolsa automáticamente los cargos de generación ya incurridos. Reintentar el guardado solicita espacio disponible y reutiliza el resultado original sin regenerarlo.
Cuota insuficiente
Ante 403, 402 o errores de cuota, comprueba primero los límites de cuenta y clave. La autenticación persistente permite leer el historial con claves válidas de cuota agotada, pero las nuevas tareas siguen necesitando presupuesto. Para liquidar una tarea anterior, sigue consultando el registro original; no reenvíes con otra clave de API o solicitud. Consulta Autenticación y Tareas asíncronas e idempotencia.