Quick Guide

BeatAPI provides one server-side API key for Workflow, Realtime, Video, Image, and Effect APIs. This guide covers authentication, file upload, the shared async Task contract, usage, and production error handling.

Base URL and authentication

https://api.beatapi.io

Create a key in Dashboard → API Keys, then keep it on a trusted server.

$
read -rsp "BeatAPI API key: " BEATAPI_API_KEY && echo
$
export BEATAPI_API_KEY

1
Authorization: Bearer <BEATAPI_API_KEY>

The silent prompt keeps the key out of shell history. Never place a permanent key in browser code, mobile code, scripts, logs, or screenshots. Realtime browsers receive only a short-lived client_secret created by your server.

Choose an API

With the exception of Realtime, create operations return an asynchronous Task. Store data.id, then poll the shared task endpoint.

First async request

$
curl https://api.beatapi.io/v1/music-video/tasks \
>
  -X POST \
>
  -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.",
>
    "resolution": "720p"
>
  }'

A valid request returns 201 Created. Save data.id before continuing.

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

Poll every 5–10 seconds with jitter. The task endpoint allows up to 120 requests per minute per API key.

Get task status

GET /v1/tasks/{task_id}

Status values

Normalized Task fields

Usage and output fields

Upload an input file

POST /v1/files

Use file upload when an input is local instead of already available at a public HTTPS URL.

Multipart fields

$
curl https://api.beatapi.io/v1/files \
>
  -X POST \
>
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
>
  -F "file=@./song.mp3" \
>
  -F "purpose=input"

You may also send the raw file body with its asset Content-Type.

PDF, generic text, octet-stream, video, and ZIP uploads are not supported. Workflow input URLs cannot be localhost, private-network, or data URLs.

File response

1
{
2
  "data": {
3
    "id": "file_3xYz9",
4
    "object": "file",
5
    "url": "https://media.beatapi.io/inputs/file_3xYz9.mp3",
6
    "key": "inputs/file_3xYz9.mp3",
7
    "mime_type": "audio/mpeg",
8
    "size_bytes": 1048576,
9
    "purpose": "input",
10
    "audio_duration_seconds": 64.02,
11
    "audio_duration_source": "mp3_frame_scan",
12
    "created_at": 1782210000
13
  }
14
}

Use data.url in the model or workflow request. Audio task limits still apply: Standard Music Video accepts 10–180 seconds; Premium accepts 10–300.

Check usage and limits

GET /v1/usage

This authenticated endpoint has no parameters.

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

Breakdown item fields:

Music Video tasks paused at storyboard_ready or requires_action can have settled credits without counting as active processing work.

Errors and retry policy

1
{
2
  "error": {
3
    "code": "rate_limit_exceeded",
4
    "message": "Too many requests.",
5
    "request_id": "req_abc123",
6
    "retry_after_seconds": 12
7
  }
8
}

Idempotency differs by endpoint:

• Realtime Session create requires Idempotency-Key (1–128 characters).
• Workflow, Image, Video, and Effect task creation accept an optional key. Reuse a key only with the exact same logical request body.
• Image, Video, and Effect keys are documented with a maximum of 255 characters. Workflow keys should be kept concise for cross-database compatibility.

Production checklist

• Use the exact https://api.beatapi.io origin.
• Keep permanent API keys on trusted servers.
• Validate required/optional fields, enums, limits, and conditional rules from the selected API page.
• Store task/Session IDs and request_id before starting background work.
• Poll with jitter and stop at the documented terminal or action state.
• Honor status codes, Retry-After, and retry_after_seconds.
• Verify webhook signatures against raw bytes before JSON parsing.
• Record credit reservations, settlements, refunds, errors, and final output URLs.
• Review the Privacy Policy and Terms of Service before processing cameras, faces, voices, or reference assets.