認証とリクエスト規約
プログラムが使う API キー、呼び出し先、リクエストヘッダーです。
API Key
Bearer 認証です。すべてのリクエストに付与します：
キーの先頭には地域が入っています（例：sk-row-...）。row はそのキーの地域で、どの API に送るかを決めます。row は https://api.beatra.cn/v1 です。地域が違うリクエストは拒否されます。キーはコンソール
console.beatra.cn の 開発者向け → API キー で作成します。secret が表示されるのは作成時の一度だけです。ローテーション時は、新しい key を作成 → デプロイを切り替え → 古い key を失効、の順で行います（新旧の key は並行して有効にできます）。
コンソールへのログインは、人がアカウントを管理するためのものです。API キーはプログラム、サービス、バックグラウンドの処理に使います。コンソールにログインした状態を、自動で動くプログラムに入れないでください。
Base URL
リクエストヘッダー
| Header | 必須 | 説明 |
|---|---|---|
Authorization | はい | Bearer <api_key> |
Content-Type | はい | application/json（ファイルアップロードを除く） |
Idempotency-Key | 強く推奨 | 作成系の POST に付与。リトライでは同じ key を使用。重複排除は永続的で、同じ key は常に同じタスクに解決されます |
X-Request-Id | 任意 | レスポンスにそのままエコーバック。トラブルシューティング時に最速の検索キー |
冪等性のルール
- 同じ論理操作のリトライ → 同一の
Idempotency-Keyを使う - ユーザーの意図が変わった → 新しい key に切り替える
- 同じ key で body が異なる →
409 idempotency_conflict
レート制限のレスポンスヘッダーと 429 の処理はレート制限を参照してください。
MCP ホストの接続（OAuth）
標準 MCP OAuth に対応したホストに https://mcp.beatra.cn/mcp を追加します。ホストが認証先を見つけて登録し、ブラウザーで Beatra を開きます。ログイン後、接続先を確認して 許可 を選んでください。API キーやトークンをコピーする必要はありません。
接続したアプリは、Beatra のクレジットを使った画像・動画・音楽・音声の生成、公開ソーシャルデータの取得、音声やアバターの管理、タスクの表示とキャンセル、作品の保存と閲覧、残高とクレジット履歴の閲覧ができます。
OAuth に対応したホストはバックグラウンドで認証を更新します。1 年間使われなかった場合は再ログインしてください。ヘッドレス接続コマンドによる接続は、解除されるか、1 年間使われなくなるまで有効です。
コンソールの デバイス → 接続済みアプリ で接続先、初回接続、最終使用を確認し、接続を解除できます。更新用の認証情報の再利用が確認されると、その認可は失効し、このページに理由が表示されます。ホストから再接続してください。
Beatra Skill を使うエージェントは Skill のログイン手順を使います。クイックスタートを参照してください。
最終更新