Skip to content

API Reference

Account and balance

GET /v1/account — the account's available balance in credits, plus the request count and credits spent by this key over the last 30 days.

Get the account's available balance in credits and usage statistics for the key.

Playground

Use a test key here

Paste a clipia_test_… key into the form below: it charges no credits and calls no models, and the response has the same shape. The form keeps the key in this browser, so never enter a live clipia_live_… key here: it is a server-side secret. See Sandbox.

GET
/v1/account

Authorization

headerAuthorizationBearer <token>

API key in the Authorization header with the Bearer scheme, the primary form. Generated clients add the Bearer prefix themselves, and in the playground the field already contains it: type the key after it. The playground keeps the key in this browser, so use a test key for trials:

Authorization: Bearer <CLIPIA_API_KEY>

The same key is also accepted with the Key scheme (Authorization: Key <key>, the word Key in any case) and in the separate X-Api-Key header (the apiKeyHeader scheme); use whichever form suits you, the server tells them apart. The key is created in the developer console (clipia.ai/developer, "API keys" tab) and shown only once. Format: clipia_live_… (live), clipia_test_… (sandbox).

Sandbox / test mode. A key with the clipia_test_… prefix works in the sandbox: submit charges no credits and starts no real generation; it instantly returns status: COMPLETED with a deterministic mock result (a fixed sample asset on media.clipia.ai). The cost field shows the estimated cost, but it is not charged. Webhooks arrive through the same signed mechanism (HMAC-SHA256). This mode is meant for debugging an integration before you switch to a live key.

Response Body

Account details.

application/json
  1. response
account_id?string

Account ID.

balance*
usage_30d*

Usage over the last 30 days.

curl -X GET "https://example.com/v1/account"
{  "account_id": "8f3a1c7e-2b4d-4e6f-9a01-23456789abcd",  "balance": {    "credits": 1840  },  "usage_30d": {    "requests": 512,    "credits_spent": 6120  }}

GET /v1/account returns the balance of the account the key belongs to and a summary for this key over the last 30 days. Any valid key works — no extra permission is needed.

GET/v1/account

Request

curl https://api.clipia.ai/v1/account \
  -H "Authorization: Bearer $CLIPIA_KEY"

Response 200

{
  "account_id": "8f3a1c7e-2b4d-4e6f-9a01-23456789abcd",
  "balance": { "credits": 1840 },
  "usage_30d": { "requests": 512, "credits_spent": 6120 }
}

Prop

Type

Credits

Generations and LLM chat draw credits from the balance of the account the key belongs to. You can top up on clipia.ai. If there aren't enough credits, submit returns 402 insufficient_credits; if the account has no active subscription, 402 subscription_required — see Errors. The balance in this response does not reflect that restriction.

Cost estimation

POST /v1/models/{model}/estimate — find out what a generation costs in credits before running it; no job is created and no credits are reserved.

Idempotency

The Idempotency-Key header makes retrying a generation submit safe — the same request returns the same request_id with no second job and no second charge.