Quick Guide

BeatAPI uses one server-side API key across Workflow, Realtime, Video, Image, and Effect APIs. Start with the three steps below, then use the rest of this guide for shared task fields, uploads, limits, and production errors.

First task in three steps

1. Create an API key

Create a key in Dashboard → API Keys, then load it into your shell without placing it in command history:

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

All requests use the https://api.beatapi.io base URL and this header:

1
Authorization: Bearer <BEATAPI_API_KEY>

2. Create a task

This minimal image request uses POST /v1/images/tasks:

$
curl https://api.beatapi.io/v1/images/tasks \
>
  -X POST \
>
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "model": "nano-banana",
>
    "prompt": "Editorial product photograph on a warm stone pedestal."
>
  }'

A valid request returns 201 Created. Save the returned data.id.

3. Poll the result

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

Replace task_8K2qA with the data.id from step 2. Poll every 5–10 seconds with jitter. On succeeded, read data.output.media and stop polling. On failed, read data.error_code and data.error_message, then stop polling.

Choose an API

With the exception of Realtime, create operations return an asynchronous Task. Store data.id, then poll the shared task endpoint. 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
}

Public error codes

BeatAPI exposes only the stable public codes below. Internal provider errors are normalized and are never part of the customer contract. These values appear in response error.code. Terminal asynchronous failures may also return the applicable value in task error_code.

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.