> ## 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.

# Create a conversion

> Starts a new voice conversion job using either an Audimee built-in voice or one of your custom voice models. Conversions run asynchronously — the response returns immediately with the conversion `id`; poll `GET /conversions/{id}` for progress.

When using a custom voice model, the model must have finished training (`confirmedDone: true`). Calls against models that are still training or that failed training return `400`.



## OpenAPI

````yaml POST /conversions
openapi: 3.1.0
info:
  title: Audimee API
  description: >-
    The Audimee API lets clients browse voice models, train custom voices, and
    run AI voice conversions.
  version: 1.0.0
servers:
  - url: https://audimee.com/api/v1
security:
  - bearerAuth: []
paths:
  /conversions:
    post:
      tags:
        - Conversions
      summary: Create a conversion
      description: >-
        Starts a new voice conversion job using either an Audimee built-in voice
        or one of your custom voice models. Conversions run asynchronously — the
        response returns immediately with the conversion `id`; poll `GET
        /conversions/{id}` for progress.


        When using a custom voice model, the model must have finished training
        (`confirmedDone: true`). Calls against models that are still training or
        that failed training return `400`.
      operationId: createConversion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversionRequest'
            example:
              voiceModelId: '101'
              inputFileUrl: https://example.com/audio/my-recording.wav
              conversionStrength: 0.7
              pitchShift: 3
      responses:
        '200':
          description: Conversion job queued. Poll `GET /conversions/{id}` for progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConversionResponse'
              example:
                id: 457d147e-e0c4-4b92-a731-92bbc8b7ab22
        '400':
          description: >-
            Invalid body, or the referenced custom voice model is still training
            / failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                stillTraining:
                  summary: Custom model still training
                  value:
                    error: Custom voice model is still training
                trainingFailed:
                  summary: Custom model training failed
                  value:
                    error: >-
                      Custom voice model training failed: Training audio quality
                      too low
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Voice model not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Voice model not found
        '500':
          description: >-
            Failed to resolve the voice model, download or process the input
            audio, or persist the conversion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                downloadFailed:
                  summary: Could not download the input audio
                  value:
                    error: Failed to download audio file
                lengthFailed:
                  summary: Could not read audio length
                  value:
                    error: Failed to get audio length
                uploadFailed:
                  summary: Could not upload to storage
                  value:
                    error: Failed to upload file
                createFailed:
                  summary: Could not create the conversion
                  value:
                    error: Failed to create conversion
components:
  schemas:
    CreateConversionRequest:
      type: object
      required:
        - voiceModelId
        - inputFileUrl
      properties:
        voiceModelId:
          type: string
          description: >-
            ID of the voice model to use. Accepts both Audimee built-in IDs
            (numeric strings) and your own custom model UUIDs.
        inputFileUrl:
          type: string
          description: >-
            URL to the audio file to convert. The server downloads it
            server-side, so the URL must be reachable from the public internet
            for the duration of the request.
        conversionStrength:
          type: number
          minimum: 0
          maximum: 1
          default: 0.3
          description: >-
            Strength of the voice conversion effect, `0.0`–`1.0`. Defaults to
            `0.3` when omitted.
        pitchShift:
          type: integer
          minimum: -24
          maximum: 24
          default: 0
          description: >-
            Pitch shift applied during conversion, in semitones. Whole numbers
            between `-24` and `24`. Defaults to `0`.
        sampleRateHz:
          type: integer
          enum:
            - 44100
            - 48000
          default: 44100
          description: Output sample rate. Either `44100` or `48000`. Defaults to `44100`.
    CreateConversionResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: UUID of the queued conversion job.
    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}`.

````