BeatAPI Text API

openapi: 3.2.0
info:
  title: BeatAPI Developer Text API
  version: 1.0.0-launch
  license:
    name: BeatAPI Terms of Service
    url: https://beatapi.io/terms-of-service
  description: 'BeatAPI provides one API key for public text models, image generation, video generation,

    video analysis, Effects, asynchronous video workflows, and short-lived Realtime Video Sessions.


    For asynchronous operations, create a task, poll the shared task endpoint or receive webhook events,

    and read hosted output URLs from `output.media`. For Realtime, create a Session on a trusted server

    with your Bearer API key and pass only the returned short-lived `client_secret` to the browser.


    Customer balances and usage are USD-denominated. Compatibility fields such

    as `credit_balance` and `credits_reserved` remain in the API; 1 Credit = $1 USD.


    ## 5 minute Quick Start


    1. Set your base URL to `https://api.beatapi.io`.

    2. Create an API key in Dashboard → API Keys

    and send it as

    `Authorization: Bearer `.

    USD balance top-ups are available from

    Dashboard → Billing.

    3. Use public HTTPS URLs for input media. If your files are local, upload

    them with `POST /v1/files` first.

    4. Create a workflow task.

    5. Poll every 5-10 seconds until `status` is `succeeded` or `failed`.

    6. Add webhooks later if you do not want to poll.


    ```bash

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

    export BEATAPI_API_KEY


    curl https://api.beatapi.io/v1/workflows


    curl https://api.beatapi.io/v1/music-video/tasks \

    -H "Authorization: Bearer $BEATAPI_API_KEY" \

    -H "Content-Type: application/json" \

    -d ''{

    "images": ["https://cdn.beatapi.io/samples/neon-singer.png"],

    "audio_url": "https://cdn.beatapi.io/samples/neon-singer-preview.mp3",

    "prompt": "Neon rooftop performance with cinematic light trails.",

    "language": "en",

    "resolution": "720p"

    }''


    curl https://api.beatapi.io/v1/tasks/task_8K2qA \

    -H "Authorization: Bearer $BEATAPI_API_KEY"

    ```


    ## How tasks work


    A task starts as `queued` or `processing`. Keep polling

    `GET /v1/tasks/{task_id}` every 5-10 seconds with a little jitter. Stop when

    the task is `succeeded` or `failed`.


    - `queued`: accepted and waiting for platform capacity.

    - `processing`: generation is running.

    - `storyboard_ready`: Music Video storyboard shots are available.

    - `requires_action`: choose storyboard shots and call compose.

    - `editing`: a storyboard shot edit is running.

    - `composing`: selected storyboard shots are being composed.

    - `succeeded`: output is ready in `output.media[]`.

    - `failed`: no usable output was produced. Inspect `error_code`,

    `error_message`, and `usage` for the final task result.


    The current 10 minute processing window is an operational timeout for launch

    testing, not a completion SLA.


    ## Inputs and limits


    Public workflow inputs must use HTTPS URLs that are reachable from the

    public internet. Localhost, private network URLs, and data URLs are rejected.

    Use `POST /v1/files` for local images, audio, subtitles, or Motion Control reference videos.


    Each verified new user account starts with a $2 welcome balance that never expires and

    1 active processing concurrency. Lifetime paid purchases unlock higher limits:

    $10+ = 2, $100+ = 5, $1,000+ = 10, $5,000+ = 15, and $20,000+ = 30.

    `GET /v1/usage` returns current usage totals, concurrency limit, and active

    processing task count. Active concurrency measures tasks that are currently

    using BeatAPI processing resources. storyboard_ready and requires_action

    tasks can have settled USD usage but do not count toward active processing

    concurrency.


    ## Webhooks are optional


    Polling is the simplest integration path. If you add webhooks, BeatAPI sends

    `task.succeeded` and `task.failed` events. Webhook delivery failures do not

    change task status; polling remains the source of truth.'
servers:
- url: https://api.beatapi.io
tags:
- name: Text
  description: Discover enabled text models and call them through OpenAI, Anthropic, or Gemini-compatible request formats.
paths:
  /v1/models:
    get:
      operationId: listTextModels
      tags:
      - Text
      summary: List available text models
      description: Returns the text models currently enabled for this BeatAPI environment in OpenAI list format.
      security:
      - BearerAuth: []
      - ApiKeyHeader: []
      - GoogleApiKeyHeader: []
      responses:
        '200':
          description: OpenAI-compatible model list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextModelList'
              example:
                object: list
                data:
                - id: gpt-5.6-sol
                  object: model
                  created: 1788220800
                  owned_by: beatapi
                - id: gpt-5.6-terra
                  object: model
                  created: 1788220800
                  owned_by: beatapi
                - id: gpt-5.6-luna
                  object: model
                  created: 1788220800
                  owned_by: beatapi
                - id: claude-fable-5-1
                  object: model
                  created: 1788220800
                  owned_by: beatapi
        '401':
          $ref: '#/components/responses/TextUnauthorized'
        '404':
          description: Text API is not enabled for this environment (`not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextError'
        '429':
          $ref: '#/components/responses/TextRateLimited'
        '503':
          $ref: '#/components/responses/TextUnavailable'
  /v1/responses:
    post:
      operationId: createTextResponse
      tags:
      - Text
      summary: Create a text response
      description: Recommended OpenAI-compatible surface for reasoning, tools, structured outputs, and streaming. Unknown request fields are ignored, as on the OpenAI API; `POST /v1/capabilities/run` refuses them.
      security:
      - BearerAuth: []
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextPassthroughRequest'
            example:
              model: gpt-5.6-sol
              input: Design a resilient webhook retry strategy for a payments API.
              reasoning:
                effort: medium
              stream: true
      responses:
        '200':
          description: OpenAI-compatible JSON response or server-sent event stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextPassthroughResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/TextBadRequest'
        '401':
          $ref: '#/components/responses/TextUnauthorized'
        '402':
          $ref: '#/components/responses/TextInsufficientCredits'
        '403':
          $ref: '#/components/responses/TextForbidden'
        '404':
          $ref: '#/components/responses/TextNotFound'
        '429':
          $ref: '#/components/responses/TextRateLimited'
        '500':
          $ref: '#/components/responses/TextInternalError'
        '503':
          $ref: '#/components/responses/TextUnavailable'
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      tags:
      - Text
      summary: Create a text chat completion
      description: OpenAI Chat Completions-compatible endpoint for existing SDK integrations. Unknown request fields are ignored, as on the OpenAI API; `POST /v1/capabilities/run` refuses them.
      security:
      - BearerAuth: []
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextPassthroughRequest'
            example:
              model: gpt-5.6-terra
              messages:
              - role: user
                content: Summarize the attached product requirements into an implementation plan.
              stream: true
      responses:
        '200':
          description: OpenAI-compatible JSON response or server-sent event stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextPassthroughResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/TextBadRequest'
        '401':
          $ref: '#/components/responses/TextUnauthorized'
        '402':
          $ref: '#/components/responses/TextInsufficientCredits'
        '403':
          $ref: '#/components/responses/TextForbidden'
        '404':
          $ref: '#/components/responses/TextNotFound'
        '429':
          $ref: '#/components/responses/TextRateLimited'
        '500':
          $ref: '#/components/responses/TextInternalError'
        '503':
          $ref: '#/components/responses/TextUnavailable'
  /v1/messages:
    post:
      operationId: createMessage
      tags:
      - Text
      summary: Create an Anthropic-compatible message
      description: Anthropic Messages-compatible endpoint. Send the BeatAPI key with x-api-key or Bearer authentication. Unknown request fields are ignored by this gateway; `POST /v1/capabilities/run` refuses them.
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextPassthroughRequest'
            example:
              model: gpt-5.6-luna
              max_tokens: 1024
              messages:
              - role: user
                content: Classify this support request and return JSON.
      responses:
        '200':
          description: Anthropic-compatible JSON response or server-sent event stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextPassthroughResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/TextBadRequest'
        '401':
          $ref: '#/components/responses/TextUnauthorized'
        '402':
          $ref: '#/components/responses/TextInsufficientCredits'
        '403':
          $ref: '#/components/responses/TextForbidden'
        '404':
          $ref: '#/components/responses/TextNotFound'
        '429':
          $ref: '#/components/responses/TextRateLimited'
        '500':
          $ref: '#/components/responses/TextInternalError'
        '503':
          $ref: '#/components/responses/TextUnavailable'
  /v1beta/models/{model}:{action}:
    post:
      operationId: generateGeminiCompatibleContent
      tags:
      - Text
      summary: Generate text content with a Gemini-compatible request
      description: Gemini-compatible endpoint for generateContent and streamGenerateContent. The BeatAPI key is removed before forwarding.
      security:
      - GoogleApiKeyHeader: []
      - GoogleApiKeyQuery: []
      - BearerAuth: []
      parameters:
      - in: path
        name: model
        required: true
        schema:
          $ref: '#/components/schemas/TextModelId'
      - in: path
        name: action
        required: true
        schema:
          type: string
          enum:
          - generateContent
          - streamGenerateContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            example:
              contents:
              - role: user
                parts:
                - text: Explain this architecture decision in three concise bullets.
      responses:
        '200':
          description: Gemini-compatible JSON response or server-sent event stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextPassthroughResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/TextBadRequest'
        '401':
          $ref: '#/components/responses/TextUnauthorized'
        '402':
          $ref: '#/components/responses/TextInsufficientCredits'
        '403':
          $ref: '#/components/responses/TextForbidden'
        '404':
          $ref: '#/components/responses/TextNotFound'
        '429':
          $ref: '#/components/responses/TextRateLimited'
        '500':
          $ref: '#/components/responses/TextInternalError'
        '503':
          $ref: '#/components/responses/TextUnavailable'
components:
  responses:
    TextUnavailable:
      description: The request could not be completed (`processing_unavailable`, `processing_timeout` or `processing_failed`). Nothing was charged. Retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
    TextInternalError:
      description: Unexpected internal error (`internal_error`). Retryable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
    TextNotFound:
      description: Unknown model (`not_found`). List the enabled models with `GET /v1/models`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
    TextForbidden:
      description: The key or account is not permitted to use this model (`forbidden`), for example a model that is not available on free credit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
    TextBadRequest:
      description: Malformed JSON or an unsupported field (`bad_request`), or input refused by moderation (`content_policy_violation`). Not retryable unchanged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
    TextRateLimited:
      description: Too many requests (`rate_limit_exceeded`, including the free-model limits). Retry after `Retry-After` seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
    TextUnauthorized:
      description: No API key (`missing_api_key`), or a key that is wrong, expired, disabled or exhausted (`invalid_api_key`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
    TextInsufficientCredits:
      description: Insufficient balance (`insufficient_credits`). The account balance is zero or below the price of this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextError'
  schemas:
    TextModel:
      type: object
      additionalProperties: false
      required:
      - id
      - object
      - created
      - owned_by
      properties:
        id:
          $ref: '#/components/schemas/TextModelId'
        object:
          type: string
          const: model
        created:
          type: integer
          example: 1788220800
        owned_by:
          type: string
          const: beatapi
    TextModelId:
      type: string
      description: Public text model id exposed by BeatAPI. Call GET /v1/models to discover the models enabled for your environment.
    TextPassthroughRequest:
      type: object
      description: SDK-compatible text request. BeatAPI preserves the supported fields of the chosen wire format and streams the matching response format back.
      required:
      - model
      properties:
        model:
          $ref: '#/components/schemas/TextModelId'
      additionalProperties: true
    TextError:
      description: 'Text endpoint error in the native wire format, so an SDK raises its usual exception: the OpenAI shape on /v1/models, /v1/chat/completions, /v1/responses and the Gemini-compatible endpoint, the Anthropic shape on /v1/messages. The HTTP status and the English message follow the same code table as every other BeatAPI endpoint.'
      oneOf:
      - $ref: '#/components/schemas/OpenAITextError'
      - $ref: '#/components/schemas/AnthropicTextError'
    AnthropicTextError:
      type: object
      required:
      - type
      - error
      properties:
        type:
          type: string
          const: error
        error:
          type: object
          required:
          - type
          - message
          properties:
            type:
              type: string
            message:
              type: string
              description: English sentence that states the cause.
    TextPassthroughResponse:
      type: object
      description: Response body in the selected SDK-compatible wire format.
      additionalProperties: true
    OpenAITextError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              description: English sentence that states the cause.
            type:
              type: string
            code:
              type: string
              description: BeatAPI error code, for example `insufficient_credits` or `rate_limit_exceeded`.
    TextModelList:
      type: object
      additionalProperties: false
      required:
      - object
      - data
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/TextModel'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_xxx
      description: 'Send your API key as `Authorization: Bearer <BEATAPI_API_KEY>`.'
    PersonalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: nap_xxx
      description: 'Send the account''s personal access token as `Authorization: Bearer <token>`. Create it on the Dashboard''s Account security page. API keys are not accepted.'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Anthropic-compatible API key header. Use a BeatAPI API key.
    GoogleApiKeyHeader:
      type: apiKey
      in: header
      name: x-goog-api-key
      description: Gemini-compatible API key header. Use a BeatAPI API key.
    GoogleApiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: Gemini SDK compatibility only. Prefer the x-goog-api-key header when possible.
externalDocs:
  description: BeatAPI documentation
  url: https://docs.beatapi.io