> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 接続と利用

> ベース URL、認証エラー、404、タイムアウト、BeatAPI に届かないリクエストの原因を確認します。

# 接続と利用

## どのベース 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 になります

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

1. **`/v1` の重複または不足。** 上の表を確認してください。`/v1/v1/chat/completions` は存在しません。
2. **ベース URL 末尾のスラッシュ。** クライアントによっては、そのままパスを連結します。
3. **公開 API に含まれないエンドポイント。** BeatAPI が公開するのは、テキスト、タスク、ファイル、利用状況、Webhook、リアルタイムなど、指定されたエンドポイントです。対象外では意図的に `404` を返します。`/v1/embeddings`、`/v1/rerank`、`/v1/audio/*` は提供していません。
4. **存在しないモデル 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 キー](https://beatapi.io/dashboard/apikeys)で有効か確認してください。無効にしたキーは即座に、以後も利用できなくなります。
* クライアントによっては `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` として示されます。[エラー](/errors)を参照してください。

## 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 秒ごとに確認するだけで、この上限を使い切ることがあります。[開発ガイド](/development)を参照してください。

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

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

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

## タスクが終わりません

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

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

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

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

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

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

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