API Documentation

Every request must include your API key as a Bearer token:

Authorization: Bearer zpk_live_xxxxxxxx...

A key is shown in full only once, at creation — store it somewhere safe.

From a terminal — run zooop login (ZOOOP CLI). It opens the browser, you check the code and approve, and the CLI receives a key bound to the account and project you picked. These keys show a CLI badge on the API Keys page and can be revoked there like any other. See CLI sign-in.

Or create a key yourself. Personal and team keys are created in different places:

• Personal keys bill against your personal credit balance. Create them on the API Keys page (user settings → API Keys).
• Team keys bill against the team’s shared balance. They are created separately, inside the team admin panel — open Your teams, pick a team, and go to its API Keys tab. (Requires owner/admin role.)

Key properties — each key is bound to a project and can carry an optional expiry and a daily credit cap. Call GET /me to inspect a key’s remaining quota and rate limits.

Requests without a valid key return 401 (missing_token, invalid_token, user_not_found). A banned account, a key whose project was deleted, or a team key whose team is gone returns 403 (account_banned, token_project_unbound, team_unavailable).

From a terminal, the ZOOOP CLI does all of this in two commands: npx zooop login, then zooop run. To call the API from your own code:

1. Get an API key and export it as ZOOOP_API_KEY — a personal key, or a team key from your team admin panel (see Authentication).
2. Pick a model — call GET /api/public/v1/models to discover interfaceId / versionId pairs, or pass an aiTool / template slug instead.
3. Submit the task, then poll until it finishes and read outputs[0].url.

The snippet on the right runs the full submit → poll → read-result loop.

zooop login starts a login, shows a short code (like QBKF-7XRM) and opens zooop.ai/cli/login. Check that the browser shows the same code, pick whose credits to use and which project results go to, and click Authorize. The CLI then receives an ordinary API key, so everything on this page applies to it.

On a server, over SSH or in an agent sandbox without a browser, open zooop.ai/cli/login on any device and type the code. In CI, skip the login and set ZOOOP_API_KEY instead — it always takes precedence.

Logging in again from the same machine replaces that machine’s previous CLI key, so repeated logins don’t pile up. zooop logout revokes the key on the server and deletes the local copy.

Every command with examples: the ZOOOP CLI guide. The three endpoints below are what the CLI calls. They follow the OAuth 2.0 device authorization grant (RFC 8628), so you can use them to sign in your own tool the same way.

Rate limit: 10 requests/min per client IP. The approval page also shows the country the request came from, so a user can spot a code someone else forwarded to them.

Rate limit: 60 requests/min per client IP. Until the user decides, every poll returns 400 with one of these codes:

Authorization required. Rate limit: 120 requests/min per key. A key can only revoke itself; it stops working on every endpoint at once.

Authorization required. Rate limit: 60 requests/min per key.

Idempotency — pass an Idempotency-Key header (1–256 chars). Repeats within 24 hours return the original task instead of creating a new one.

Billing — credits are charged when the task is created and refunded automatically if it fails or is cancelled. A template with a per-resolution price table charges the listed price for the resolution the task runs at (never less than the model’s own price); POST /quote returns the exact figure.

Errors: 400 invalid_payload / invalid_idempotency_key / missing_required_params / param_out_of_domain / param_conflict / foreign_url, 402 arrears / token_daily_cap_exceeded, 403 model_not_public, 404 unknown_model / unknown_ai_tool / unknown_template, 422 moderation_blocked and media checks, 429 rate_limited / token_daily_cap_reached, team-key errors (see Errors & rate limits).

Authorization required. No fixed rate limit — poll every few seconds.

Scope — the key owner’s tasks in the key’s scope: team tasks for a team key, personal tasks for a personal key, including ones made in the web app. Any other task id returns 404 unknown_task.

Authorization required. Rate limit: 120 requests/min per key.

Scope — the key owner’s tasks in the project the key is bound to: team tasks for a team key, personal tasks for a personal key. That includes tasks made in the web app in that project and by other keys bound to it.

Errors: 400 invalid_status / invalid_page / invalid_page_size.

Authorization required. Rate limit: 60 requests/min per key. Same ownership rule as GET /tasks/{id}.

Only a queued task can be cancelled. Once the provider has it (running), the generation can’t be stopped and is billed normally. Repeating the call on a cancelled task returns 200 again with refundedCredits: 0.

Credits go back to the wallet that paid: the team’s for a team task, yours otherwise.

Errors: 404 unknown_task, 409 cancel_too_late (already running), 409 task_already_finished (already succeeded or failed). Both 409s carry error.taskStatus.

Authorization required. Rate limit: 30 requests/min per key.

Uploads are checked against the content policy: images right away (451 moderation_blocked with labels), videos in the background (202, then poll). When video checks are switched off, a video comes back ready directly. Audio is not checked.

Errors: 400 invalid_payload, 402 arrears, 413 file_too_large, 451 moderation_blocked, 429 rate_limited, 502 storage_upload_failed, 503 moderation_unavailable.

Authorization required. Rate limit: 120 requests/min per key. Scoped to your key (others’ uploads return 404 unknown_upload).

Authorization required. No fixed rate limit. Both type and subtype are required query params: a missing one returns 400 missing_category, an unknown pair 400 unknown_category; both carry a validCategories list.

Authorization required. Rate limit: 120 requests/min per key. Errors: 400 invalid_type.

Authorization required. Rate limit: 120 requests/min per key. Errors: 404 unknown_ai_tool.

Authorization required. Rate limit: 120 requests/min per key. Errors: 400 invalid_type.

Every approved, live template is listed — official and community alike. Running a community template attributes its creator exactly as the website does.

Authorization required. Rate limit: 120 requests/min per key. Errors: 404 unknown_template (unknown, unpublished or retired).

Authorization required. Rate limit: 120 requests/min per key. The quote equals what POST /tasks charges for the same body, as long as the input media don’t change. Errors: 400 invalid_payload / missing_required_params / param_out_of_domain, 403 model_not_public, 404 unknown_model / unknown_ai_tool / unknown_template, 422 media checks, 503 pricing_misconfigured.

Authorization required. Rate limit: 10 requests/min per key (vision is expensive). Charges 1 credit up front, refunded on failure.

Errors: 400 invalid_payload, 402 insufficient_credits / arrears, 422 policy_violation, 429 token_daily_cap_reached / rate_limited / upstream_rate_limited, 500 describe_failed, 503 vision_unavailable, plus the team-key errors.

Authorization required. Rate limit: 120 requests/min per key. Team keys return team instead of user (the creator’s personal balance is never exposed).