BeatAPI Workflows API

openapi: 3.2.0
info:
  title: BeatAPI Developer Workflows 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: Workflows
  description: Discover the workflow IDs available for task creation.
paths:
  /v1/workflows:
    get:
      operationId: listWorkflows
      tags:
      - Workflows
      x-apidog-folder: Reference/API Overview
      summary: List launch workflows
      security: []
      responses:
        '200':
          description: Workflow list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowListResponse'
              example:
                data:
                  object: list
                  data:
                  - id: music-video
                    object: workflow
                    name: Music Video API
                    description: Generate short music video clips from audio, lyrics, and visual direction.
                  - id: ecommerce-video
                    object: workflow
                    name: Ecommerce Video API
                    description: Generate product ad videos from product images and a short creative brief.
                  - id: video-analysis
                    object: workflow
                    name: Video Analysis API
                    description: Analyze an uploaded video with timestamp-aware multimodal reasoning.
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Workflow:
      type: object
      required:
      - id
      - object
      - name
      - description
      properties:
        id:
          type: string
          enum:
          - music-video
          - ecommerce-video
          - video-analysis
          example: music-video
        object:
          type: string
          enum:
          - workflow
        name:
          type: string
          example: Music Video API
        description:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support.
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
              description: 'Stable machine-readable error code. `unauthorized` is the legacy name for a 401; since 2026-09-29 a 401 is `missing_api_key` or `invalid_api_key`, but `unauthorized` may still appear. Treat it like `invalid_api_key`. `result_expired` is returned only by `POST /v1/capabilities/run` with `operation: "result"`.'
              enum:
              - bad_request
              - missing_api_key
              - invalid_api_key
              - unauthorized
              - forbidden
              - not_found
              - insufficient_credits
              - idempotency_conflict
              - rate_limit_exceeded
              - content_policy_violation
              - processing_unavailable
              - processing_failed
              - processing_timeout
              - result_transfer_failed
              - result_expired
              - not_implemented
              - realtime_disabled
              - realtime_capacity_unavailable
              - realtime_session_expired
              - origin_not_allowed
              - invalid_client_secret
              - transport_not_allowed
              - internal_error
            message:
              type: string
              description: English sentence that states the cause; for `bad_request` it names the field. Written for people and logs, not for parsing.
            retryable:
              type: boolean
              description: Whether making the same call again could succeed. Present for every code in the public table; it may be absent only for a code outside the table. True for rate_limit_exceeded, internal_error, processing_unavailable, processing_timeout, processing_failed, result_transfer_failed and realtime_capacity_unavailable. False for a request, key or balance that must change first (bad_request, content_policy_violation, missing_api_key, invalid_api_key, unauthorized, insufficient_credits, forbidden, not_found, idempotency_conflict, result_expired, not_implemented, realtime_disabled and the other realtime credential codes).
            request_id:
              type: string
              description: Correlation ID to retain for BeatAPI support.
            retry_after_seconds:
              type: integer
              description: Seconds to wait before retrying. Sent only with a 429 `rate_limit_exceeded`, and the same value is sent in the `Retry-After` header. No other code carries it.
            docs:
              type: string
              format: uri
              description: The public Skill page that says what to do about an error. Present on errors answered by the capability endpoints (`/v1/capabilities/search`, `/v1/capabilities/inspect`, `/v1/capabilities/run`); absent on every other endpoint.
    WorkflowListResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/WorkflowList'
    WorkflowList:
      type: object
      required:
      - object
      - data
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'
  responses:
    RateLimited:
      description: Too many requests (`rate_limit_exceeded`, including the free-model limits). Retryable after `Retry-After` seconds (also `error.retry_after_seconds`).
      headers:
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limit_exceeded
              message: Too many polling requests. Poll every 5-10 seconds.
              retryable: true
              request_id: req_xxx
              retry_after_seconds: 12
  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