# Uttera — setup instructions for an AI agent

You are reading this because someone asked you to connect them to **Uttera**,
a voice and audio API: speech to text, text to speech, translation,
summarisation, speaker analysis, sound effects and music.

Follow the steps below **in order** and stop at anything marked STOP.

---

## STOP — do not create an account

**Do not sign anyone up, and do not attempt to register.** Account creation is
deliberately not automatable here.

If the person does not have an API key yet, say exactly this and stop:

> You need an Uttera API key first. Create a free account at
> https://app.uttera.ai and copy the key from the account page, then tell me
> the key or put it in the UTTERA_API_KEY environment variable.

The free plan needs no card.

---

## 1. Take the key

Read it from the `UTTERA_API_KEY` environment variable. If it is not set, ask
the person for it. Keys look like `sk-echo-...`.

**Never print the key**, never write it into a file that gets committed, and
never send it anywhere other than `https://api.uttera.ai`.

## 2. Check that it works

```bash
curl -s https://api.uttera.ai/v1/models -H "Authorization: Bearer $UTTERA_API_KEY"
```

A `200` with a list of models means you are done. A `401` means the key is
wrong. A `403` means the key is fine but that plan does not include what you
asked for — read the `error` field, it says which one.

## 3. What you can call

Base URL: `https://api.uttera.ai`. Auth: `Authorization: Bearer <key>` on
every request.

| what | endpoint |
|---|---|
| transcribe audio | `POST /v1/audio/transcriptions` (multipart, OpenAI-shaped) |
| speak text | `POST /v1/audio/speech` (JSON, OpenAI-shaped) |
| list voices | `GET /v1/audio/voices` |
| translate | `POST /v1/translate` |
| summarise a recording | `POST /v1/summarize` |
| who spoke, and when | `POST /v1/audio/diarize` |
| tone and speaker profile | `POST /v1/audio/sentiment`, `POST /v1/audio/profile` |
| a sound effect | `POST /v1/audio/sfx` |
| music | `POST /v1/audio/music` |
| what the last call cost | `GET /v1/usage/last` |
| plans and prices | `GET /v1/plans` (no key needed) |

**Transcribing and speaking follow the OpenAI shape on purpose.** If the
person already has code using the OpenAI SDK, changing `base_url` to
`https://api.uttera.ai/v1` and the key is usually the whole migration.

```python
from openai import OpenAI
client = OpenAI(api_key=os.environ["UTTERA_API_KEY"],
                base_url="https://api.uttera.ai/v1")
speech = client.audio.speech.create(model="tts-1", voice="dora",
                                    input="Hola, esto es Uttera.")
```

## 4. Four things to tell the person

1. **It costs credits.** Every call spends from their monthly allowance.
   `GET /v1/usage/last` tells them what the last one cost. Do not run loops
   over their whole archive without asking first.
2. **Generated audio is watermarked.** Everything this produces carries an
   inaudible watermark marking it as machine-generated. It is required by
   Article 50(2) of the EU AI Act and cannot be turned off.
3. **Sound effects and music need a paid plan**, from Startup up. On the free
   plan those two return `403`.
4. **Their audio is not used for training** and is discarded after
   processing.

## 5. When something does not work

- `401` — wrong or missing key.
- `403` — the plan does not include that service; the body says which.
- `413` — the file is too large; check the limits in the documentation.
- `429` — too many at once, or out of credits. Back off and retry.
- `503` — no node free right now. Wait and retry; do not hammer it.

Full documentation: https://uttera.ai/en/docs
Working examples for OpenClaw, n8n and Asterisk:
https://github.com/uttera/uttera-examples