Authentication & request conventions
API keys, base URL, and headers for agent clients.
API key
Bearer authentication; every request carries:
Keys embed their region in the prefix (sk-row-...). row is the region in that example, and it selects the API host (https://api.beatra.cn/v1 for row). A key used on the wrong host is rejected. Use the API host that
matches the key's region. Create keys in the console at
console.beatra.cn → Developer → API keys. The
secret is shown only once, at creation. To rotate: create a new key → switch your deployment → revoke the old key (old and new can be active in parallel).
Console sign-in is for humans managing the account. API keys are for agents, services, MCP adapters, and background jobs. Do not embed Console session cookies into agent runtimes.
Base URL
Request headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <api_key> |
Content-Type | Yes | application/json (except file uploads) |
Idempotency-Key | Strongly recommended | Send on create-style POST requests; reuse the same key on retries. Dedupe is durable: the same key always resolves to the same task |
X-Request-Id | Optional | Echoed back verbatim in the response; the fastest lookup key when troubleshooting |
Idempotency rules
- Retries of the same logical operation → the same
Idempotency-Key; - The user's intent changed → use a new key;
- Same key with a different body →
409 idempotency_conflict.
For rate-limit response headers and 429 handling, see Rate limits.
Connect an MCP host (OAuth)
Add https://mcp.beatra.cn/mcp to a host that supports standard MCP OAuth.
The host finds Beatra's sign-in on its own, registers itself, and opens a Beatra page in your browser.
Sign in, check where the connection goes, and select Allow. No API key, no token to copy.
What a connection can do:
- create images, video, music, and speech with your Beatra credits, and use the public social data tools;
- use and manage your voices (including cloned voices) and digital avatars;
- view and cancel tasks, and save and read your works;
- see your balance and credit history (including top-ups).
How long it lasts:
- Hosts that sign in with OAuth stay signed in: they renew in the background. If a host goes unused for a year, sign in again.
- Connections made with the headless connect command last until you disconnect them, or until they go unused for a year.
Manage connections in the console under Devices → Connected apps: see each app, where it connects, when it was first connected and last used, and disconnect it. If an app's sign-in is used from a copy, Beatra disconnects that app to protect your account and says so on that page; connect it again from the app.
Agents that run Beatra Skills sign in through the Skill instead; see Quickstart.
Last updated