Transcoding

Upload audio files and manage transcoding jobs.

Submit a Job

POST /api/v1/uploads/

Upload an audio file and specify the target format. The job is queued for asynchronous processing.

Request (multipart/form-data)

Parameter	Type	Required	Description
file	File	Yes	Audio file (MP3, WAV, AAC, FLAC, OGG, M4A, Opus, WMA, AC-3)
outputFormat	String	Yes	Target format — see [Output Formats](#output-formats) table
codec	String	No	Target codec — auto-selected if omitted (see [Codecs](#codecs))
bitrate	String	No	Target bitrate (e.g. `64k`, `128k`, `256k`, `320k`) — ignored for lossless
sampleRate	String	No	Target sample rate: `8000`, `16000`, `22050`, `44100`, `48000`
channels	String	No	`1` (Mono), `2` (Stereo), `6` (5.1 Surround), `8` (7.1 Surround) — codec-dependent
segmentDuration	String	No	Segment length in seconds (HLS/DASH only, default: `4`)
priority	String	No	`"true"` to use priority queue (Pro/Enterprise plans)

Example

bash

curl -X POST http://localhost:8000/api/v1/uploads/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]" \
  -F "outputFormat=aac" \
  -F "bitrate=256k" \
  -F "sampleRate=48000" \
  -F "channels=2"

Response

json

{
  "message": "Upload started processing",
  "upload": {
    "id": "b82542ee-ac93-4ef6-92ef-1be86bf695e6",
    "file_name": "song.mp3",
    "size": 4071048,
    "status": "pending",
    "created_at": "2026-04-23T10:30:00Z"
  }
}

Validation

The API validates your request against your plan limits:

Format — Only formats included in your plan's allowed_formats list are accepted (403)
File Size — Files exceeding your plan's max file size are rejected (413)
Storage Quota — Uploads that would exceed your storage limit are rejected (403)
Concurrent Jobs — If you've hit your plan's concurrent job limit, new jobs are rejected (429)

---

Output Formats

Format ID	Display Name	Extension	Category	Notes
`mp3`	MP3	`.mp3`	Common	Universal compatibility
`aac`	AAC	`.aac`	Common	Modern MP3 successor
`m4a`	M4A	`.m4a`	Common	MPEG-4 container (AAC or Apple Lossless)
`ogg`	OGG Vorbis	`.ogg`	Common	Open-source, gaming and web
`opus`	Opus	`.opus`	Common	Best-in-class low-bitrate
`flac`	FLAC	`.flac`	Lossless	Free lossless compression
`wav`	WAV	`.wav`	Lossless	Uncompressed PCM
`wv`	WavPack	`.wv`	Lossless	Hybrid lossless compression
`ac3`	AC-3 (Dolby Digital)	`.ac3`	Broadcast	5.1 surround — TV/DVD
`eac3`	E-AC-3 (Dolby Digital Plus)	`.eac3`	Broadcast	7.1 surround — Netflix, Disney+
`wma`	WMA	`.wma`	Broadcast	Windows legacy enterprise
`mp2`	MP2 (MPEG Layer II)	`.mp2`	Broadcast	European DAB/DVB radio
`hls`	HLS (HTTP Live Streaming)	`.m3u8`	Streaming	Apple adaptive streaming
`dash`	MPEG-DASH	`.mpd`	Streaming	Open adaptive streaming
`spx`	Speex	`.spx`	Voice	Ultra-low-bitrate speech

Plan restriction: Broadcast and streaming formats may require a higher plan. See your plan details.

---

Codecs

Codec ID	Display Name	Type	Max Channels	Notes
`libmp3lame`	MP3 (LAME)	Lossy	2	32–320 kbps
`aac`	AAC (Native)	Lossy	2	32–256 kbps
`libfdk_aac`	AAC (Fraunhofer FDK)	Lossy	2	16–320 kbps. Studio grade
`libvorbis`	Vorbis (OGG)	Lossy	2	45–500 kbps
`libopus`	Opus	Lossy	2	6–510 kbps. Best low-bitrate
`ac3`	AC-3 (Dolby Digital)	Lossy	6 (5.1)	32–640 kbps
`eac3`	E-AC-3 (Dolby Digital Plus)	Lossy	16 (7.1+)	32–6144 kbps
`wmav2`	WMA v2	Lossy	2	32–320 kbps
`mp2`	MPEG-1 Layer II	Lossy	2	32–384 kbps
`libspeex`	Speex	Lossy	1	2–44 kbps. Voice only
`flac`	FLAC	Lossless	2	—
`pcm_s16le`	PCM 16-bit (WAV)	Lossless	2	CD quality
`pcm_s24le`	PCM 24-bit (WAV)	Lossless	2	Studio mastering
`pcm_f32le`	PCM 32-bit Float (WAV)	Lossless	2	Professional DAW
`alac`	ALAC (Apple Lossless)	Lossless	2	Native Apple support
`wavpack`	WavPack	Lossless	2	Audiophile archival

Use GET /api/v1/capabilities to get the runtime-available encoders for your deployment.

---

List Jobs

GET /api/v1/audio/uploads

Parameter	Type	Default	Description
status	string	—	Filter: `completed`, `processing`, `failed`, `pending`, `cancelled`
format	string	—	Filter by output format: `mp3`, `aac`, `hls`, etc.
page	int	1	Page number
per_page	int	20	Items per page (max 100)

Response

json

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_count": 42,
    "total_pages": 3
  }
}

---

Get Job Status

GET /api/v1/audio/{job_id}

Returns the complete job record.

json

{
  "id": "b82542ee-ac93-4ef6-92ef-1be86bf695e6",
  "user_id": "a1b2c3d4-...",
  "file_name": "song.mp3",
  "file_type": "audio/mpeg",
  "size": 4071048,
  "status": "completed",
  "output_format": "aac",
  "output_url": "/api/v1/uploads/local/processed/b82542ee.aac",
  "output_size": 2832046,
  "processing_duration_ms": 4520,
  "metadata": {
    "codec": "aac",
    "bit_rate": 256000,
    "sample_rate": 48000,
    "channels": 2,
    "duration": 174.5
  },
  "input_metadata": {
    "codec": "mp3",
    "bit_rate": 192000,
    "sample_rate": 44100,
    "channels": 2,
    "duration": 169.4
  },
  "error_message": null,
  "created_at": "2026-04-23T10:30:00Z",
  "updated_at": "2026-04-23T10:30:04Z"
}

---

Get Job Output

GET /api/v1/audio/{job_id}/output

Returns output URLs and metadata for a completed job. Returns 409 Conflict if the job isn't finished.

json

{
  "job_id": "b82542ee-...",
  "output_url": "/api/v1/uploads/local/processed/file.aac",
  "output_format": "aac",
  "metadata": { "codec": "aac", "bit_rate": 256000, "duration": 174.5 },
  "input_metadata": { "codec": "mp3", "bit_rate": 192000, "duration": 169.4 }
}

---

Cancel / Delete Job

DELETE /api/v1/audio/{job_id}

Active jobs (pending/processing) are cancelled — status set to cancelled
Completed/failed jobs are deleted from the database

json

{ "status": "cancelled" }

---

Presets

Pre-configured transcoding profiles for common use cases.

GET /api/v1/presets/ — Returns all available presets (system + your custom presets)

POST /api/v1/presets/ — Create a custom preset (Pro/Enterprise plans)

PUT /api/v1/presets/{id} — Update a preset

DELETE /api/v1/presets/{id} — Delete a preset

Built-in Presets

Preset	Format	Codec	Bitrate	Channels	Use Case
Podcast Standard	MP3	LAME	128k	Mono	All podcast platforms
Music HLS Stream	HLS	AAC	256k	Stereo	Adaptive streaming
Voice Opus	Opus	libopus	64k	Mono	Audiobooks, interviews
Lossless FLAC	FLAC	flac	—	Stereo	Archival
Hi-Fi M4A	M4A	FDK AAC	256k	Stereo	Apple ecosystem
Broadcast AC-3	AC-3	ac3	448k	5.1	TV/cinema
Apple Lossless	M4A	ALAC	—	Stereo	Apple lossless
Radio Broadcast	MP2	mp2	192k	Stereo	DAB/DVB compliance

---

Codecs & Formats Discovery

GET /api/v1/codecs — List all supported codecs with bitrate ranges and sample rates

GET /api/v1/codecs/{codec_id} — Get codec details

GET /api/v1/formats — List all output formats with MIME types and default codecs

GET /api/v1/formats/{format_id} — Get format details

GET /api/v1/capabilities — Runtime capabilities: FFmpeg version, available encoders, and full codec/format catalog

Transcoding

Upload audio files and manage transcoding jobs.

Submit a Job

POST /api/v1/uploads/

Upload an audio file and specify the target format. The job is queued for asynchronous processing.

Request (multipart/form-data)

Parameter	Type	Required	Description
file	File	Yes	Audio file (MP3, WAV, AAC, FLAC, OGG, M4A, Opus, WMA, AC-3)
outputFormat	String	Yes	Target format — see [Output Formats](#output-formats) table
codec	String	No	Target codec — auto-selected if omitted (see [Codecs](#codecs))
bitrate	String	No	Target bitrate (e.g. `64k`, `128k`, `256k`, `320k`) — ignored for lossless
sampleRate	String	No	Target sample rate: `8000`, `16000`, `22050`, `44100`, `48000`
channels	String	No	`1` (Mono), `2` (Stereo), `6` (5.1 Surround), `8` (7.1 Surround) — codec-dependent
segmentDuration	String	No	Segment length in seconds (HLS/DASH only, default: `4`)
priority	String	No	`"true"` to use priority queue (Pro/Enterprise plans)

Example

bash

curl -X POST http://localhost:8000/api/v1/uploads/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]" \
  -F "outputFormat=aac" \
  -F "bitrate=256k" \
  -F "sampleRate=48000" \
  -F "channels=2"

Response

json

{
  "message": "Upload started processing",
  "upload": {
    "id": "b82542ee-ac93-4ef6-92ef-1be86bf695e6",
    "file_name": "song.mp3",
    "size": 4071048,
    "status": "pending",
    "created_at": "2026-04-23T10:30:00Z"
  }
}

Validation

The API validates your request against your plan limits:

Format — Only formats included in your plan's allowed_formats list are accepted (403)
File Size — Files exceeding your plan's max file size are rejected (413)
Storage Quota — Uploads that would exceed your storage limit are rejected (403)
Concurrent Jobs — If you've hit your plan's concurrent job limit, new jobs are rejected (429)

---

Output Formats

Format ID	Display Name	Extension	Category	Notes
`mp3`	MP3	`.mp3`	Common	Universal compatibility
`aac`	AAC	`.aac`	Common	Modern MP3 successor
`m4a`	M4A	`.m4a`	Common	MPEG-4 container (AAC or Apple Lossless)
`ogg`	OGG Vorbis	`.ogg`	Common	Open-source, gaming and web
`opus`	Opus	`.opus`	Common	Best-in-class low-bitrate
`flac`	FLAC	`.flac`	Lossless	Free lossless compression
`wav`	WAV	`.wav`	Lossless	Uncompressed PCM
`wv`	WavPack	`.wv`	Lossless	Hybrid lossless compression
`ac3`	AC-3 (Dolby Digital)	`.ac3`	Broadcast	5.1 surround — TV/DVD
`eac3`	E-AC-3 (Dolby Digital Plus)	`.eac3`	Broadcast	7.1 surround — Netflix, Disney+
`wma`	WMA	`.wma`	Broadcast	Windows legacy enterprise
`mp2`	MP2 (MPEG Layer II)	`.mp2`	Broadcast	European DAB/DVB radio
`hls`	HLS (HTTP Live Streaming)	`.m3u8`	Streaming	Apple adaptive streaming
`dash`	MPEG-DASH	`.mpd`	Streaming	Open adaptive streaming
`spx`	Speex	`.spx`	Voice	Ultra-low-bitrate speech

Plan restriction: Broadcast and streaming formats may require a higher plan. See your plan details.

---

Codecs

Codec ID	Display Name	Type	Max Channels	Notes
`libmp3lame`	MP3 (LAME)	Lossy	2	32–320 kbps
`aac`	AAC (Native)	Lossy	2	32–256 kbps
`libfdk_aac`	AAC (Fraunhofer FDK)	Lossy	2	16–320 kbps. Studio grade
`libvorbis`	Vorbis (OGG)	Lossy	2	45–500 kbps
`libopus`	Opus	Lossy	2	6–510 kbps. Best low-bitrate
`ac3`	AC-3 (Dolby Digital)	Lossy	6 (5.1)	32–640 kbps
`eac3`	E-AC-3 (Dolby Digital Plus)	Lossy	16 (7.1+)	32–6144 kbps
`wmav2`	WMA v2	Lossy	2	32–320 kbps
`mp2`	MPEG-1 Layer II	Lossy	2	32–384 kbps
`libspeex`	Speex	Lossy	1	2–44 kbps. Voice only
`flac`	FLAC	Lossless	2	—
`pcm_s16le`	PCM 16-bit (WAV)	Lossless	2	CD quality
`pcm_s24le`	PCM 24-bit (WAV)	Lossless	2	Studio mastering
`pcm_f32le`	PCM 32-bit Float (WAV)	Lossless	2	Professional DAW
`alac`	ALAC (Apple Lossless)	Lossless	2	Native Apple support
`wavpack`	WavPack	Lossless	2	Audiophile archival

Use GET /api/v1/capabilities to get the runtime-available encoders for your deployment.

---

List Jobs

GET /api/v1/audio/uploads

Parameter	Type	Default	Description
status	string	—	Filter: `completed`, `processing`, `failed`, `pending`, `cancelled`
format	string	—	Filter by output format: `mp3`, `aac`, `hls`, etc.
page	int	1	Page number
per_page	int	20	Items per page (max 100)

Response

json

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_count": 42,
    "total_pages": 3
  }
}

---

Get Job Status

GET /api/v1/audio/{job_id}

Returns the complete job record.

json

{
  "id": "b82542ee-ac93-4ef6-92ef-1be86bf695e6",
  "user_id": "a1b2c3d4-...",
  "file_name": "song.mp3",
  "file_type": "audio/mpeg",
  "size": 4071048,
  "status": "completed",
  "output_format": "aac",
  "output_url": "/api/v1/uploads/local/processed/b82542ee.aac",
  "output_size": 2832046,
  "processing_duration_ms": 4520,
  "metadata": {
    "codec": "aac",
    "bit_rate": 256000,
    "sample_rate": 48000,
    "channels": 2,
    "duration": 174.5
  },
  "input_metadata": {
    "codec": "mp3",
    "bit_rate": 192000,
    "sample_rate": 44100,
    "channels": 2,
    "duration": 169.4
  },
  "error_message": null,
  "created_at": "2026-04-23T10:30:00Z",
  "updated_at": "2026-04-23T10:30:04Z"
}

---

Get Job Output

GET /api/v1/audio/{job_id}/output

Returns output URLs and metadata for a completed job. Returns 409 Conflict if the job isn't finished.

json

{
  "job_id": "b82542ee-...",
  "output_url": "/api/v1/uploads/local/processed/file.aac",
  "output_format": "aac",
  "metadata": { "codec": "aac", "bit_rate": 256000, "duration": 174.5 },
  "input_metadata": { "codec": "mp3", "bit_rate": 192000, "duration": 169.4 }
}

---

Cancel / Delete Job

DELETE /api/v1/audio/{job_id}

Active jobs (pending/processing) are cancelled — status set to cancelled
Completed/failed jobs are deleted from the database

json

{ "status": "cancelled" }

---

Presets

Pre-configured transcoding profiles for common use cases.

GET /api/v1/presets/ — Returns all available presets (system + your custom presets)

POST /api/v1/presets/ — Create a custom preset (Pro/Enterprise plans)

PUT /api/v1/presets/{id} — Update a preset

DELETE /api/v1/presets/{id} — Delete a preset

Built-in Presets

Preset	Format	Codec	Bitrate	Channels	Use Case
Podcast Standard	MP3	LAME	128k	Mono	All podcast platforms
Music HLS Stream	HLS	AAC	256k	Stereo	Adaptive streaming
Voice Opus	Opus	libopus	64k	Mono	Audiobooks, interviews
Lossless FLAC	FLAC	flac	—	Stereo	Archival
Hi-Fi M4A	M4A	FDK AAC	256k	Stereo	Apple ecosystem
Broadcast AC-3	AC-3	ac3	448k	5.1	TV/cinema
Apple Lossless	M4A	ALAC	—	Stereo	Apple lossless
Radio Broadcast	MP2	mp2	192k	Stereo	DAB/DVB compliance

---

Codecs & Formats Discovery

GET /api/v1/codecs — List all supported codecs with bitrate ranges and sample rates

GET /api/v1/codecs/{codec_id} — Get codec details

GET /api/v1/formats — List all output formats with MIME types and default codecs

GET /api/v1/formats/{format_id} — Get format details

GET /api/v1/capabilities — Runtime capabilities: FFmpeg version, available encoders, and full codec/format catalog