> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Songs

> Analyze music using a state-of-the-art Audio Language Model that listens directly to the audio waveform. Unlike text-based AI, this model processes the actual sound — identifying harmony, structure, timbre, lyrics, and cultural context through deep music understanding. Supports audio up to 20 minutes (MP3, WAV, FLAC). Two modes: (1) **Presets** — pass a `preset` name like `catalog_metadata`, `mood_tags`, or `full_report` for structured, optimized output. (2) **Custom prompt** — pass a `prompt` for free-form questions. The `full_report` preset runs all 13 presets in parallel and returns a comprehensive music intelligence report. Use `GET /api/songs/analyze/presets` to list available presets.



## OpenAPI

````yaml api-reference/openapi/releases.json POST /api/songs/analyze
openapi: 3.1.0
info:
  title: Recoup API - Releases
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/songs/analyze:
    post:
      description: >-
        Analyze music using a state-of-the-art Audio Language Model that listens
        directly to the audio waveform. Unlike text-based AI, this model
        processes the actual sound — identifying harmony, structure, timbre,
        lyrics, and cultural context through deep music understanding. Supports
        audio up to 20 minutes (MP3, WAV, FLAC). Two modes: (1) **Presets** —
        pass a `preset` name like `catalog_metadata`, `mood_tags`, or
        `full_report` for structured, optimized output. (2) **Custom prompt** —
        pass a `prompt` for free-form questions. The `full_report` preset runs
        all 13 presets in parallel and returns a comprehensive music
        intelligence report. Use `GET /api/songs/analyze/presets` to list
        available presets.
      requestBody:
        description: Music analysis request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SongAnalyzeRequest'
      responses:
        '200':
          description: Music analysis completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SongAnalyzeResponse'
        '400':
          description: Bad request — missing or invalid fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SongAnalyzeErrorResponse'
        '401':
          description: Unauthorized — invalid or missing API key / Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SongAnalyzeErrorResponse'
        '500':
          description: Server error — upstream model unavailable or inference failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SongAnalyzeErrorResponse'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    SongAnalyzeRequest:
      type: object
      description: >-
        Provide exactly one of `preset` or `prompt`. Use `preset` for structured
        analysis workflows, or `prompt` for free-form questions.
      properties:
        preset:
          type: string
          enum:
            - catalog_metadata
            - mood_tags
            - lyric_transcription
            - mix_feedback
            - song_description
            - music_theory
            - similar_artists
            - sample_detection
            - sync_brief_match
            - audience_profile
            - content_advisory
            - playlist_pitch
            - artist_development_notes
            - full_report
          description: >-
            Name of a curated analysis preset. Use instead of prompt for
            structured, optimized output. The 'full_report' preset runs all 13
            presets in parallel and returns a comprehensive report. See [List
            Analyze Presets](/api-reference/songs/analyze-presets) for the full
            list of available presets.
          example: catalog_metadata
        prompt:
          type: string
          minLength: 1
          maxLength: 24000
          description: Text prompt or question about the music
          example: Describe the genre, tempo, and mood of this track.
        audio_url:
          type: string
          format: uri
          description: Public URL to an audio file (MP3, WAV, or FLAC — up to 20 minutes)
          example: https://example.com/song.mp3
        max_new_tokens:
          type: integer
          minimum: 1
          maximum: 2048
          default: 512
          description: Maximum number of tokens to generate
          example: 512
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
          description: >-
            Controls output creativity — higher values produce more varied
            responses
          example: 0.7
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Nucleus sampling probability cutoff
          example: 0.9
        do_sample:
          type: boolean
          default: false
          description: Enable sampling (set true when using temperature or top_p)
          example: false
    SongAnalyzeResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
          description: Request status
        preset:
          type: string
          description: Preset used for analysis, when applicable
          example: catalog_metadata
        response:
          description: >-
            Model output for single-preset or custom-prompt analysis. May be
            plain text or structured JSON depending on the preset.
        report:
          type: object
          description: >-
            Full report payload returned only when using the `full_report`
            preset
        elapsed_seconds:
          type: number
          format: float
          description: Inference time in seconds
    SongAnalyzeErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
          description: Error status
        missing_fields:
          type: array
          description: Path to the first invalid or missing field when validation fails
          items:
            type: string
        error:
          type: string
          description: Error message describing what went wrong
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Recoup API key. [Learn more](/quickstart#api-keys).
    bearerAuth:
      type: http
      scheme: bearer

````