openapi: 3.1.0
info:
  title: Beatoven Composition Tasks 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: Tasks
  description: Poll asynchronous composition task status and retrieve generated assets.
paths:
  /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:
  responses:
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid Bearer API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    StemUrls:
      type: object
      properties:
        bass:
          type: string
          format: uri
        chords:
          type: string
          format: uri
        melody:
          type: string
          format: uri
        percussion:
          type: string
          format: uri
    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
    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'
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Beatoven API token, issued by hello@beatoven.ai or from the API dashboard.