Quick Guide

BeatAPI uses one server-side API key across Text, Workflow, Realtime, Video, Image, and Effect APIs. Start with the three steps below, then use the rest of this guide for synchronous text responses, 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:

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. Wait data.poll_after_seconds between polls (5 for images, 8 for video and effects, 10 for data and workflows; it is present while the task runs). 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

Text calls return synchronously or as a server-sent event stream. Realtime creates a short-lived Session. Workflow, Video, Image, and Effect create operations return an asynchronous Task: store data.id, then poll the shared task endpoint. Polling GET /v1/tasks/{task_id} is not rate limited; wait poll_after_seconds between polls.

For GPT model selection, request formats, and streaming examples, see the GPT guide.

Get task status

GET /v1/tasks/{task_id}

Status values

Image and video tasks only use queued, processing, succeeded and failed. The other statuses belong to Music Video.

Normalized Task fields

Usage and output fields

On a failed task, usage.credits_reserved is the amount held at create, usage.credits_charged and usage.credits_settled are 0, and usage.credits_refunded is the amount returned. An accepted task fails with one of six codes: content_policy_violation and bad_request (not retryable), and processing_unavailable, processing_timeout, processing_failed and result_transfer_failed (retryable). See Errors.

Upload an input file

POST /v1/files

Use file upload when an input is local instead of already available at a public HTTPS URL. Every upload must include an exact Content-Length; normal curl, browser, and SDK uploads set it automatically. Chunked uploads without a declared length are rejected before the body is buffered.

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.

Some common aliases are accepted and stored under the canonical type, for example image/jpg as image/jpeg, audio/mp3 as audio/mpeg, and text/plain (with a .srt filename) as application/x-subrip. PDF, generic text, octet-stream, unsupported video containers, and ZIP uploads are refused with 400 bad_request. The gateway trusts the declared Content-Type; when the filename has an extension, it must agree with that type. It does not inspect the file contents and does not read duration or dimensions. A file accepted by the upload can still be refused by the model or workflow that uses it, for example for duration or size rules, when you create the task. Workflow input URLs cannot be localhost, private-network, or data URLs.

Upload refusals are 400 bad_request with one of these messages:

If the file cannot be stored, the upload answers 503 with processing_unavailable (“File storage is temporarily unavailable. Retry later; nothing was stored.”) or result_transfer_failed (“The file could not be stored on our side. Retry; nothing was stored.”). Retry with backoff.

File response

{
  "data": {
    "id": "file_6f1c2b9e-4d0a-4c58-9a57-2f0a8f3d7b11",
    "object": "file",
    "url": "https://media.beatapi.io/uploads/1042/6f1c2b9e-4d0a-4c58-9a57-2f0a8f3d7b11.mp3",
    "key": "uploads/1042/6f1c2b9e-4d0a-4c58-9a57-2f0a8f3d7b11.mp3",
    "mime_type": "audio/mpeg",
    "size_bytes": 1048576,
    "purpose": "input",
    "created_at": 1782210000
  }
}

Use data.url in the model or workflow request. The model or workflow checks its own limits when you create the task; for example, Standard Music Video accepts 10–180 seconds of audio and 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

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: at most 60 successful requests per 1 minute(s). Retry after 60 seconds.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 60
  }
}

Every error carries code, an English message that states the cause, and request_id; only a 429 rate_limit_exceeded also carries retry_after_seconds and the Retry-After header; a 503 has no known wait, so retry it with backoff. retryable is present for every code in the table below. Branch on it: false means the same call will fail again until you change it.

Public error codes

BeatAPI exposes only the stable public codes below. BeatAPI never names the supplier behind a model and does not pass on raw upstream bodies. Errors lists which code each failure produces at create and on an accepted task, and how the text endpoints fail before the model is called (this envelope) and during the call (the SDK’s native error shape, with BeatAPI codes for our own refusals and rewritten codes for failures on the model’s side). These values appear in response error.code. Terminal asynchronous failures may also return the applicable value in task error_code.

BeatAPI does not answer 502 or 504; one you still see came from the network edge, has no JSON body, and is retried like a 503.

Idempotency:

• Workflow, Image, Video, and Effect task creation accept an optional key, and so does POST /v1/capabilities/run. Realtime Session create requires it (up to 255 characters).
• A key is remembered for 24 hours. A key longer than 255 characters is 400 bad_request.
• The same key with a different body or path is 409 idempotency_conflict. So is the same key while the first request is still running.
• Repeating the identical request returns the stored response with the header Idempotent-Replayed: true.
• Only 2xx responses are stored, so after a 400 or 402 you can retry with the same key.

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 every poll_after_seconds and stop at the documented terminal or action state.
• Download and store the results you need to keep.
• Honor status codes, Retry-After, and retry_after_seconds.
• Verify webhook signatures against raw bytes before JSON parsing. Webhooks send only task.succeeded and task.failed, with 3 attempts (retries after 1 minute and 5 minutes). A task failed by the timeout sweep fires no event, so keep polling as the source of truth.
• 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.