# 选择 Beatra 的使用方式：Agent Skill、MCP 还是 REST API
> 在智能体里使用，就装 Beatra Skill，它会替你连接 Beatra MCP；开发自己的应用，就调用 REST API。三种方式各适合谁、怎么开始。

Beatra 是专为 AI 智能体打造的多媒体生成服务：通过 Agent Skill 或 MCP，让智能体直接生成图片、视频、音乐和配音，并查询公开社交数据。安装免费，生成按积分计费。

在智能体里使用，就装 Beatra Skill，它会替你连接 Beatra MCP；开发自己的应用，就调用 REST API。三种方式创建同样的异步任务、消耗同一份积分；公开社交数据只能通过 Skill 和 Beatra MCP 使用。

## 三种方式对比 [#compare]

| | Agent Skill（智能体用户推荐） | Beatra MCP | REST API |
| --- | --- | --- | --- |
| 适合 | 在智能体里工作的人 | Skill 底层运行的工具层 | 开发自己的应用、后端服务或批量任务的开发者 |
| 从哪开始 | 给智能体发一条安装消息 | 安装 Skill，由 Skill 连接 | 在控制台创建 API Key |
| 登录方式 | 浏览器里用设备码批准一次 | 同一个设备码，由 Skill 申请 | `Authorization: Bearer <API key>` |
| 怎么调用 | 用平常说话的方式告诉智能体 | MCP 工具，例如 `beatra.images.generate` | `/v1` 下的 HTTPS 接口 |
| 服务地址 | 通过 Skill 自带的客户端调用 Beatra MCP | `https://mcp.beatra.cn/mcp`（streamable HTTP） | `https://api.beatra.cn/v1` |
| 参考文档 | [安装 Beatra Skill](https://docs.beatra.cn/zh/docs/install-skill) | [MCP 工具参考](https://docs.beatra.cn/zh/docs/mcp-tools) | [API 参考](https://docs.beatra.cn/zh/docs/api-reference) |

安装 Skill 和登录都免费。每次生成媒体、每次查询公开社交数据都从同一份积分里扣除，见[计费与用量](https://docs.beatra.cn/zh/docs/mechanisms/billing)。

## 安装 Agent Skill [#skill]

Beatra Skill 是一个包含全部能力的包：图片、视频、音乐、语音和公开社交数据。除了工具本身，它还告诉智能体怎么做事：什么时候扣积分、怎样重试才不会重复扣费、怎么上传本地文件、怎么查当前的模型和价格。

把这条消息发给你的智能体：

```text title="发给智能体"
请帮我安装 Beatra；需要登录授权时告诉我：https://beatra.ai/install.md
```

智能体会装好 Skill，在浏览器里打开 Beatra 授权页面，等你登录并点「允许连接」。分步说明见[快速开始](https://docs.beatra.cn/zh/docs/quickstart)；装了什么、以后怎么更新和重新连接，见[安装 Beatra Skill](https://docs.beatra.cn/zh/docs/install-skill)。

## Beatra MCP [#mcp]

Beatra MCP 是运行全部 Beatra 工具的服务，地址是 `https://mcp.beatra.cn/mcp`（streamable HTTP），负责生成媒体、上传文件、查询模型和音色、查看任务。它用设备码登录，Beatra Skill 会替你申请设备码并保持连接，所以使用 MCP 的起点就是安装 Skill。

每个工具的参数、返回内容和计费方式见 [MCP 工具参考](https://docs.beatra.cn/zh/docs/mcp-tools)。

## 调用 REST API [#rest]

REST API 以 HTTPS 接口提供图片、视频、音乐、配音生成和声音克隆，地址是 `https://api.beatra.cn/v1`，接口契约是 [/openapi.json](https://docs.beatra.cn/openapi.json)（OpenAPI 格式）。它适合不经过智能体运行的代码：你自己的产品、后端服务或定时任务。

1. 在[控制台](https://console.beatra.cn)「开发 → API Key」里创建 API Key。
2. 用 `Authorization: Bearer <API key>` 发送，创建类请求带上 `Idempotency-Key`，见[认证与请求约定](https://docs.beatra.cn/zh/docs/authentication)。
3. 提交请求后，跟踪返回的任务直到完成，见[异步任务](https://docs.beatra.cn/zh/docs/mechanisms/async-tasks)。

## 三种方式相同的部分 [#shared]

- **任务**：生成媒体都会返回一个任务，从 `queued` 到 `running` 再到最终状态，各处字段相同。
- **积分**：每个 Beatra 账号一份余额。各模型的价格以 `beatra.models.list` 和 `GET /v1/catalog/models` 的实时数据为准。
- **错误**：错误码和重试规则相同，见[排错指南](https://docs.beatra.cn/zh/docs/troubleshooting)。