Authentication and limits
Workspace-scoped Bearer keys, permissions, rate limits, and safe retries.
Send the key in the header on every current REST API request:
Create keys in Settings → Developer. Current production keys start with vb_live_. The credential selects the workspace; request bodies do not use a workspace ID to switch accounts.
Owners and admins create or revoke keys. The key creator must remain a member of the workspace. API access requires an active subscription or at least one completed historical top-up; generation also requires sufficient spendable credits.
Scopes
| Scope | Operations |
|---|---|
models:read | Model catalog |
files:write | Create upload URLs |
generations:read, generations:write | Read or create media and speech generations |
voices:read, voices:write | Preset catalog and custom voice operations |
personas:read, personas:write | Reusable persona operations |
agents:read, agents:write | Agent plans, execution, and review |
credits:read | Credit balance |
usage:read | API usage summary |
webhooks:read, webhooks:write | Webhook endpoints and deliveries |
Choose the smallest set your application needs. A missing required scope returns 403.
Rate and concurrency limits
The default request limit is 60 requests per minute per workspace. API keys in the same workspace share it. Media execution allows 5 concurrent media jobs per workspace; Agent execution allows one live run per workspace.
Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset when returned. On 429, respect Retry-After and use backoff. Queue work instead of repeatedly resubmitting it.
Idempotency
Creation and Agent action POST endpoints accept Idempotency-Key. Use 1–255 visible ASCII characters. The key is associated with the API key and request path/body.
- Same key and same request: replays a completed stored response, with
Idempotent-Replayed: true. - Same key while the request is processing:
409. - Same key with a changed path or body:
422.
Use a new key when you intentionally change the operation. Keep the body identical on retries; do not generate a fresh key after a network timeout if you are trying to avoid duplicate work.
Protect and rotate keys
Store keys on your server or in a secret manager. Create a replacement, update your application, and revoke the old key once the replacement works. Revocation stops future use immediately. Do not paste keys into browser code, public repositories, support messages, or screenshots.