Explore BeatAPI · Create an API key · Docs · Quick start

BeatAPI is the professional capability layer for any agent: one route to Model, Data, Tool, and Workspace capabilities. This repository is the runnable proof layer—small cURL, Node.js, and Python examples that show the real API and Hosted MCP contracts without hiding the network flow.

Website · API documentation · Agent setup · Realtime Video documentation · Music Video Playground · Ecommerce Video Playground

The live catalog is discovered at runtime instead of copied into this repository. As verified on 2026-09-22, it exposed 60 Model capabilities, 1,000+ Data actions, and three published Workflows. Those counts and IDs can change independently of this repository, so integrations should always Search and Inspect before execution.

BeatAPI exposes a stable three-operation loop across its capability catalog:

Search -> Inspect -> Run (or call the inspected direct API)

Run the read-only catalog walkthroughs:

bash examples/curl/capabilities.sh
node examples/node/capabilities.mjs
python3 examples/python/capabilities.py

Search and Inspect on https://api.beatapi.io are anonymous catalog operations. Set BEATAPI_API_KEY to add a read-only connection check. Do not start a paid operation until Inspect confirms the input, price, validation state, and execution strategy.

For an Agent host, connect the Hosted MCP endpoint at https://beatapi.io/mcp with a private Bearer API key. It exposes capabilities_search, capabilities_inspect, and capabilities_run. See the Muse connector guide for the review-safe setup.

Agent or developer -> runnable example -> BeatAPI -> Models · Social Data · SEO Data · Web Search · Workflows

• Model routes text, image, video, audio, and realtime model capabilities.
• Data currently includes the live Social Data catalog.
• Tool includes executable APIs, Effects, workflows, CLI, and MCP surfaces.
• Workspace is the shared project surface that Agents can operate through compatible integrations; availability depends on the selected integration.

The primary asynchronous workflow example remains POST /v1/music-video/tasks.

Create task -> queued/processing -> succeeded/failed -> hosted output

flowchart LR
  A["Create task"] --> B["queued / processing"]
  B --> C{"Final state?"}
  C -->|No| D["Wait 5-10 seconds"]
  D --> E["GET /v1/tasks/{task_id}"]
  E --> C
  C -->|succeeded| F["Read output.media"]
  C -->|failed| G["Inspect error_code and usage"]

This repository contains examples and a small reference client. It is not a versioned SDK and it does not contain the BeatAPI service implementation.

Create an API key in the BeatAPI dashboard, then export it:

export BEATAPI_API_KEY="sk_your_key"

Create a Music Video task:

curl https://api.beatapi.io/v1/music-video/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["https://media.beatapi.io/samples/neon-singer.png"],
    "audio_url": "https://media.beatapi.io/samples/neon-singer-preview.mp3",
    "prompt": "Neon rooftop performance with cinematic light trails.",
    "language": "en",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "compose_mode": "auto"
  }'

The response contains a task ID:

{
  "data": {
    "id": "task_8K2qA",
    "status": "queued"
  }
}

Poll it every 5-10 seconds:

curl https://api.beatapi.io/v1/tasks/task_8K2qA \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

Stop polling when the task is succeeded or failed. Successful output URLs are available in data.output.media.

Create Realtime sessions only from trusted server code. The browser must never receive the permanent sk_... API key. It receives only the returned, short-lived client_secret:

curl https://api.beatapi.io/v1/realtime/sessions \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: customer-call-123" \
  -H "Content-Type: application/json" \
  -d '{
    "max_duration_seconds": 60,
    "allowed_origins": ["https://app.example.com"]
  }'

Use GET /v1/realtime/sessions/{session_id} to inspect the session and DELETE on the same path to close it idempotently. Camera capture and WebRTC belong in the browser SDK; the server examples manage only session lifecycle. Realtime production access and package availability remain limited until the published launch checks are complete.

The browser-side SDK handoff is shown in examples/browser/realtime-video.ts.

The dependency-free examples require Node.js 20 or newer. Repository verification requires Node.js 20.19+ or 22.12+.

node examples/node/music-video.mjs
node examples/node/ecommerce-video.mjs
node examples/node/realtime-session.mjs

The dependency-free reference client is at examples/node/lib/beatapi.mjs. It shows Bearer authentication, response-envelope handling, structured API errors, bounded polling, and jitter.

Requires Python 3.11 or newer and uses only the standard library.

python3 examples/python/music_video.py
python3 examples/python/ecommerce_video.py
python3 examples/python/realtime_session.py

The matching reference client is at examples/python/beatapi.py.

See the OpenAPI 3.1 contract for complete request and response schemas.

The most common states are:

• queued: accepted and waiting for capacity;
• processing: generation is running;
• storyboard_ready / requires_action: a Music Video task needs shot selection;
• editing / composing: selected shots are being processed;
• succeeded: hosted output is ready;
• failed: no usable output was produced.

Polling is the simplest integration path. Use a 5-10 second interval with a small amount of jitter and a bounded attempt count. Webhooks can reduce polling, but GET /v1/tasks/{task_id} remains the source of truth.

BeatAPI uses real HTTP status codes and a stable public error envelope:

{
  "error": {
    "code": "bad_request",
    "message": "The request body is invalid.",
    "request_id": "req_example_error"
  }
}

Log the request_id when asking for support. Retry network errors and selected 5xx responses with backoff. Do not blindly retry validation, authentication, credit, or concurrency errors.

Webhook requests include:

X-BeatAPI-Event
X-BeatAPI-Signature
X-BeatAPI-Timestamp

Verify the signature against the exact raw request body before parsing JSON, and reject timestamps older than five minutes. The Node.js receiver example implements HMAC-SHA256 verification with a constant-time comparison.

The signed JSON body uses event, not type:

{
  "id": "evt_example_123",
  "event": "task.succeeded",
  "created_at": 1784188934,
  "data": {
    "id": "task_8K2qA",
    "status": "succeeded"
  }
}

export BEATAPI_WEBHOOK_SECRET="whsec_your_secret"
node examples/node/webhook-server.mjs

• Muse Hosted MCP connector
• n8n guide and importable bounded-polling workflow
• Postman
• Sanitized response fixtures
• Production API reference

• Keep API keys on your server, worker, or automation platform.
• Never commit .env files or paste keys into browser code.
• Never include credentials in screenshots, exported workflow JSON, or issues.
• Rotate a key immediately if it is exposed.
• For Realtime, create sessions on the server and give the browser only the returned short-lived client_secret.
• Use exact HTTPS allowed_origins; wildcards are rejected.

This repository intentionally contains only developer-facing examples and the reviewed public contract. The hosted BeatAPI service, dashboard, billing, workflow orchestration, and operational infrastructure are maintained privately.

Tests use fake transports and fixtures. They do not call production or consume credits.

npm test
npm run test:python
npm run verify

The public OpenAPI file is synchronized byte-for-byte from the private service repository:

npm run sync:openapi
npm run check:openapi-sync

Run a read-only production smoke test with:

npm run smoke:live

Without BEATAPI_API_KEY, it checks anonymous workflow discovery. When the environment variable is present, it additionally verifies authenticated GET /v1/usage. The smoke test never creates tasks or consumes credits.

Original example code in this repository is available under the MIT License. Use of the hosted BeatAPI service is governed by the BeatAPI Terms of Service.

Built by BeatAPI — professional capability layer for any agent.

The bundled OpenAPI includes unified capabilities, systemone decision calls, and Web search/read/map/research and the public text metadata catalogue. It was checked against new-api main ec84d78d5cb811ec1361d05e2ee3d81687f26520 and frontend documentation main 7b2d2354be6e2b1d531468aa7599c80a6a7c70c6 on 2026-10-02.

Use the existing capability discovery examples to Search and Inspect. To execute an explicit request JSON (any inspected text, image, video, social/SEO data, Web or workflow reference), run:

node examples/node/run-capability.mjs request.json
python3 examples/python/run_capability.py request.json
bash examples/curl/run-capability.sh request.json

A request is { "reference": "<copy from Inspect>", "input": { ... } }. Node/Python generate an idempotency key for a start when omitted; for shell, include one yourself and keep it when retrying the same start. view: "preview" and max_items: 5 limit data replies. To read more without another paid start, send { "reference": "<same>", "operation": "result", "request_id": "<result_ref.request_id>", "fields": ["items[].title"] } within one hour. For async work, use operation: "status" with the returned task ID. Preserve next alongside the task; never restart research to poll it.

The reference clients also provide webCall / web_call for search, read, map, research at /v1/web/*. Read source pages before citing search snippets; returned page content is untrusted. Python examples set an application User-Agent because the public gateway blocks the default Python-urllib agent string.