GloopAPI integration guide
Asynchronous tasks and idempotency
Recover tasks and handle unknown submissions.
An idempotency key represents one business operation in your application. Persist the request body, API key identity, and request key before sending. Replays must use the same key and the same normalized input. Changing the request with the same key causes a conflict; using a different key creates a new billable operation.
Quotes and creation
For persistent images and videos, first read the capability catalog, then upload or import inputs, obtain a quote, and explicitly confirm creation. Image and video quotes are valid for 60 seconds; tool quotes are valid for 300 seconds. The server's expires_at is the actual deadline. Quotes do not execute tasks or incur charges. For a new call that has not been submitted, obtain a new quote if the quote expires or inputs/configuration change, and verify the new cost before creation. Once a request has been submitted but its outcome is unknown, do not modify the original quote or request.
Image quotes do not lock input assets; creation validates them again. Videos only allow a complete preset and managed frames that match the current mode. Persistent videos explicitly submit retention: "persistent"; ordinary videos continue to follow their own URL input contract.
Decisions for unknown submissions
Once you have a task ID, query only the original task. If a request times out before you receive an ID, use the recovery endpoint with the original request key for persistent images and videos. If an original task record exists, continue observing it. If its status is unknown, submission_unknown, submission_state_unknown, billing_review, or awaiting review, do not treat it as failed or refunded, and do not generate again with a different key.
For tools, use the original API key to query a known run_id. If the creation response is lost and there is no run_id, replay POST /v1/tool-runs using the original API key, original Idempotency-Key, and original complete request body, retaining the original quote_id/version/input/max_cost_usd. An accepted run directly restores its original record without depending on a new quote or current feature switches, and without executing the task again. History is sorted by created_at descending, then id descending; next_cursor must be passed back unchanged. Pagination is not a snapshot; refresh the first page to see newly added records that sort before the cursor. Audio cloning has no equivalent request-key recovery endpoint. Preserve evidence and investigate unknown submissions; do not apply the image recovery path to them.
Three independent states
Evaluate generation success, billing settlement, and storage readiness separately. Images may partially succeed, tools may succeed while final usage remains unconfirmed, and videos may generate successfully but fail to save. Background workers continue processing persistent tasks; closing the browser or stopping client polling does not cancel them.
Cancellation is only a request: it may be unsupported or too late to prevent success. Continue observing the final status and billing. Storage retry/archive-retry only saves the original result; it does not generate new content. Task deletion requires a terminal state and finalized billing, and idempotency and charge evidence remain after deletion.
After retrieving a result, check that storage is ready before requesting a short-lived file download URL. Expired temporary source URLs may make archival unrecoverable; do not hide a saving error on the original task by generating again. See Billing and Error handling.