Skip to main content
Send an API key on every request:
Keep the key in the environment variable RASK_API_KEY. A request with any of the query parameters access_token, api_key, token is refused with 400 token_in_query, and parameter names the one it found. This happens even when the Authorization header holds a valid key. The key in the URL stays valid, so revoke it in Settings if the URL was logged or shared. API v3 does not accept web sessions, and API v2 credentials answer 401 invalid_token.

​
Get a key

Keys are created in the web app, under Settings -> API keys (open it). There is no API for it. You choose:
  • A name and a workspace. The key works in that workspace only.
  • Access. One of three presets, or your own set of scopes.
  • Spending. Whether the key may spend credits, with its monthly caps.
  • Expiry. 30 days, 90 days or 1 year (the default). A key that cannot spend may also never expire. A key that can spend must expire.
The key is shown once. Rask stores only its hash and cannot show it again, so a lost key means a new key. A workspace holds at most 100 active keys, and one person at most 25 per workspace.

​
What a key is

Each key is bound to one workspace and acts as one user, the person who created it. The workspace owner is the payer: all work is charged to the owner and the owner’s plan applies. All workspaces of one owner share one set of credit pools. No request takes a workspace id. An id outside the key’s workspace answers 404, as if it did not exist, never 403. What you can change later: the name (only the key’s own user can) and the caps. Scopes, workspace, acting user and expiry are fixed, so a key that lacks a scope needs a replacement. Requests that spend credits or delete data always see the key’s current state. Other requests can take a minute or two to see a revocation, or a change to the key, its user, its workspace or the payer’s plan. A key is raskai_live_key_ and 49 base62 characters. GET /v3/me shows it masked, in auth.display.

​
Scopes

Scopes are resource:action. Every operation lists the ones it needs in its reference page, and the operation table has them all. Two rules expand what a key holds: X:write implies X:read, and every *:write implies jobs:read. Estimates need the action’s scope but not credits:spend. GET /v3/languages works with any valid key. jobs:read reads every job the key started. A job that another key started also needs the scope that reads what the job works on: media:read for media_import, voices:read for voice_clone, transcripts:read for translation and segment_generation, and projects:read for the rest. Without it, the job answers 404 job_not_found and is left out of lists. A run that orders lip-sync or on-screen adds those scopes for that request, as x-rask-operation.conditional says on createLocalization, createProject and resumeJob.

​
Spend caps

A key can carry two monthly caps, counted per UTC month: one on minutes and one on project credits. Free lip-sync minutes (lipsync_free_minutes) count against neither. A key that can spend gets a minutes cap of 120 minutes unless you set another; “no limit” is an explicit choice. The project-credit cap is off unless you set one. The workspace owner can change the caps of any key in the workspace, and a member cannot raise a cap the owner set. Members’ spending keys follow the owner’s policy: whether members may create them at all, and a highest minutes cap that starts at 300 minutes. A member’s key gets at most that cap by default, and a member cannot set a minutes cap above it or “no limit”. The cap is checked exactly at every spend. A request above it answers 403 token_spend_limit_exceeded with credit_type, limit_minutes, spent_minutes, required_minutes (or the _projects fields) and resets_at. Spending that is already promised counts too: a stored auto-dub, an on-screen auto-start and the remaining stages of a run. A refunded charge stops counting. To see where a key stands, read auth in GET /v3/me, or spend_limit in any estimate.

​
What each 401 means

A 401 is about the key itself. Do not retry it unchanged. Many failed authentications from one address answer 429 rate_limited with the policy auth-fail-ip, and until Retry-After passes, even a valid key from that address can be refused. Fix the key, then wait Retry-After seconds. 503 auth_unavailable means the check itself failed: wait Retry-After seconds and retry.

​
What each 403 means

A 403 means the key is fine and this request is refused. Branch on code. feature_not_in_plan with feature: api_access on every call means the plan has no API access at all.

​
Trying requests on this site

The playground on the reference pages calls the API directly, with the key you paste. It may call only GET and estimate operations, so nothing it does can spend. Use a read-only key. Estimates need the action’s write scope, so a read-only key gets 403 insufficient_scope on them; to try an estimate, use a key without credits:spend.