openapi: 3.1.0
info:
  title: Beatoven Composition API
  description: >
    Public REST API for Beatoven.ai's text-to-music generation. Submit a
    natural language prompt and receive an asynchronously composed track with
    downloadable master mix and individual stems (bass, chords, melody,
    percussion). The API is asynchronous: POST a composition request to receive
    a task_id, then poll the task endpoint until status is "composed".
  version: v1
  contact:
    name: Beatoven.ai Support
    email: hello@beatoven.ai
    url: https://www.beatoven.ai/api
  license:
    name: Beatoven.ai Terms of Service
    url: https://www.beatoven.ai/tos
servers:
  - url: https://public-api.beatoven.ai
    description: Beatoven public API production server
security:
  - BearerAuth: []
tags:
  - name: Tracks
    description: Compose new tracks from natural language prompts.
  - name: Tasks
    description: Poll asynchronous composition task status and retrieve generated assets.
paths:
  /api/v1/tracks/compose:
    post:
      summary: Compose A Track From A Prompt
      description: >
        Start an asynchronous track composition from a text prompt. Returns a
        task_id that can be polled at /api/v1/tasks/{task_id} until the
        track is composed.
      operationId: composeTrack
      tags:
        - Tracks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComposeRequest'
            examples:
              LoFiChillHop:
                summary: 30-second peaceful lo-fi prompt
                value:
                  prompt:
                    text: 30 seconds peaceful lo-fi chill hop track
                  format: wav
                  looping: false
      responses:
        '200':
          description: Composition task accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComposeResponse'
              examples:
                Started:
                  value:
                    status: started
                    task_id: ccb84650-7b4a-4d00-9f80-8a6427ca21aa_1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/v1/tasks/{task_id}:
    get:
      summary: Get Composition Task Status
      description: >
        Retrieve the current status of an asynchronous composition task.
        While the task is queued the status is "composing", once execution
        begins it is "running", and once finished it is "composed" and the
        response includes URLs for the master track and individual stems.
      operationId: getTaskStatus
      tags:
        - Tasks
      parameters:
        - name: task_id
          in: path
          required: true
          description: Task identifier returned by POST /api/v1/tracks/compose.
          schema:
            type: string
            example: ccb84650-7b4a-4d00-9f80-8a6427ca21aa_1
      responses:
        '200':
          description: Current task status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatus'
              examples:
                Composing:
                  value:
                    status: composing
                Composed:
                  value:
                    status: composed
                    meta:
                      project_id: 3ade3151-372d-4ac8-b1ef-866a67ef0875
                      track_id: ccb84650-7b4a-4d00-9f80-8a6427ca21aa
                      prompt:
                        text: 30 seconds peaceful lo-fi chill hop track
                      version: 1
                      track_url: https://cdn.beatoven.ai/tracks/example.wav
                      stems_url:
                        bass: https://cdn.beatoven.ai/stems/bass.wav
                        chords: https://cdn.beatoven.ai/stems/chords.wav
                        melody: https://cdn.beatoven.ai/stems/melody.wav
                        percussion: https://cdn.beatoven.ai/stems/percussion.wav
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Task not found.
        '500':
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Beatoven API token, issued by hello@beatoven.ai or from the API dashboard.
  schemas:
    Prompt:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Natural language prompt describing the desired track (genre, mood, length, instruments).
          example: 30 seconds peaceful lo-fi chill hop track
    ComposeRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          $ref: '#/components/schemas/Prompt'
        format:
          type: string
          enum:
            - mp3
            - aac
            - wav
          default: wav
          description: Audio container for the rendered track.
        looping:
          type: boolean
          default: false
          description: Set true to bias the composition toward loopable structure.
    ComposeResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - started
          description: Indicates the composition task has been accepted.
        task_id:
          type: string
          description: Identifier used to poll composition progress.
    StemUrls:
      type: object
      properties:
        bass:
          type: string
          format: uri
        chords:
          type: string
          format: uri
        melody:
          type: string
          format: uri
        percussion:
          type: string
          format: uri
    TaskMeta:
      type: object
      properties:
        project_id:
          type: string
        track_id:
          type: string
        prompt:
          $ref: '#/components/schemas/Prompt'
        version:
          type: integer
        track_url:
          type: string
          format: uri
          description: Pre-signed URL to download the rendered master track.
        stems_url:
          $ref: '#/components/schemas/StemUrls'
    TaskStatus:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - composing
            - running
            - composed
          description: composing = queued, running = in progress, composed = finished.
        meta:
          $ref: '#/components/schemas/TaskMeta'
    Error:
      type: object
      properties:
        error:
          type: string
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid Bearer API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'