BeatAPI Agent Plugin

Quick start · Model coverage · Security · Verification

BeatAPI Agent Plugin

A cross-host Agent Toolkit plugin for discovering live BeatAPI models andrunning text, image, video, Effect, analysis, and production workflowAPIs through one local MCP interface.

The repository packages the same canonical beatapi-video Skill, bundled MCPserver, typed client, and locked OpenAPI contract for four agent surfaces:

Marketplace acceptance is a separate review step. The presence of a manifestin this repository does not mean a listing is already live.

Quick start

1. Create a key in Dashboard → API Keys.
2. Install the plugin for your host using one of the paths below.
3. Configure the key outside the conversation. For local uploads, also setBEATAPI_UPLOAD_ROOTS to directories containing files you selected.
4. Ask the agent to discover current models before creating a paid task.

For example:

Use $beatapi-video to list current video models, choose one that supports image
references, and create a 10-second 9:16 product shot from these images.

Requirements: Node.js 20.19+ or 22.12+, a BeatAPI account, and network access tohttps://api.beatapi.io.

Install on Cursor and Grok Bot

Cursor and Grok Bot share the same Cursor Marketplace plugin and account-levelconfiguration. For local review on macOS or Linux, link this checkout and reloadCursor:

ln -s /absolute/path/to/beatapi-agent-plugin \
  ~/.cursor/plugins/local/beatapi-agent-plugin

Open Customize → Plugins → BeatAPI → Configure, then setBEATAPI_API_KEY. Add BEATAPI_UPLOAD_ROOTS only when you need local uploads;use colon-separated absolute directories on macOS/Linux or semicolon-separateddirectories on Windows. Keep the default BEATAPI_BASE_URL; a support-providedcustom HTTPS origin also requires BEATAPI_TRUST_CUSTOM_BASE_URL=1.

Install on Grok Build

Validate and install a source checkout with the current Grok Build CLI:

npm ci
npm run verify
grok plugin validate .
grok plugin install .

The recommended credential path is the operating-system credential manager:

npm install --global [email protected]
beatapi auth login
export BEATAPI_CLI_PATH="$(command -v beatapi)"

The reviewed npm integrity for [email protected] issha512-7a7XF/tCc5u2p/ZnonSkLq1JF4OPpv3yaj7mFqnQcK9/HjOtj5hMny5bax4VcTbjgHRfDc1QlFXSbF3tzIL19Q==.

Alternatively, export the key only in the shell that launches Grok Build:

read -s BEATAPI_API_KEY
export BEATAPI_API_KEY
printf '\n'
grok

Install on Codex

Build and add the repository-local marketplace:

npm ci
npm run verify
codex plugin marketplace add ./dist/marketplace
codex plugin add beatapi-agent-plugin@beatapi-local

Then run beatapi auth login and set BEATAPI_CLI_PATH to the CLI's absoluteexecutable path, or set BEATAPI_API_KEY in the environment that launchesCodex. Restart the desktop app after installation.

Model coverage

Model IDs are discovered at runtime rather than hardcoded into the plugin:

The generic image and video tools accept a current model ID plus itsmodel-specific parameters. New models can therefore appear in discoverywithout requiring a new plugin release. The bundled OpenAPI snapshot remains thesource for each model's supported fields and constraints.

What the plugin can do

• discover text models, image/video model aliases, workflows, and publishedEffects;
• create non-streaming text responses when the user explicitly requestsBeatAPI text generation;
• create image, video, Effect, Video Analysis, Music Video, and Ecommerce Videotasks;
• upload explicitly selected local images, audio, MP4/MOV video, and SRT filesfrom configured trusted directories;
• inspect, edit, materialize, and compose Music Video storyboard shots;
• inspect and close existing short-lived Realtime Video sessions;
• poll asynchronous tasks until a terminal or actionable state;
• inspect USD balance, usage, and active concurrency;
• inspect, update, and delete existing webhook endpoints.

The MCP server exposes 26 focused tools. Paid mutations are labeled as such;read-only and destructive annotations are set independently.

Realtime-session and webhook creation return one-time secrets. Those two createoperations are intentionally not exposed to an agent until a host secret brokercan keep both the secret and its retrieval handle outside model authority. Usetrusted server-side application code or the BeatAPI dashboard for that setup.

API key and secret safety

Never paste an API key into a prompt. The plugin excludes credential fields andrecursively rejects credential-shaped values in open-ended model parameters.

• Cursor and Grok Bot inject declared variables from the plugin configurationscreen.
• Codex and Grok Build can use beatapi auth login or inheritBEATAPI_API_KEY from the launching process.
• Responses are recursively sanitized for credential-like fields and bearervalues.
• Local uploads are disabled until BEATAPI_UPLOAD_ROOTS is configured, thencanonical paths are confined to those trusted directories and symlinks arerejected.
• One-time-secret creation operations are not exposed through this agentpackage.
• The default endpoint is https://api.beatapi.io; overrides must be exactHTTPS origins without credentials, paths, queries, or fragments and require aseparate explicit operator trust flag.

Architecture

flowchart LR
  H[Codex · Cursor · Grok Bot · Grok Build] --> M[Host manifest]
  M --> S[beatapi-video Skill]
  M --> P[Bundled stdio MCP server]
  P --> C[Locked typed client]
  C --> A[BeatAPI public API]
  O[Locked OpenAPI contract] --> C
  O --> S

The host-specific manifests are thin adapters. Product behavior stays local tothe shared Skill, MCP server, typed client, and contract, so fixes do not driftacross separate repositories.

Package layout

Do not edit synchronized Skill or client files directly. Refresh them throughnpm run skill:sync and npm run runtime:sync.

Publishing paths

1. Cursor Marketplace and Grok Bot: submit this public repository once athttps://cursor.com/marketplace/publish after owner review and merge.
2. Grok Build Marketplace: add a SHA-pinned entry for this public repositoryto xai-org/plugin-marketplace and regenerate its component index.
3. Codex local marketplace: npm run marketplace:build creates aninstallable marketplace and ZIP under dist/.
4. OpenAI Plugin Directory: npm run submission:build creates the separateSkills-only review artifact. It does not claim a hosted HTTPS MCP server.

See submission/SUBMISSION.md for the separate publicdirectory review boundary.

Verification

npm run verify
python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
grok plugin validate .

Verification covers OpenAPI drift, synchronized Skill/client sources, Cursorand Grok manifests, TypeScript, MCP protocol behavior, credential rejection andredaction, upload-root confinement and size limits, deterministic bundles, andrelease packaging.

Contributing

Issues and pull requests are welcome. Please keep new claims tied to executablesource, tests, or the current public OpenAPI contract, and run npm run verifybefore opening a pull request.

License

MIT