Convert MP3 to FLAC

To convert MP3 to FLAC, send one POST to /v1/audio-convert with the MP3 source and "to": "flac" in the body. Left out, "to" falls back to its default "mp3", so a FLAC request has to send it. Each call costs $0.003 in USDC on Base via x402, with no account and no API key. The source file can be up to 100 MB and 60 min (3,600 s) long.

Agents read this page asGET /v1/audio-convert/schemafree: schema, examples, errors, price

Endpoint
POST /v1/audio-convert
Price
$0.003 per call
API
audio-convert
Selects the target
"to": "flac"
MP3pair-tone.mp3the source, by URL or inline
FLACin the responsereturned in the JSON answer

Limits

LimitValue
Largest source file100 MB (104,857,600 bytes)
Longest input60 min (3,600 s)
Timeout94 s
Source formatsAIFF, AVI, FLAC, MKV, MP3, MP4, Ogg, WAV
Output formatsAAC, FLAC, MP3, Opus, WAV

Example

A real MP3 to FLAC run of audio-convert.

Request
POST /v1/audio-convert
content-type: application/json
payment-signature: <base64 x402 payload>

{
  "url": "https://grist.tools/samples/av/pair-tone.mp3",
  "to": "flac"
}
Response200 OK
200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/av/pair-tone.mp3",
  "bytes": 12980,
  "source_container": "mp3",
  "format": "flac",
  "bitrate_kbps": null,
  "sample_rate": null,
  "audio_bytes": 43000,
  "audio_base64": "ZkxhQwAAACICQAJAAAAAAAbWAfQBcAAAAAAAAAAAAAAAAAAAAAAAAAAABAAADgYA..."
}

Source file: av/pair-tone.mp3, 12.7 KB (12,980 bytes). 3 s mono 8 kHz MP3 at 32 kbit/s, encoded by ffmpeg's libmp3lame with the bit-exact flags: three 0.5 s 500 Hz triangle beeps at rising level, each followed by 0.5 s of silence. The recorded run returned 42 KB (43,000 bytes) of FLAC, 3.3 times the source size, with the source read as the mp3 container. Decoded, the FLAC in audio_base64 opens with 66 4C 61 43 00 00 00 22 02 40 02 40 (ASCII fLaC). Recorded with ffmpeg 8.1.2.

In the sample itself: the file opens with an ID3v2.4 tag with 10 bytes of body, then an MPEG 2.5 Layer III frame header at byte 20: 32 kbps, 8,000 Hz, mono. That first frame is an Info header rather than audio, and it counts 44 audio frames and 12,960 bytes. In the returned FLAC: its 34-byte STREAMINFO block, in its own field order, declares blocks of 576 samples, a largest frame of 1,750 bytes, 8,000 Hz, 1 channel, 24 bits per sample and a total sample count of 0, which the format reserves for a length the encoder did not write back. Its MD5 signature of the decoded audio is all zeros, the value for a signature that was not computed. The next metadata block is VORBIS_COMMENT, 14 bytes long.

Format notes

MP3 as a source

MP3 is lossy audio. Grist accepts it when the file opens with an ID3v2 tag or with a bare MPEG audio frame sync: the byte FF followed by a byte whose top three bits are set. That sync test also matches a raw ADTS AAC stream, and because nothing proves ffmpeg would then pick the right demuxer, AAC is kept out of the sources. Duration needs care with MP3. For a file without a Xing header, the probe estimates length by dividing file size by the bitrate of the first frames, which a crafted variable-bitrate file can falsify, so any probe warning sends the measurement to a scan of real packet timestamps. Once accepted, the first audio stream is decoded by ffmpeg; a lossless destination stores the decoded samples without recovering what MP3 encoding discarded.

FLAC as a target

Lossless compression is the point of a FLAC target. A PCM source normally comes out smaller, and at the source rate every sample survives; a lossy source goes the other way and grows, because the encoder keeps each decoded sample, artefacts included, and recovers nothing the earlier compression removed. ffmpeg's flac codec and flac muxer write the result, streamed to a pipe with no temporary file. As with any lossless destination, a bitrate_kbps value is refused rather than silently ignored. A sample_rate from the closed set can be pinned; left unset, ffmpeg usually follows the rate of the input. The duration is checked before encoding starts, video is dropped, metadata and chapters are stripped, and just the first audio stream is mapped, under bit-exact flags that keep the output reproducible with the pinned ffmpeg.

Errors

When each is raised, and what it means for payment: /docs/audio-convert.

invalid_input 400blocked_target 403unreachable_target 424upstream_timeout 424unsupported_content_type 415too_large 413unprocessable 422internal 500

Questions

What does it cost to convert MP3 to FLAC?

$0.003 per call, paid in USDC on Base via x402.

How large can the MP3 file be?

Up to 100 MB (104,857,600 bytes), and at most 60 min (3,600 s) of media. Past a limit the call answers too_large (413).

What happens if the conversion fails?

The tool answers with a typed JSON error from the errors table. Payment is settled only after the tool has produced its result; a call that fails inside the tool is never settled.