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

# File Conversion

> Initiate a file conversion task using either an audio URL or file upload with optional format parameters and webhook callback.



## OpenAPI

````yaml POST /v1/file_convert
openapi: 3.1.0
info:
  title: Musicgpt API
  version: 1.0.0
  description: API for retrieving conversion details by ID.
servers:
  - url: https://api.musicgpt.com/api/public
    description: Production server
security: []
paths:
  /v1/file_convert:
    post:
      summary: Convert audio file to different format
      description: >-
        Initiate a file conversion task using either an audio URL or file upload
        with optional format parameters and webhook callback.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                audio_url:
                  type: string
                  description: URL of the audio file to convert
                  example: https://example.com/audio.mp3
                audio_file:
                  type: string
                  format: binary
                  description: Audio file to upload and convert directly
                target_format:
                  type: string
                  description: Target format for conversion
                  enum:
                    - mp3
                    - wav
                    - flac
                    - ogg
                    - aac
                    - webm
                  example: wav
                target_sr:
                  type: integer
                  description: >-
                    Target sample rate in Hz (optional) - can be any of [8000,
                    16000, 22050, 24000, 32000, 44100, 48000, 96000, 192000]
                  enum:
                    - 8000
                    - 16000
                    - 22050
                    - 24000
                    - 32000
                    - 44100
                    - 48000
                    - 96000
                    - 192000
                  default: 44100
                  example: 44100
                target_bit_depth:
                  type: integer
                  description: Target bit depth (16, 24, or 32)
                  enum:
                    - 16
                    - 24
                    - 32
                  example: 24
                webhook_url:
                  type: string
                  description: Callback URL for async processing results
                  example: https://your-webhook-url.com/callback
              required:
                - target_format
              anyOf:
                - required:
                    - audio_url
                - required:
                    - audio_file
      responses:
        '200':
          description: Successfully initiated file conversion
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  task_id:
                    type: string
                  conversion_id:
                    type: string
                  output_path:
                    type: string
                  credit_estimate:
                    type: number
                    format: float
                example:
                  success: true
                  task_id: convert789
                  conversion_id: conv456
                  output_path: https://storage.example.com/converted/audio.wav
                  credit_estimate: 100.1
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Either audio_url or audio_file must be provided
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Internal Server Error
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: Python
          source: >-
            import requests


            url = "https://api.musicgpt.com/api/public/v1/file_convert"

            headers = {
                "Authorization": "<<<api key>>>"
            }


            # Option 1: URL

            payload = {
                "audio_url": "https://example.com/audio.mp3",
                "target_format": "wav",
                "target_sr": 44100,
                "webhook_url": "https://your-webhook-url.com/callback"
            }

            response = requests.post(url, headers=headers, data=payload)

            print(response.json())


            # Option 2: File Upload

            # payload = {

            #     "target_format": "flac",

            #     "target_bit_depth": 24,

            #     "webhook_url": "https://your-webhook-url.com/callback"

            # }

            # with open("audio.mp3", "rb") as f:

            #     files = {"audio_file": f}

            #     response = requests.post(url, headers=headers, data=payload,
            files=files)

            # print(response.json())
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````