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

	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.cn/mcp` (streamable HTTP)	`https://api.beatra.cn/v1`
Reference	Install the Beatra Skill	MCP tool reference	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.

Install the Agent 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:

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. What gets installed, and how to update or reconnect: Install the Beatra Skill.

Beatra MCP

Beatra MCP is the server at https://mcp.beatra.cn/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.

Call the REST API

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

Create an API key in the console under Developer → API keys.
Send it as Authorization: Bearer <API key>, with an Idempotency-Key on requests that create work: Authentication & request conventions.
Submit a request, then follow the returned task until it finishes: Async tasks.

What is the same on all three

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.