Appearance
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 keyEach 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
| Code | Status | Meaning |
|---|---|---|
missing_api_key | 401 | No Authorization header arrived |
invalid_api_key | 401 | The key does not exist or is mistyped |
api_key_revoked | 401 | The key was revoked |
api_key_expired | 401 | The key is past its expiry date |
organization_suspended | 403 | The key is valid, but API access for the organization is suspended. Contact support |