# beatra

> Capability-aggregating AI generation backend. REST API for currently available AI generation workflows, with preview and planned capabilities tracked separately in the roadmap.

Customers integrate via REST. There is no SDK — `Authorization: Bearer <api_key>` and standard HTTP headers. Use `X-Request-Id` for correlation; public HTTP headers do not expose internal routing or execution details. The chat endpoint is OpenAI-compatible (clients just swap `base_url` and key).

## Docs

- [Overview](https://docs.beatra.ai/en/docs/overview): What beatra is, what you can build today, and what's coming
- [Quickstart](https://docs.beatra.ai/en/docs/quickstart): 5-minute first call (curl + Python + Node)
- [Authentication](https://docs.beatra.ai/en/docs/authentication): API keys, regions, header conventions
- [How beatra works](https://docs.beatra.ai/en/docs/concepts): Release states, model selection, idempotency, errors, async task flows
- [Text & chat](https://docs.beatra.ai/en/docs/build/text-generation): OpenAI-compatible text generation with sync and streaming
- [Image generation](https://docs.beatra.ai/en/docs/build/image-generation): Preview: image generation (text-to-image and image-to-image)
- [Video generation](https://docs.beatra.ai/en/docs/build/video-generation): Planned: video generation workflows
- [Audio & speech](https://docs.beatra.ai/en/docs/build/audio-and-speech): Planned: speech synthesis, transcription, voices
- [Music generation](https://docs.beatra.ai/en/docs/build/music-generation): Preview: music generation from prompts and reference audio
- [API Reference](https://docs.beatra.ai/en/docs/api-reference): Full endpoint reference (auto-rendered from OpenAPI)
- [Chat API](https://docs.beatra.ai/en/docs/api-reference/chat): OpenAI-compatible text generation with sync and streaming modes
- [Models catalog API](https://docs.beatra.ai/en/docs/api-reference/models-catalog): List models and inspect capabilities
- [Music API](https://docs.beatra.ai/en/docs/api-reference/music): Preview endpoints for text-to-music and reference-audio music tasks
- [Uploads API](https://docs.beatra.ai/en/docs/api-reference/uploads): Preview single-shot source media upload endpoint
- [Tasks API](https://docs.beatra.ai/en/docs/api-reference/tasks): Preview async task lookup and cancellation endpoints
- [Go-live checklist](https://docs.beatra.ai/en/docs/resources/go-live-checklist): Pre-launch checklist for headers, models, retries, and security
- [Usage & limits](https://docs.beatra.ai/en/docs/resources/usage-and-limits): How beatra is billed and how request limits behave today
- [Errors & retries](https://docs.beatra.ai/en/docs/resources/errors-and-retries): Error envelope, retryable flag, idempotent retry rules
- [Error codes](https://docs.beatra.ai/en/docs/resources/error-codes): Public taxonomy with retryable flags + HTTP status mapping
- [Migrating from OpenAI](https://docs.beatra.ai/en/docs/resources/migrating-from-openai): Most callers can just change base_url + key
- [Roadmap](https://docs.beatra.ai/en/docs/roadmap): Release status for available, preview, and planned capabilities
- [Changelog](https://docs.beatra.ai/en/docs/changelog): What changed and when in the public contract
- [OpenAPI Spec](https://docs.beatra.ai/openapi.yaml): Machine-readable public contract for available and preview endpoints
- [OpenAPI JSON](https://docs.beatra.ai/openapi.json): Machine-readable contract as JSON
- [llms.txt](https://docs.beatra.ai/llms.txt): AI-agent discovery map for beatra docs

## Conventions

- All endpoints under `/v1`. MVP base URL: `https://api.beatra.ai`. Region fields remain in API keys/config for future multi-region expansion.
- Public OpenAPI lists only available, beta, and preview endpoints. Planned capabilities are documented in the roadmap and are not part of the callable contract until they appear in OpenAPI.
- Current callable endpoints are text chat, streaming chat, model/catalog discovery, public health, Preview image generation (text-to-image and image-to-image), Preview music generation, Preview single-shot uploads, and Preview task lookup/cancel. Use `stream: true` on `POST /v1/chat/completions` for Server-Sent Events ending with `data: [DONE]`.
- Video, speech, voices, resumable uploads, and customer callbacks are planned capabilities. Treat their docs as roadmap material until the endpoints appear in public OpenAPI.
- Errors use `{error: {code, message, retryable, ...}}`; `retryable: false` means changing the request, not waiting, will help.