Getting started

Authentication

Authenticate every request with a secret API key sent as a Bearer token.

The Voiser API uses API keys. Send your key in the Authorization header of every request:

Authorization: Bearer vs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
curl https://api.34.181.188.80.sslip.io/v2/account \
  -H "Authorization: Bearer $VOISER_API_KEY"

Requests without a valid key fail with 401 (auth_required or auth_api_key_invalid).

Creating a key

  1. Sign in to the studio and switch to the account (personal or team) the key should belong to.
  2. Open Settings → API keys and select Create key. Give it a name you will recognise later, such as production-backend.
  3. Copy the key. It is shown only once; Voiser stores only a hash of it.
Who can manage keys

Creating and revoking keys requires the admin or owner role on the account. An account can have up to 20 active keys.

Keys look like vs_ followed by 40 letters and digits. Keys issued by the previous voiser.ai API keep working without any change.

How keys act

  • A key belongs to an account. Jobs, files and credit usage created with the key belong to that account and show up in the studio.
  • Requests run on behalf of the member who created the key. If that member leaves the account, or the account is deleted, the key stops working.
  • The same key works for v1 and v2.
  • Each key has its own rate limits and its own webhook signing secret.

Keeping keys safe

Never expose a key in a browser or app

Anyone with your key can spend your credits. Call the API from your own server, keep the key in an environment variable or a secret manager, and never commit it to source control or ship it inside a web page or mobile app.

  • Use separate keys per environment and per service, so you can revoke one without touching the others.
  • Rotate a key by creating a new one, deploying it, and then revoking the old one in Settings → API keys. Revocation takes effect immediately.
  • If a key leaks, revoke it right away.

Authentication errors

StatusCodeMeaning
401auth_requiredNo Authorization header, or it is not a Bearer token.
401auth_api_key_invalidThe key is wrong, revoked, or its creator no longer has access to the account.
403account_role_requiredThe key's creator does not have the role this endpoint needs.
403auth_forbiddenThe key cannot access this resource.

See Errors for the error format.