> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wav.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.
Convert audio files to different formats with optional webhook support for asynchronous updates.
***
## Endpoint
```http theme={null}
POST /v1/file_convert
```
This endpoint processes an uploaded or linked audio file and converts it to a specified output format. You may also define optional parameters like sample rate and bit depth.
***
## Request Parameters
| Parameter | Type | Required | Description |
| ------------------ | --------- | -------- | ----------------------------------------------------------------------------------------- |
| `audio_url` | `String` | Optional | The URL of an audio file to convert. Either `audio_url` or `audio_file` must be provided. |
| `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. |
| `target_format` | `String` | Yes | Desired output format. Supported: `mp3`, `wav`, `flac`, `ogg`, `aac`, `webm`. |
| `target_sr` | `Integer` | Optional | Target sample rate in Hz. Defaults to original if not specified. |
| `target_bit_depth` | `Integer` | Optional | Target bit depth. Options: `16`, `24`, `32`. Defaults to `16`. |
| `webhook_url` | `String` | Optional | Callback URL to receive the result once conversion is complete. |
> **content-type:** multipart/form-data
***
## Sample Output
Listen to a real sample output:
Download Audio
***
## Try it Yourself
Visit the [File Conversion Endpoint Explorer](/api-documentation/endpoint/fileconvert) to try your own text samples.
***
## Sample Request
### cURL
```bash theme={null}
curl -X POST \
-F "audio_file=@input.mp3" \
-F "target_format=wav" \
-F "target_sr=44100" \
-F "webhook_url=https://yourdomain.com/webhook" \
https://api.wav.com/api/public/v1/convert
```
### Python
```python theme={null}
import requests
url = "https://api.wav.com/api/public/v1/file_convert"
headers = {
"Authorization": ""
}
data = {
"target_format": "wav",
"target_sr": 44100,
"webhook_url": "https://example.com/my-webhook"
}
# Option 1: audio_url
data["audio_url"] = ""
response = requests.post(url, headers=headers, data=data)
# Option 2: File Upload
# with open("song.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())
```
***
## Sample Response
### Success (200 OK)
```json theme={null}
{
"success":true,
"task_id":"7024eac0-02e2-4811-96e3-7031f007f97f",
"conversion_id":"a1286a84-d886-47d9-a717-77af15894cb9",
"eta":-1,
"credit_estimate":19.833,
"message":"",
"status":"IN_QUEUE"
}
```
***
## Webhook Response
```json theme={null}
{
"success": true,
"conversion_id": "a1286a84-d886-47d9-a717-77af15894cb9",
"output_file_path": "https://cdn1.wav.com/FileConversions/standard/3567f876-a196-467f-8538-f12ef1ba318e.mp3",
"conversion_type": "File Conversion",
"task_id": "7024eac0-02e2-4811-96e3-7031f007f97f",
"message": "File conversion completed"
}
```
***
## Common Errors
* **400 Bad Request**: Invalid request. Possibly due to missing parameters or unsupported formats.
* **500 Internal Server Error**: Server encountered an error during processing.
***
## OpenAPI
````yaml POST /v1/file_convert
openapi: 3.1.0
info:
title: WAV API
version: 1.0.0
description: API for retrieving conversion details by ID.
servers:
- url: https://api.wav.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: 'Input audio URL (supported format: YouTube URL).'
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 task
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
task_id:
type: string
conversion_id:
type: string
eta:
type: integer
credit_estimate:
type: number
message:
type: string
status:
type: string
example:
success: true
task_id: 7024eac0-02e2-4811-96e3-7031f007f97f
conversion_id: a1286a84-d886-47d9-a717-77af15894cb9
eta: -1
credit_estimate: 19.833
message: ''
status: IN_QUEUE
'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.wav.com/api/public/v1/file_convert"
headers = {
"Authorization": ""
}
data = {
"target_format": "wav",
"target_sr": 44100,
"webhook_url": "https://example.com/my-webhook"
}
# Option 1: audio_url
data["audio_url"] = ""
response = requests.post(url, headers=headers, data=data)
# Option 2: File Upload
# with open("song.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data,
files=files)
print(response.json())
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````