Skip to content

Authentication ​

Every request to the API carries an API key as a bearer token:

http
Authorization: Bearer xv_...

The OpenAI SDKs send this header for you when you pass api_key. The header is the only way to authenticate. Query parameters, cookies and signed URLs are not accepted. That includes the realtime WebSocket, because a key in a URL ends up in proxy logs and browser history.

Keys belong to a project ​

text
Organization   your account: members, billing and limits
  └─ Project   one application or workload
       └─ API key

Each key belongs to one project. Usage, request logs and spending are attributed to that project automatically, so there is nothing extra to send. Use a separate project for each application, so you can tell later which workload spent what.

Rate limits and credit are shared by the whole organization, not split per project. See Rate limits.

Key format ​

Keys start with xv_, followed by 49 letters and digits. The last six characters are a checksum, so a mistyped or truncated key is rejected with invalid_api_key straight away. The dashboard shows each key by its last four characters, xv_…a1b2, so you can match it against the end of the value in your environment.

Keys issued before the xv_ format start with sk_live_ or sk_test_. They keep working and are billed like any other key.

Every key is billed for what it uses. There is no free test mode. To keep development traffic apart from production, give it its own project.

Managing keys ​

Create, rotate and revoke keys under Projects → your project → API keys in the dashboard.

  • The secret is shown once, when the key is created. We cannot show it to you again, so a lost key is replaced, not recovered.
  • Expiry is optional. A key past its expiry fails with api_key_expired.
  • Revoking is immediate. The next request with the key fails with api_key_revoked.
  • Rotating issues a new secret with the same name and retires the old one. You choose when the old key stops working: immediately, or after up to 7 days so your deploy can switch to the new secret with no downtime. If a key may have leaked, stop it immediately.

Keep keys on your server ​

Never put a key in a browser bundle, a mobile app or a public repository. Anyone who has it can spend your balance. For a browser or mobile client, send the audio to your own server and call xVoice from there.

Check a key ​

GET /v1/me tells you what a key belongs to. It costs nothing and does not count against your rate limits, which makes it a good deploy-time check.

bash
curl https://api.xvoice.dev/v1/me \
  -H "Authorization: Bearer $XVOICE_API_KEY"
json
{
  "organization_id": "org_01J8...",
  "project_id": "proj_01J8...",
  "api_key_id": "key_01J8..."
}

Errors ​

CodeStatusMeaning
missing_api_key401No Authorization header arrived
invalid_api_key401The key does not exist or is mistyped
api_key_revoked401The key was revoked
api_key_expired401The key is past its expiry date
organization_suspended403The key is valid, but API access for the organization is suspended. Contact support

xVoice is a product of Stochastic Inc.