API Keys, Authentication and Credits: A Complete Guide

Getting a Key

Open the API dashboard, choose a plan to activate API access, and generate a key from the API Keys tab. API access is gated behind an active plan, so the key and the credit allotment arrive together — there is no separate provisioning step to wait on.

Every request needs that key in a header. The API accepts two formats, and they are equivalent — use whichever fits your HTTP client:

Authorization: Bearer <API_KEY>
# or
x-api-key: <API_KEY>

The Authorization: Bearer form is conventional and works well with most SDKs and HTTP libraries that already have first-class support for bearer tokens. The x-api-key form is convenient when a framework or gateway already reserves the Authorization header for its own session auth, which is common if you are calling from inside an application that authenticates its own users.

Which Endpoints Actually Cost Anything

This table is the entire cost model. Two rows cost credits and six do not, which has real design implications: the operation you will perform most often — polling job status — is free, so your polling frequency is a UX and compute decision rather than a budget decision.

A worked example makes the arithmetic concrete. An eight-photo listing rendered into one merged reel costs nine credits: eight video generations plus one reel merge. Uploading the eight photos, polling each of the nine jobs a dozen times, listing your recent jobs, and checking your balance all cost nothing. The number is nine regardless of how chatty your integration is.

When Credits Are Charged — and Refunded

Both paid endpoints are asynchronous, and the charge happens at acceptance rather than at completion. The create response tells you so explicitly:

POST /api/v1/videos

{ "jobId": "uuid", "status": "pending", "creditsCharged": 1 }

That creditsCharged field is the authoritative record of what this call cost you, and the moment you receive it you have spent money on a job whose only identifier is in that response body. Persist it immediately. A process that crashes between the API call and the database write has paid for a render it can never retrieve.

If generation fails, the credit is refunded to your account automatically. No support ticket, no manual reconciliation. That is a meaningful simplification for anyone metering usage downstream, because it means a failed render never needs a compensating adjustment on a customer's invoice:

GET /api/v1/videos/:jobId

{
  "job": {
    "status": "completed",
    "video_url": "https://...",
    "download_url": "https://...?download",
    "credit_cost": 1
  }
}

Monitoring the Balance

The balance endpoint is free, which means there is no reason not to poll it on a schedule and store the result somewhere your alerting can see:

GET /api/v1/credits

# Returns total, used, and remaining for the account.

The failure mode to design against is not running out of credits — it is running out mid-batch. A twenty-photo listing that exhausts the pool at photo fourteen leaves you with fourteen orphaned clips, no reel, and a customer looking at a half-finished job. The fix is a preflight check: before starting a listing, confirm the remaining balance covers every clip plus the merge, and queue the listing rather than starting it if it does not.

Key Management Practices

Because a revoked key returns 401 immediately rather than failing gradually, rotation is safe but has to be sequenced correctly. These four decisions cover nearly every operational problem teams hit.

The client-side storage warning is worth repeating because the consequence is unusual here. A leaked key does not just expose data — it lets a stranger spend your credit balance. Every call to the video endpoint from a stolen key is a real charge against your account, so keys must stay server-side without exception.

Per-Customer Accounting Rules

If you are reselling video inside your own product, the pooled credit model means all tenant boundaries are yours to enforce. These seven rules are the ones that keep a metered feature reconcilable.

The job listing endpoints help here as a reconciliation backstop. Because GET /api/v1/videos and GET /api/v1/reels are free and return this key's jobs newest first, you can periodically compare what the API believes you created against what your own database recorded — and catch any job you paid for but failed to persist.