# Beatra の利用方法を選ぶ：Agent Skill、MCP、REST API
> Agent を使う人は Beatra Skill をインストールし、Skill が Beatra MCP に接続します。独自アプリを作る開発者は REST API を呼び出します。それぞれの向き不向きと始め方。

Beatra は AI Agent のためのクリエイティブ実行基盤です。Agent Skill を 1 つインストールするか Beatra MCP サーバーに接続して、作りたいものを伝えると、Agent が画像・動画・音楽・音声を生成し、公開ソーシャルデータを検索します。料金はすべて 1 つのクレジット残高から支払います。

Claude Code、Cursor、Codex、WorkBuddy などの Agent で使う場合は、Beatra Skill のインストールをおすすめします。Skill が Beatra MCP への接続を代わりに行います。独自のアプリ、バックエンド、バッチ処理を作る場合は、API キーで REST API を呼び出します。3 つの方法は同じ非同期タスクを作成し、同じクレジットを使います。公開ソーシャルデータは Skill と Beatra MCP でのみ使えます。

## 3 つの方法の比較 [#compare]

| | Agent Skill（Agent 利用者におすすめ） | Beatra MCP | REST API |
| --- | --- | --- | --- |
| 向いている人 | Agent で作業する人 | Skill が内部で使うツール層 | 独自のアプリ、バックエンド、バッチ処理を作る開発者 |
| 始め方 | Agent にインストールメッセージを 1 通送る | Skill をインストールすると Skill が接続する | コンソールで API キーを作成する |
| ログイン | ブラウザでデバイスコードを一度承認する | Skill が申請する同じデバイスコード | `Authorization: Bearer <API key>` |
| 呼び出し方 | 普段の言葉で Agent に頼む | `beatra.images.generate` などの MCP ツール | `/v1` 以下の HTTPS エンドポイント |
| 接続先 | Skill に同梱のクライアントが Beatra MCP を呼び出す | `https://mcp.beatra.ai/mcp`（streamable HTTP） | `https://api.beatra.ai/v1` |
| リファレンス | [Beatra Skill のインストール](https://docs.beatra.ai/ja/docs/install-skill) | [MCP ツールリファレンス](https://docs.beatra.ai/ja/docs/mcp-tools) | [API リファレンス](https://docs.beatra.ai/ja/docs/api-reference) |

Skill のインストールとログインは無料です。メディアの生成と公開ソーシャルデータの検索は、どちらも同じクレジット残高から差し引かれます。[課金と使用量](https://docs.beatra.ai/ja/docs/mechanisms/billing)を参照してください。

## Agent Skill をインストールする [#skill]

Beatra Skill は、画像、動画、音楽、音声、公開ソーシャルデータのすべての機能を 1 つにまとめたパッケージです。ツールに加えて、クレジットが使われるタイミング、二重に課金されない再試行の方法、ローカルファイルのアップロード方法、現在のモデルと価格の調べ方といった作業のルールも Agent に伝えます。

次のメッセージを Agent に送ってください。

```text title="Agent に送る"
Beatra をインストールし、ログインが必要になったら知らせてください：https://beatra.ai/install.md
```

Agent は Skill をインストールし、ブラウザで Beatra の承認ページを開いて、あなたがログインして「接続を許可」を選ぶのを待ちます。手順は[クイックスタート](https://docs.beatra.ai/ja/docs/quickstart)、インストールされる内容と更新・再接続の方法は[Beatra Skill のインストール](https://docs.beatra.ai/ja/docs/install-skill)にあります。

## Beatra MCP [#mcp]

Beatra MCP は、すべての Beatra ツールを実行するサーバーです。接続先は `https://mcp.beatra.ai/mcp`（streamable HTTP）で、メディアの生成、ファイルのアップロード、モデルとボイスの一覧、タスクの確認を担います。ログインにはデバイスコードを使い、Beatra Skill がデバイスコードの申請と接続の維持を代わりに行います。そのため、MCP を使い始める方法は Skill のインストールです。

各ツールの引数、出力、課金の扱いは [MCP ツールリファレンス](https://docs.beatra.ai/ja/docs/mcp-tools)にあります。

## REST API を呼び出す [#rest]

REST API は、画像・動画・音楽・音声の生成とボイスクローンを `https://api.beatra.ai/v1` の HTTPS エンドポイントとして提供し、その仕様は OpenAPI 形式の [/openapi.json](https://docs.beatra.ai/openapi.json) にあります。Agent を介さずに動くコード、つまり独自の製品、バックエンドサービス、定期実行のジョブに向いています。

1. [コンソール](https://console.beatra.ai)の「開発者向け → API キー」で API キーを作成します。
2. `Authorization: Bearer <API key>` で送信し、作業を作成するリクエストには `Idempotency-Key` を付けます。[認証とリクエスト規約](https://docs.beatra.ai/ja/docs/authentication)を参照してください。
3. リクエストを送信したら、返されたタスクを完了まで追跡します。[非同期タスク](https://docs.beatra.ai/ja/docs/mechanisms/async-tasks)を参照してください。

## 3 つの方法で共通のこと [#shared]

- **タスク**：メディアの生成はどれもタスクを返し、`queued` から `running` を経て最終状態になります。フィールドはどこでも同じです。
- **クレジット**：Beatra アカウントごとに 1 つの残高です。モデルごとの価格は `beatra.models.list` と `GET /v1/catalog/models` の最新データで確認できます。
- **エラー**：エラーコードと再試行のルールは同じです。[トラブルシューティング](https://docs.beatra.ai/ja/docs/troubleshooting)を参照してください。