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

# Analyse audio

> Measures the vocal range of the singer in an audio file. Compare `pitchRange` with a voice model's `pitchRange` to choose a `pitchShift` for the conversion, and use `effectsDetection` to judge whether the audio is clean enough to convert well. The call is synchronous — the response carries the result.

`audioUrl` must be an `http` or `https` URL. Supported formats: `wav`, `mp3`, `flac`, `ogg`, `m4a`, `aif` and `aiff` — detected from the URL extension when present, otherwise from the downloaded file itself.



## OpenAPI

````yaml POST /audio-analysis
openapi: 3.1.0
info:
  title: Audimee API
  description: >-
    The Audimee API lets clients browse voice models, train custom voices, run
    AI voice conversions, and create multi-voice harmonies.
  version: 1.0.0
servers:
  - url: https://audimee.com/api/v1
security:
  - bearerAuth: []
paths:
  /audio-analysis:
    post:
      tags:
        - Audio Analysis
      summary: Analyse audio
      description: >-
        Measures the vocal range of the singer in an audio file. Compare
        `pitchRange` with a voice model's `pitchRange` to choose a `pitchShift`
        for the conversion, and use `effectsDetection` to judge whether the
        audio is clean enough to convert well. The call is synchronous — the
        response carries the result.


        `audioUrl` must be an `http` or `https` URL. Supported formats: `wav`,
        `mp3`, `flac`, `ogg`, `m4a`, `aif` and `aiff` — detected from the URL
        extension when present, otherwise from the downloaded file itself.
      operationId: createAudioAnalysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAudioAnalysisRequest'
            example:
              audioUrl: https://example.com/audio/my-recording.wav
      responses:
        '200':
          description: The analysis result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioAnalysis'
              examples:
                rangeMeasured:
                  summary: Vocal range measured on a clean vocal
                  value:
                    pitchRange:
                      low: 52
                      high: 69
                    effectsDetection:
                      instrumental: false
                      reverbEcho: false
                effectsDetected:
                  summary: Instruments detected, analysis skipped
                  value:
                    pitchRange: null
                    effectsDetection:
                      instrumental: true
                      reverbEcho: true
                rangeNotMeasured:
                  summary: Vocal range could not be measured
                  value:
                    pitchRange: null
                    effectsDetection: null
        '400':
          description: >-
            Invalid body, non-http(s) URL, or audio longer than the conversion
            limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidUrl:
                  summary: Not a URL
                  value:
                    error: 'audioUrl: Invalid url'
                unsupportedProtocol:
                  summary: Not http or https
                  value:
                    error: 'audioUrl: Must be an http or https URL'
                audioTooLong:
                  summary: Audio longer than the conversion limit
                  value:
                    error: Audio length exceeds the maximum of 7 minutes
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: The audio could not be downloaded or analysed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Failed to analyse audio
components:
  schemas:
    CreateAudioAnalysisRequest:
      type: object
      required:
        - audioUrl
      properties:
        audioUrl:
          type: string
          format: uri
          description: >-
            Publicly reachable `http` or `https` URL of the audio file. A
            supported audio extension in the URL helps format detection but is
            not required.
    AudioAnalysis:
      type: object
      required:
        - pitchRange
        - effectsDetection
      properties:
        pitchRange:
          type:
            - object
            - 'null'
          description: >-
            Vocal range of the singer as MIDI note numbers — the same unit as a
            voice model's `pitchRange`. `null` when the range could not be
            measured.
          required:
            - low
            - high
          properties:
            low:
              type: number
            high:
              type: number
        effectsDetection:
          type:
            - object
            - 'null'
          description: >-
            Effects detected on the audio, using the same thresholds as the web
            app's quality check. A `true` flag means the audio contains signals
            that degrade conversion quality — consider isolating the vocal
            before converting. `null` when the backend response carried no
            effects signals.
          required:
            - instrumental
            - reverbEcho
          properties:
            instrumental:
              type: boolean
              description: true when instruments were detected alongside the vocal.
            reverbEcho:
              type: boolean
              description: true when reverb or echo was detected on the vocal.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable explanation of what went wrong.
  responses:
    Unauthorized:
      description: Missing, malformed, or unrecognised bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingHeader:
              summary: No Authorization header
              value:
                error: Missing or invalid Authorization header
            invalidToken:
              summary: Token not recognised
              value:
                error: Invalid authorization token
            userNotFound:
              summary: Token valid but user no longer exists
              value:
                error: User not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Static API key issued by Audimee, passed as `Authorization: Bearer
        {token}`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.