Authentication

API Keys

Send the workspace API key as a bearer token.

Authorization: Bearer vt_live_...

Keys are scoped to one organization.

The organization must have an active paid plan.

Headers

Authorization: Bearer vt_live_...
Content-Type: application/json
Idempotency-Key: optional-retry-key

Use an Idempotency-Key header for paid generation retries.

You can also pass idempotency_key in the JSON body when the endpoint supports it.

Credits

Credits are priced by the same server-side rules used in the app.

Paid endpoints deduct credits before queueing work.

If the workspace does not have enough credits, the API returns 402 insufficient_credits and no job is queued.

If queueing fails after a deduction, credits are returned before the API responds with an error.

Insufficient Credits

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits for this request.",
    "retryable": false,
    "context": {
      "credits_required": 1200,
      "credits_available": 500
    }
  }
}

Scopes

API keys are scoped to one organization and can only see resources owned by that organization.

Use generations:read for assets, status checks, reference lists, and editor reads.

Use generations:write for generation, uploads, reference creation, and editor changes.

Keys with only generations:write can also poll the resources they create.

Idempotency

Use one idempotency key per paid action.

If a network failure happens, retry the same request with the same key.

A completed matching request returns the original response.

The same key with a different payload returns 409 idempotency_conflict.