# Audiomenti for agents

You are helping someone turn audio into text with Audiomenti (https://audiomenti.com). This is everything you need.

## What it costs

One credit transcribes up to one hour of audio. A job costs one credit per started hour of its files added together (twenty 5-minute clips are 2 credits). Ask before spending someone's money:

```
curl -s "https://audiomenti.com/api/v1/pricing?seconds=<total seconds>&files=<count>"
```

The answer's `quote` has `credits`, `usd` and `estimated_wait`. No key needed.

## Getting a key

A key (`am_` + 32 hex) is made by verifying an email. A person has to open the email:

```
curl -X POST https://audiomenti.com/api/v1/register/start -H "Content-Type: application/json" \
  -d '{"email": "<their email>", "agree": true}'
```

`agree: true` accepts https://audiomenti.com/terms and https://audiomenti.com/privacy on their behalf, so ask them first. They click the link and copy the key from https://audiomenti.com/account, or you trade the token: `POST /api/v1/register/confirm {"token": "..."}`.

Send the key as `Authorization: Bearer am_...`. Check the balance with `GET /api/v1/me` (`credits`).

## Buying credits

You cannot pay. Get a link and give it to the person:

```
curl -s -X POST https://audiomenti.com/api/v1/checkout -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"hours": 12}'
```

`{"job": "<id>"}` instead buys exactly what that job still needs and starts it when paid.

## Doing a job

Files on the web (public links, up to 200 per job):

```
curl -s -X POST https://audiomenti.com/api/v1/jobs -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"url": "https://..."}], "language": "en", "format": "txt", "start": true}'
```

Local files: create the job with `{"files": [{"path": "a.mp3", "bytes": 123456, "seconds": 600}]}`, then `PUT /api/v1/jobs/<id>/files/<n> --data-binary @a.mp3` for each (n counts from 1; over 95 MB use `/multipart`, `/parts/<part>`, `/complete`), then `POST /api/v1/jobs/<id>/start`.

A `402 insufficient_credits` answer carries `needed`: get a checkout link for the job, wait for the person to pay, and it starts by itself.

Poll `GET /api/v1/jobs/<id>` every 10 to 30 seconds until `status` is `done` or `failed`. Then:

```
curl -s -OJ "https://audiomenti.com/api/v1/jobs/<id>/download?format=txt" -H "Authorization: Bearer $KEY"
curl -s "https://audiomenti.com/api/v1/jobs/<id>/files/1/transcript?format=json" -H "Authorization: Bearer $KEY"
```

The download is the single file for a one-file job, otherwise a zip with the same names and folders as what went in. Any format, any number of times, free.

## Formats

- `txt`: Plain text (.txt). The words in paragraphs. For reading, quoting and pasting into a document.
- `timestamps`: Text with times (.txt). Each paragraph starts with the time it was said, so you can find it in the recording.
- `md`: Markdown (.md). Paragraphs with a time heading every few minutes. For notes apps and wikis.
- `srt`: SRT subtitles (.srt). Numbered captions with times. For video editors, YouTube and most players.
- `vtt`: WebVTT subtitles (.vtt). Captions for the web: the format browsers play next to a video.
- `json`: JSON (.json). Every segment and every word with its time. For code.

## Languages

English (en), Spanish (es), French (fr), German (de), Italian (it), Portuguese (pt), Dutch (nl), Polish (pl), Russian (ru), Ukrainian (uk), Swedish (sv), Danish (da), Finnish (fi), Czech (cs), Slovak (sk), Romanian (ro), Hungarian (hu), Bulgarian (bg), Croatian (hr), Greek (el), Estonian (et), Lithuanian (lt), Latvian (lv), Slovenian (sl), Maltese (mt). The spoken language is detected from the audio. Anything else comes back wrong or empty: say so instead of spending credits. No translation, no speaker labels.

## Things to tell the person

- Audio is deleted as soon as it has been transcribed; unpaid uploads after 24 hours.
- The audio is sent to Replicate, a third-party GPU provider in the United States, which removes it within an hour.
- Transcripts stay on the account until deleted: `DELETE /api/v1/jobs/<id>` wipes one for good.
- A file that fails costs nothing. Audio that runs shorter than quoted is refunded automatically.

Full reference: https://audiomenti.com/api and https://audiomenti.com/openapi.json.
