API and MCP docs

Free API access is a separate cloud feature from the browser tool. It provides 500 credits per UTC month without a card after you sign in with a Google-verified @gmail.com account and pass Turnstile, subject to a $20 monthly free compute budget.

Create an API key from the account settings page after activation. All keys on the account share the same credit pool, rate limits, and unfinished-job limits. When the free compute budget is exhausted, new free jobs pause until the displayed reset time; paid Developer jobs and browser-local compression continue separately.

Send a multipart request with a GIF file and an options field containing JSON. Target mode uses decimal bytes in targetBytes; do not send separate mode or targetBytes form fields.

Every create request must include an account-scoped Idempotency-Key. Reusing the same key with the same file and options returns the original job without reserving credits again.

The create response contains a top-level id. Save it as JOB_ID and use it in the status URL; it is not nested inside a job property. The create response alone does not contain a download link. Query the status endpoint even when creation replays an already completed job. Replace YOUR_JOB_ID in the example with that id, then copy result.downloadUrl from a succeeded response into DOWNLOAD_URL before running the download command.

While status is queued or processing, result is null. When status is succeeded, read result.downloadUrl and result.expiresInSeconds. On failed or canceled, stop polling and inspect error.code and error.message rather than retrying a download.

Poll every few seconds and stay within the account read limit. A new status query can refresh an expired download link while the file is still accessible. Links last up to 15 minutes and never extend file access past 24 hours. Polling, downloading and exact idempotent replay do not spend credits.

JSON create requests use sourceUrl and options. The server fetches only HTTPS URLs, validates each redirect, blocks private networks, and enforces the same file-size limits as uploads.

If a website blocks browser CORS, local URL import may fail. REST URL import is still a cloud job and uses your API key, credits, rate limits, and retention rules.

GET /api/v1/usage returns { usage }. The usage object includes active pool, limit, used, reserved, remaining, resetAt, windowStart, and windowEnd. Free create requests are limited to 10 rpm, Developer create requests to 60 rpm, and status or usage reads to 120 rpm per account.

Free API windows reset by UTC calendar month. Developer windows reset monthly at the subscription anchor, including annual subscriptions. Credits do not roll over. Free accounts can have 2 unfinished jobs, Developer accounts can have 20, and the free queue can hold 100 jobs. A free job waiting more than 10 minutes is terminated and releases its reservation.

The MCP endpoint is Streamable HTTP at /api/mcp. It exposes compress_gif, get_compression, and get_usage and uses the same API key as REST.

MCP accepts remote HTTPS GIF URLs. Local files should be uploaded through REST; do not pass server-local paths or large Base64 payloads to the MCP tool.

Call compress_gif with sourceUrl, an optional options object and a required idempotencyKey. Then pass the returned id to get_compression. The adapter wraps the REST response in structuredContent.data; successful tool transport does not mean the compression job has finished. Use get_usage with an empty object to check your balance.

Inputs up to 5MB cost 1 credit in quality or size mode and 2 credits in target mode. Inputs over 5MB and up to 20MB cost 2 credits, or 4 credits in target mode. Each processing attempt has a 60-second budget and at most 8 encoded candidates.

Validation failures, system failures, and timeouts do not spend user credits. A valid result that misses the requested target still spends the disclosed quote because compute work completed; the job marks targetMet: false.

The job’s credits and cost.credits fields show the quoted cost, not proof of a completed debit. Credits are reserved when a job is accepted, settled on success and released on failure. Check /api/v1/usage for the current used, reserved and remaining balance.

Common error codes include API_KEY_REQUIRED, API_KEY_INVALID, INSUFFICIENT_CREDITS, FREE_API_NOT_ACTIVE, IDEMPOTENCY_CONFLICT, INPUT_TOO_LARGE, INVALID_GIF, RATE_LIMITED, TOO_MANY_OUTSTANDING_TASKS, and FREE_COMPUTE_BUDGET_EXHAUSTED.

401 covers missing or invalid API keys. 402 is only for exhausted user credits. 403 covers inactive free API access. 409 covers idempotency conflicts. 413 covers cloud input size limits. 422 covers invalid GIF data or options. 429 covers create/read rate limits and unfinished-job caps. 503 covers temporary queue pressure or FREE_COMPUTE_BUDGET_EXHAUSTED; respect Retry-After when present.

Local browser compression and cloud API jobs have different data flows. Choose the browser tool when the GIF needs to stay on your device; use REST or MCP when a remote workflow needs to process it.

The browser tool does not upload your GIF. Importing a URL contacts the site hosting that image directly. API and MCP requests upload a file or ask our service to fetch a public HTTPS URL. Cloudflare hosts the application, database and file storage. Access to API input and output files expires after 24 hours; download links last up to 15 minutes. Background cleanup removes expired files, so physical deletion may happen later. We record technical usage events such as compression success or failure, input and output size, target status and downloads in Cloudflare service logs to measure reliability and usage. These events exclude filenames, source URLs and file contents. Cloudflare also processes request data to deliver and protect the service. Product event logs are retained for up to 7 days.

Send Authorization: Bearer YOUR_API_KEY on create, status and usage requests. The API also accepts the x-api-key header. Account sign-in cookies are not a replacement for an API key. All keys belonging to one account share allowances and limits.

Keep the key in a server-side environment variable or your AI client’s protected configuration. Do not place it in a public webpage, repository or image URL. If a key is exposed, revoke it in API key settings and create a replacement. The free browser tool needs no API key.

mode accepts quality, size or target and defaults to quality. target requires a positive integer targetBytes, measured in decimal bytes: 100KB is 100000 and 1MB is 1000000. For multipart uploads, put these fields inside the JSON-encoded options field.

Optional colors accepts auto, 64, 128 or 256. lossyLevel accepts an integer from 0 to 200. width accepts an integer from 1 to 4096 and requests resizing; omit it to keep the original dimensions. No frame-dropping or format-conversion option is supported.

One request processes one GIF. Free API inputs are limited to 5MB and Developer inputs to 20MB. Both also require each edge to be at most 4096 pixels, at most 1,000 frames, and width × height × frame count at most 50,000,000. A short but very large animation can hit these safety limits before its byte-size limit.

Choose a new Idempotency-Key for each new file-and-options request and keep that key when retrying after an uncertain network response. Keys contain 1–128 printable, non-space ASCII characters. An identical replay returns the existing task; changing the input or options under the same key returns 409 IDEMPOTENCY_CONFLICT.

For 429 or temporary 503 responses, honor Retry-After when present and back off. A 402 credit shortage needs an allowance reset or a plan change; repeated requests will not fix it. A 503 FREE_COMPUTE_BUDGET_EXHAUSTED pauses new free jobs until the displayed reset, while paid jobs and the local browser tool remain separate.

A failed job remains the same failed job when its key is replayed. Check the cause first, then use a new key for a deliberate new attempt. Do not create new keys on every timeout: the first request may already have been accepted.