GloopAPI integration guide
Billing
Understand reservations, settlement, and file storage.
Model catalogs, public pricing summaries, and actual call billing provide different information. Before initiating a billable operation, verify the model or tool, inputs, and budget. A sufficient balance does not imply permission to call.
Reservation and settlement
Accepting a request may reserve an estimated quota amount. Once authoritative usage is available, settlement uses the frozen price and charges or refunds the difference. Usage-based video quotes are estimates, not promises of a maximum spend. Maximum tool reservations are calculated from input bounds and frozen rules, and creation checks the cost cap.
status=succeeded describes execution, while billing.status=reserved still means the charge is awaiting confirmation. A null final amount is not zero. Requests with unknown outcomes or conflicting usage retain reservations pending verification. Whether confirmed failures are refunded depends on the endpoint and usage evidence; there is no blanket promise that all failures are free.
For synchronous text, consult the platform's usage records for final consumption. For asynchronous tasks, inspect their billing status. Do not generate again to try to settle an old task.
Tool pricing capabilities
pricing.mode distinguishes flat constant per-call pricing, input pricing precomputed from inputs, and usage pricing based on final usage. schema_version only describes the rule format. For flat pricing, amount is the complete constant price, including zero; input/usage do not expose a misleading constant amount.
pricing.quote_required determines whether new calls need a quote. requires_usage indicates whether final settlement needs authoritative usage, including platform settlement constraints. Even a flat selling price may require a quote and final usage; make decisions using these two capability fields. When requires_usage=true, max_cost_usd must cover maximum_usd, and settlement waits for authoritative usage after success. Rules using input pricing without final usage requirements can settle at the input-based amount after quoting, without waiting for final usage.
metered_pricing only restricts new calls that require final usage. It does not restrict constant/input rules that need no final usage, or block queries of accepted runs, idempotent replays of original requests, or recovery of frozen billing. Quotes bind the key, tool version, normalized input, and pricing/source configuration. A quote_id supplied for a constant-price tool is always validated too. The lowest tier shown in the catalog does not mean the tool is free.
File retention and space
Ordinary API archived files expire according to the deployment's retention period in days. Persistent images/videos use reference protection for long-term retention; expires_at=0 means no fixed expiration. Storage occupancy and generation charges are accounted for separately; downloads are not guaranteed before ready.
Deleting a persistent task clears its results and releases removable references; background cleanup removes unshared files. Shared references, billing records, and idempotency records remain. Deleting files or failing to save does not automatically refund generation charges already incurred. Retrying a save requests available storage and reuses the original result without generating again.
Insufficient quota
For 403, 402, or quota errors, first check account and key limits. Persistent authentication lets valid keys with exhausted quota read history, but new tasks still require a budget. Continue querying the original record when an existing task needs settlement; do not resubmit with a different API key or request key. See Authentication and Asynchronous tasks and idempotency.