# Free API and REST API

## Free API
No key and no account. Send a file to `POST https://audo.ai/api/try/<tool>` and get the result back. Each tool processes the first part of the file for free, a few times a day.

```bash
curl -F file=@interview.wav https://audo.ai/api/try/remove-noise -o interview-clean.wav
```

### Inputs

- `file`, or `url` for a public HTTPS link, for tools that take one file. Send the body as `multipart/form-data`, or as JSON when every input is a `url`.
- Join takes `file` (or `url`) 2 to 20 times, in order.
- Swap audio takes `video` and `audio` (or `video_url` and `audio_url`).
- Align a script takes `file`, plus a `text` field or a `script` file (TXT, SRT, or VTT, up to 2 MB).
- Options are the tool's inputs, with the same names and defaults as the MCP tools. Send numbers and booleans as text, and arrays, such as cut's `ranges`, as JSON. IDs and `idempotency_key` aren't accepted, and `free` and `max_credits` need an API key.
- `format` (`json`, `srt`, `vtt`, or `txt`) chooses what transcription and alignment return.
- A request takes up to 100 MB of files, with or without a key; without one, what its links fetch counts too. Links are fetched one at a time. Please send a User-Agent that names your agent.

### Responses

- The request waits up to about 30 seconds and returns the result itself: the audio or video file, the transcript, or the media info JSON.
- Send `Prefer: respond-async` to get `202` as soon as the upload is checked.
- A job that's still running returns `202` with a link to check on it: `/api/try/jobs/<job_id>?t=<token>`. The link works for 1 hour.
- `RateLimit-Policy` and `RateLimit` say how many free uses are left. `Audo-Processed-Seconds` says how much of the file was processed, and `Audo-Full-Price-Credits` gives the price of the whole file.
- When the free uses run out, the API returns `429` with JSON that says which limit, when it resets, and how to get more.

### Whole files with an API key
Send an API key from the [API keys](https://audo.ai/keys) page, and the same request runs on your account: the whole file, paid with your credits and charged only if the job succeeds. Add an `Idempotency-Key` header (a new UUID for each request) to retry safely: the same key returns the same job. Uploads are still up to 100 MB; send a larger file with the [REST API](https://audo.ai/docs/api#rest-api), which uploads in parts.

```bash
curl -H "Authorization: Bearer $AUDO_API_KEY" -F file=@interview.wav https://audo.ai/api/try/remove-noise -o interview-clean.wav
```

- Add `free=true` to process only the free part, or `max_credits` to cap the price. Both need a key.
- Without enough credits, the API answers `402` with the price and where to buy credits.

### Free limits

| Tool | Free API | Free covers | Free uses a day |
|---|---|---|---|
| Remove noise | `remove-noise` | First minute | 3 |
| Enhance voice | `enhance-voice` | First minute | 3 |
| Transcribe | `transcribe` | First 2 minutes | 3 |
| Align a script | `align-script` | First 2 minutes | 3 |
| Cut | `cut` | First 3 minutes | 3 |
| Remove silence | `remove-silence` | First 3 minutes | 3 |
| Set loudness | `loudness` | First 3 minutes | 3 |
| Convert | `convert` | First 3 minutes | 3 |
| Join files | `join` | First 3 minutes | 3 |
| Swap a video's audio | `swap-audio` | First 3 minutes | 3 |
| Media info | `media-info` | Whole file | 20 |
| Remove filler words | `remove-fillers` | First 2 minutes | 3 |
| Level speakers | `level-speakers` | First 3 minutes | 3 |
| Mix tracks | `mix` | First 3 minutes | 3 |

Uses are counted per tool, per UTC day. The website and the API share one count for each visitor.

Without a key, one address can send 2 uploads at once (an account, 4). Another upload while those are still arriving gets `429` with `Retry-After`; send it again once one finishes.

### Every tool

### Remove noise

```bash
curl -F file=@interview.wav https://audo.ai/api/try/remove-noise -o interview-clean.wav
```

### Enhance voice

```bash
curl -F file=@lecture.wav https://audo.ai/api/try/enhance-voice -o lecture-enhanced.wav
```

### Transcribe

```bash
curl -F file=@interview.mp3 -F format=srt https://audo.ai/api/try/transcribe -o interview.srt
```

### Align a script

```bash
curl -F file=@talk.mp3 -F script=@script.txt -F format=srt https://audo.ai/api/try/align-script -o talk.srt
```

### Cut

```bash
curl -F file=@episode.mp3 -F 'ranges=[[0,12.5]]' https://audo.ai/api/try/cut -o episode-cut.mp3
```

### Remove silence

```bash
curl -F file=@episode.wav https://audo.ai/api/try/remove-silence -o episode-tight.wav
```

### Set loudness

```bash
curl -F file=@episode.wav -F target=podcast https://audo.ai/api/try/loudness -o episode-loud.wav
```

### Convert

```bash
curl -F file=@episode.wav -F format=mp3 https://audo.ai/api/try/convert -o episode.mp3
```

### Join files

```bash
curl -F file=@intro.mp3 -F file=@episode.mp3 -F file=@outro.mp3 https://audo.ai/api/try/join -o full-episode.mp3
```

### Swap a video's audio
```bash
curl -F video=@talk.mp4 -F audio=@talk-clean.wav https://audo.ai/api/try/swap-audio -o talk-new.mp4
```

### Media info

```bash
curl -F file=@interview.wav https://audo.ai/api/try/media-info
```

### Remove filler words

```bash
curl -F file=@interview.mp3 https://audo.ai/api/try/remove-fillers -o interview-tight.mp3
```

### Level speakers

```bash
curl -F file=@podcast.wav https://audo.ai/api/try/level-speakers -o podcast-leveled.wav
```

### Mix tracks

```bash
curl -F file=@voice.wav -F file=@music.mp3 -F 'tracks=[{"role":"voice"},{"role":"music","volume_db":-6}]' -F duck=true https://audo.ai/api/try/mix -o voice-mix.wav
```

## REST API
The REST API runs whole files with your credits. Its base address is `https://audo.ai/api/v1`. Send an API key from the [API keys](https://audo.ai/keys) page as a bearer token:

```bash
curl https://audo.ai/api/v1/account -H "Authorization: Bearer $AUDO_API_KEY"
```

### Run a tool

1. `POST /api/v1/files` with `{"filename": "interview.wav", "sizeBytes": 48213000}` returns the file and how to upload it: one link in `upload` (up to 100 MB), or, for files over 16 MB, `multipart` with the part size, a part link, and a complete link, all under one token.
2. Upload the bytes with `PUT` to `upload.url`. For parts, `PUT` part n (counting from 1) to `multipart.partUrl` with `{n}` replaced by n, then `POST` to `multipart.completeUrl`, which joins them or lists the parts to send again.
3. `GET /api/v1/files/<file_id>?wait=30` until its status is `ready`. Its `prices` gives each tool's price for the file, in credits.
4. `POST /api/v1/jobs` with the tool and its inputs, in snake_case: `{"tool": "remove_noise", "file_id": "file_8Kc2QmP4", "idempotency_key": "<a new UUID>"}`. Add `max_credits` to cap the price, or `"free": true` for the free part.
5. `GET /api/v1/jobs/<job_id>` until its status is `succeeded`, `failed`, or `cancelled`. A job is charged only if it succeeds.
6. `GET /api/v1/files/<output_file_id>/download` returns a link that works for 15 minutes.

### Endpoints

| Method and path | What it does |
|---|---|
| `GET /api/v1/account` | Balance, free uses left today, prices, and limits |
| `GET /api/v1/ledger` | Credit history |
| `POST /api/v1/files` | Create a file and get an upload link |
| `GET /api/v1/files` | List recent files |
| `GET /api/v1/files/<id>` | A file's status, length, and prices |
| `GET /api/v1/files/<id>/download` | A download link |
| `DELETE /api/v1/files/<id>` | Delete a file now |
| `POST /api/v1/quote` | The price of a tool for some files, and the free uses left |
| `POST /api/v1/jobs` | Start a tool |
| `GET /api/v1/jobs` | List jobs, or one tool's with `?tool=` |
| `GET /api/v1/jobs/<id>` | A job's status, progress, stage, rough time left (`estimatedSecondsLeft`), and outputs |
| `POST /api/v1/jobs/<id>/cancel` | Cancel a job that hasn't finished |

### Errors

Errors are JSON: `{"error": {"code": "...", "message": "...", "retryable": false, "nextAction": "..."}}`. The message says what went wrong, and `nextAction` says what to do. Codes: `bad_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `idempotency_key_reused`, `insufficient_balance`, `over_spending_cap`, `free_limit_reached`, `free_budget_exhausted`, `free_disabled`, `file_not_ready`, `file_invalid`, `file_expired`, `file_too_large`, `file_too_long`, `unsupported_format`, `wrong_file_type`, `text_too_long`, `no_audio`, `ranges_outside`, `fetch_failed`, `limit_exceeded`, `upload_limit_reached`, `rate_limited`, `job_not_cancellable`, `tool_unavailable`, `build_mismatch`, `internal_error`.

### OpenAPI

The full description of the free API and the REST API is at https://audo.ai/api/openapi.json.