接続と利用

どのベース URL を使えばよいですか？

https://api.beatapi.io を使用します。末尾に /v1 が必要かどうかは、クライアントが自動で付加するパスによって決まります。

クライアントの種類	ベース URL	自動で付加するパス
OpenAI SDK、OpenAI 互換ツール	`https://api.beatapi.io/v1`	`/chat/completions`
Anthropic SDK、Claude ネイティブツール	`https://api.beatapi.io`	`/v1/messages`
Gemini SDK、Gemini ネイティブツール	`https://api.beatapi.io`	`/v1beta/models/...`
HTTP の直接呼び出し	完全なパス。例 `https://api.beatapi.io/v1/chat/completions`	なし

設定を誤ると、すべてのリクエストで 404 が返ります。多くのクライアントは URL の誤りではなく「接続できない」と表示します。

すべてのリクエストが 404 になります

よくある原因から順に確認してください。

/v1 の重複または不足。 上の表を確認してください。/v1/v1/chat/completions は存在しません。
ベース URL 末尾のスラッシュ。 クライアントによっては、そのままパスを連結します。
公開 API に含まれないエンドポイント。 BeatAPI が公開するのは、テキスト、タスク、ファイル、利用状況、Webhook、リアルタイムなど、指定されたエンドポイントです。対象外では意図的に 404 を返します。/v1/embeddings、/v1/rerank、/v1/audio/* は提供していません。
存在しないモデル ID。 ID は大文字と小文字を区別し、ベンダーのプレフィックスは付けません。anthropic/claude-fable-5-1 ではなく claude-fable-5-1 を指定します。

401 missing_api_key または invalid_api_key

missing_api_key はキーが BeatAPI に届いていないことを意味します。invalid_api_key はキーが届いたものの、誤り、有効期限切れ、無効化、利用上限到達のいずれかであることを意味します。詳細はメッセージに表示されます。古いクライアントでは、どちらも旧名称の unauthorized と表示される場合があります。

ヘッダーは Authorization: Bearer <key> です。Bearer がないと、キーの形式が不正と判断されます。
キーの前後に貼り付けた空白もキーの一部として扱われます。
ダッシュボード → API キーで有効か確認してください。無効にしたキーは即座に、以後も利用できなくなります。
クライアントによっては x-api-key や x-goog-api-key ヘッダーを使います。これらも利用でき、同じアカウントと残高に紐付きます。

403 forbidden

認証は成功しましたが、そのアカウントまたはキーでは操作が許可されていません。リクエストを調べる前に、キーの IP 許可リスト、呼び出せるモデルのグループ、アカウントの状態を確認してください。無料クレジットしかないアカウントで無料対象外のモデルを呼ぶと、理由を示すメッセージとともに 403 forbidden を返します。チャージすると利用できます。

BeatAPI の 403 は常に BeatAPI 自身の判定です。モデルの応答を 403 としてそのまま返すことはありません。ただし、本文が error code: 1010 の 403 はネットワークのエッジで発生しています。User-Agent を明示してください。コンテンツ審査で拒否されたプロンプトは、作成時には 400 content_policy_violation、受け付け済みのタスクでは error_code の content_policy_violation として示されます。エラーを参照してください。

402 insufficient_credits

残高が 0、またはリクエストの料金に足りません。クレジットを追加するまで、アカウントのすべての有料操作で 402 が返されます。キー単位ではありません。残高不足は、すべてのエンドポイントで必ず 402 です。ユーザー向けのサービスでは監視を推奨します。

429 rate_limit_exceeded

異なる 2 つの制限が 429 を返します。それぞれ対処方法が異なります。

リクエスト数の制限は、キーの毎分のリクエスト数が多すぎる場合です。Retry-After または retry_after_seconds に従ってください。有料の上限はチャージ累計額に応じて増えます。無料モデルには独自の固定上限があり、初回チャージ前は毎分 1 件、チャージ後は毎分最大 10 件の成功リクエストです。有料の上限とは別に計測します。
user_concurrency_exceeded は同時処理中のタスクが多すぎる場合です。すぐ再試行せず、実行中のタスクの完了を待ってください。GET /v1/usage は concurrency.limit と concurrency.active を返します。

リクエスト数の制限は、ポーリングループが原因になりがちです。タスクエンドポイントの上限はキーごとに毎分 120 リクエストです。複数のタスクを 1 秒ごとに確認するだけで、この上限を使い切ることがあります。開発ガイドを参照してください。

リクエストがタイムアウトします

stream: false のテキスト呼び出しは、モデルの処理が終わるまで応答を返しません。長い推論では時間がかかる場合があります。次の 2 点を試してください。

ストリーミングを使います。 stream: true なら最初のデータが早く届き、処理中も接続が維持されます。
クライアントのタイムアウトを延ばします。 多くの SDK の初期値は 30 秒または 60 秒で、長い非ストリーミングの生成には短い場合があります。

タスクが終わりません

経過時間ではなくステータスを確認してください。GET /v1/tasks/{task_id} は決められた状態のいずれかを返します。そのうち 2 つは処理中を意味しません。

Music Video タスクの storyboard_ready と requires_action は、モデルではなく利用者の操作を待っています。ポーリングを続けても処理は進みません。

それ以外は、終了状態（succeeded、failed）か実際の処理中です。全状態の表はクイックガイドを参照してください。

サーバーからは接続できませんが、自分の PC からは接続できます

実際に呼び出すマシンからテストしてください。Dify、Docker の AnythingLLM、CI ランナーなどのセルフホスト環境には、それぞれ外向き通信の制限があります。コンテナーまたはホストが api.beatapi.io に到達できるか確認し、社内プロキシでも通信を許可してください。

不具合報告には何を含めますか？

失敗したレスポンスの request_id を含めてください。すべての BeatAPI エラーに付いており、ログ内の呼び出しを正確に特定できます。モデル ID、エンドポイント、おおよその時刻も添えて、ダッシュボードからチケットを作成してください。