# Choose how to use Beatra: Agent Skill, MCP, or REST API
> Agent users install the Beatra Skill, which connects Beatra MCP for them; developers building their own app call the REST API. When each fits and how to start.

Beatra is a creative runtime for AI agents: install one Agent Skill or connect the Beatra MCP server, describe what you want, and your agent generates images, video, music, and speech, and looks up public social data — all billed from one credit balance.

If you use an agent such as Claude Code, Cursor, Codex, or WorkBuddy, install the Beatra Skill: it is the recommended way, and it connects Beatra MCP for you. If you are building your own app, backend, or batch job, call the REST API with an API key. All three create the same asynchronous tasks and spend the same credits; public social data is available only through the Skill and Beatra MCP.

## Compare the three [#compare]

| | Agent Skill (recommended for agents) | Beatra MCP | REST API |
| --- | --- | --- | --- |
| Fits | People who work in an agent | The tool layer the Skill runs on | Developers building their own app, backend, or batch job |
| Start with | One install message to your agent | Installing the Skill, which connects it | An API key from the console |
| Sign-in | One browser approval with a device code | The same device code, requested by the Skill | `Authorization: Bearer <API key>` |
| What you call | Plain-language requests to your agent | MCP tools such as `beatra.images.generate` | HTTPS endpoints under `/v1` |
| Endpoint | Runs Beatra MCP through its bundled client | `https://mcp.beatra.ai/mcp` (streamable HTTP) | `https://api.beatra.ai/v1` |
| Reference | [Install the Beatra Skill](https://docs.beatra.ai/en/docs/install-skill) | [MCP tool reference](https://docs.beatra.ai/en/docs/mcp-tools) | [API reference](https://docs.beatra.ai/en/docs/api-reference) |

Installing the Skill and signing in are free. Each generation and each public social data lookup uses Beatra credits from the same balance: see [Billing & usage](https://docs.beatra.ai/en/docs/mechanisms/billing).

## Install the Agent Skill [#skill]

The Beatra Skill is one package with every capability: images, video, music, speech, and public social data. Besides the tools, it gives the agent the working rules: when credits are charged, how to retry without paying twice, how to upload local files, and how to look up current models and prices.

Send this message to your agent:

```text title="Send to your agent"
Install Beatra and tell me when I need to sign in: https://beatra.ai/install.md
```

The agent installs the Skill, opens a Beatra approval page in your browser, and waits while you sign in and choose **Allow**. Step-by-step: [Quickstart](https://docs.beatra.ai/en/docs/quickstart). What gets installed, and how to update or reconnect: [Install the Beatra Skill](https://docs.beatra.ai/en/docs/install-skill).

## Beatra MCP [#mcp]

Beatra MCP is the server at `https://mcp.beatra.ai/mcp` (streamable HTTP) that runs every Beatra tool: creating media, uploading files, listing models and voices, and checking tasks. It signs in with a device code, and the Beatra Skill requests that code and keeps the connection for you, so installing the Skill is how to start with MCP.

Every tool, with its arguments, output, and price behaviour, is in the [MCP tool reference](https://docs.beatra.ai/en/docs/mcp-tools).

## Call the REST API [#rest]

The REST API offers image, video, music, and speech generation and voice cloning as HTTPS endpoints at `https://api.beatra.ai/v1`, described by an OpenAPI contract at [/openapi.json](https://docs.beatra.ai/openapi.json). It fits code that runs without an agent: your own product, a backend service, or a scheduled job.

1. Create an API key in the [console](https://console.beatra.ai) under **Developer → API keys**.
2. Send it as `Authorization: Bearer <API key>`, with an `Idempotency-Key` on requests that create work: [Authentication & request conventions](https://docs.beatra.ai/en/docs/authentication).
3. Submit a request, then follow the returned task until it finishes: [Async tasks](https://docs.beatra.ai/en/docs/mechanisms/async-tasks).

## What is the same on all three [#shared]

- **Tasks:** creating media returns a task that moves from `queued` to `running` to a final state, with the same fields everywhere.
- **Credits:** one balance per Beatra account. Prices per model are live in `beatra.models.list` and `GET /v1/catalog/models`.
- **Errors:** the same error codes and retry rules: [Troubleshooting](https://docs.beatra.ai/en/docs/troubleshooting).