Audio

Basic request

Send the audio file as the body of POST /v1/compress. Without options the output is AAC at 192 kbit/s in an .m4a file. This example makes a mono MP3 at 96 kbit/s, a common setting for speech:

curl -X POST "https://api.smolmac.com/v1/compress?audio.format=mp3&audio.quality=low&audio.channels=mono" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @interview.wav \
  -o interview.mp3

import { readFile, writeFile } from "node:fs/promises";

const query = new URLSearchParams({
  "audio.format": "mp3",
  "audio.quality": "low",
  "audio.channels": "mono",
});
const response = await fetch(`https://api.smolmac.com/v1/compress?${query}`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SMOL_API_KEY}` },
  body: await readFile("interview.wav"),
});
if (!response.ok) throw new Error((await response.json()).error.message);

await writeFile("interview.mp3", Buffer.from(await response.arrayBuffer()));

const result = JSON.parse(response.headers.get("smol-result"));
console.log(result.duration_seconds, "seconds,", result.savings_percent, "% smaller");

import json, os, requests

with open("interview.wav", "rb") as f:
    response = requests.post(
        "https://api.smolmac.com/v1/compress",
        params={"audio.format": "mp3", "audio.quality": "low", "audio.channels": "mono"},
        headers={"Authorization": f"Bearer {os.environ['SMOL_API_KEY']}"},
        data=f,
    )
response.raise_for_status()

with open("interview.mp3", "wb") as out:
    out.write(response.content)

result = json.loads(response.headers["smol-result"])
print(result["duration_seconds"], "seconds,", result["savings_percent"], "% smaller")

The result object reports the length of the audio in duration_seconds, which is what the price is based on.

Formats

Input can be MP3, AAC, WAV, FLAC, M4A, OGG, Opus or WMA. audio.format chooses the output:

ogg and opus both produce Opus audio. They differ only in the file extension.

With original, an MP3 stays MP3, OGG and Opus stay Opus, and WAV and FLAC stay as they are. Any other input, including AAC, M4A and WMA, becomes AAC in an .m4a file.

The lossless formats are useful for changing container, not for saving space: a WAV written as FLAC is roughly half the size with no loss, while a lossy file written as WAV or FLAC gets larger and gains nothing.

Quality tiers and bitrates

audio.quality picks a bitrate for the lossy formats. The tiers are the same for AAC, MP3 and Opus.

To set a bitrate that is not one of the tiers, send audio.bitrate_kbps, a whole number from 16 to 512. It overrides audio.quality:

curl -X POST "https://api.smolmac.com/v1/compress?audio.format=opus&audio.bitrate_kbps=48&audio.channels=mono" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @voicemail.wav \
  -o voicemail.opus

The lossless formats take no bitrate. For WAV, FLAC and ALAC, audio.quality and audio.bitrate_kbps are ignored.

Channels

Only mono changes the channel count. stereo does not turn a mono recording into stereo, and it does not reduce surround audio to two channels.

The bitrate is for the whole file, not per channel. A mono file at 96 kbit/s has the same size as a stereo file at 96 kbit/s and sounds better, because all the bits go to one channel. For speech, mono at a lower tier is usually the best saving.

Sample rate

By default the output keeps the sample rate of the input. To change it, send audio.sample_rate_hz, a whole number from 8000 to 192000. Each output codec accepts a different range:

A rate outside the range for the chosen format fails with invalid_options. This is checked once the file has been read, so param is null and the message names the option.

Tags and cover art

Tags such as title, artist and album are kept by default. This is the opposite of images, where metadata is removed by default. To remove the tags, send audio.strip_metadata=true.

Embedded cover art is not carried into the output, whatever this option is set to.

When the original is kept

If the output has the same file type as the input and is not smaller, the API returns the input with Smol-Kept-Original: true, and the request is free. This is what happens when an MP3 at 128 kbit/s is sent with audio.format=mp3&audio.quality=high: encoding it again at a higher bitrate would only make it larger.

If the file type changes, you get the new file even when it is larger, and the result has increased: true. See Kept original.

Limits

• A direct request takes a file of up to 25 MB and must finish within two minutes. Longer recordings go through a job. See Large files and jobs.
• The length of a recording is limited by plan: 10 minutes on pay as you go, 60 minutes on Starter, and 3 hours on Growth, Scale and Enterprise. Longer audio fails with 422 limit_exceeded.
• A file with no audio track fails with 422 processing_failed.

To change format with fixed settings and no options, there is also POST /v1/convert?to=mp3. See Convert files.

Billing

Audio costs $0.005 per started minute, for compression and for conversion. The length is the one reported in duration_seconds.

The price does not depend on the format, the bitrate or the size of the file. Failed requests and requests where the original was kept are free. See Billing.