Getting started
Authentication
How to authorize Clipia API requests — the API key, three header forms, live and test keys, key permissions, and how to store the key safely.
Every request to /v1/* is authorized with an API key. You create the key in the Developer Console; it is shown once, tied to your account, and charges credits from its balance. The recommended header is Authorization: Bearer clipia_live_….
Header forms
You can pass the key in any of three ways. The server accepts all of them, so pick whichever suits you.
curl https://api.clipia.ai/v1/account \
-H "Authorization: Bearer $CLIPIA_KEY"| Form | Header | Note |
|---|---|---|
| Bearer | Authorization: Bearer … | recommended; accepts only keys starting with clipia_ |
| Key | Authorization: Key … | alternative scheme; the word Key is case-insensitive |
| X-Api-Key | X-Api-Key: … | if you prefer a dedicated header |
Live and test keys
The key prefix sets the environment. You choose it when you create the key.
| Prefix | Environment | Behavior |
|---|---|---|
clipia_live_… | live | real generation, credits are charged |
clipia_test_… | sandbox | a ready-made sample right away; cost is calculated but not charged |
To move from the sandbox to production, swap the key — no code changes needed. See Sandbox for details.
Live keys need an active subscription
Generation with a clipia_live_ key is available while the account has an active subscription. Without one the request returns 402 with the code subscription_required: buying a credit pack doesn't open access. Test keys (clipia_test_) work without payment.
Getting a key
- Open the Developer Console and go to the API keys tab.
- Click Create key, give it a name (up to 100 characters) and choose the environment: live or test.
- Copy the key and the webhook signing secret. Both are shown only once.
An account can hold up to 20 active keys. Once the limit is reached, creating a key returns 400 with the message api_key_limit_reached — revoke a key you no longer need and create a new one.
The key is a server-side secret
Never put the key in a browser, mobile app, frontend bundle or public repository. Keep it in a secret manager or in server environment variables. If a key leaks, revoke it in the console and create a new one.
Account password and keys. Changing your password in the account settings does not touch API keys, but MCP OAuth connections stop working until your next sign-in to your Clipia account. Resetting the password through the "Forgot password" email link revokes every active key and OAuth connection: it is the access-recovery path, so create new keys and reconnect MCP clients afterwards. If you suspect a key has leaked, do not wait for a password change — revoke the key in the console.
Key permissions
Every key is created with the generate and read permissions. You don't pick permissions when creating a key.
| Permission | What it allows |
|---|---|
generate | creating generations (POST /v1/models/{model}) and AI Gateway LLM chat (POST /v1/chat/completions) |
read | reserved; it doesn't unlock anything extra today |
- You don't need a separate key for LLM chat:
generatecovers it. Media generation and LLM calls draw credits from the same balance. - Any valid key can read the status and result of its own generations.
- The model catalog (
GET /v1/models), cost estimation and balance (GET /v1/account) need no extra permissions. - A request without the required permission returns
403 insufficient_scope.
Key rejected
If the key is missing, wrong or revoked, the server returns 401 invalid_api_key. Check the environment prefix and that the key is sent in one of the three headers. The Bearer scheme accepts only keys that start with clipia_.
Quickstart
Run your first image generation with the Clipia API in four steps, from creating a key to fetching the result, with cURL, TypeScript and Python examples.
Sandbox
The Clipia API sandbox — a clipia_test_ key runs the full submit, status, result and webhook cycle without charging credits and returns a ready sample.