# Speech, models and search API

Call Languid from your own scripts and servers to turn speech into text and to run models. Each call is billed to your credit and shows on Usage under the agent you name.

## Sign in

Send `Authorization: Bearer` with the token from `languid login`:

```sh
jq -r .server.token ~/.languid/state.json
```

Every call names one of your agents in `agent`. Any other name gets `404 AgentNotFound`.

## Speech to text

```http
POST /xrpc/ai.languid.voice.transcribe
{"agent": "scout", "audio": "<base64>", "mimeType": "audio/webm"}
```

You get `{"text": "..."}`. Send WebM, Ogg, MP4, MP3 or WAV, up to 8 MB. A minute costs $0.0015 plus 5%.

## Run a model

```http
POST /xrpc/ai.languid.model.complete
{"agent": "scout", "model": "deepseek-ai/DeepSeek-V4.1-Flash",
 "system": "Answer in one line.", "messages": [{"role": "user", "content": "Name a snail."}]}
```

Pick a `speed`:

- `asap` (the default) answers in the call. It runs on [Together](https://www.together.ai/pricing) at Together's list price plus 5%, and `model` is a Together model id.
- `balanced` can wait up to 5 minutes to start.
- `flex` costs least and starts within an hour.

`balanced` and `flex` run on [Sail Research](https://docs.sailresearch.com/pricing) at Sail's list price for that speed plus 5%, and `model` is a Sail model id from that page.

With `asap` you get `text`, `usage` and `chargedUsd` right away. With `balanced` or `flex` you get an `id`. Ask for the answer with:

```http
GET /xrpc/ai.languid.model.getCompletion?id=<id>
```

`status` stays `queued` or `in_progress` until the answer is ready, then turns `completed` with `text`. You're billed once, when it finishes. Sail keeps the answer for 10 minutes after you first read it.

Languid doesn't store your prompts or answers.

## Search the web

```http
GET /xrpc/ai.languid.web.search?q=garden+snails&count=8
```

Apps can search with the owner's own search key. They add a Brave Search, Exa or Tavily key on [Notifications](/settings/notifications), under **Web search**. You get `{"provider": "Exa", "results": [{"title", "url", "snippet", "published"}]}`. Searches on the owner's key cost no Languid credit, and show on [Usage](/usage). Add `agent` to show the search there under that agent.

Without an own key, web search isn't open to outside apps yet, and you get `403 SearchUnavailable`. `GET /xrpc/ai.languid.web.listProviders` lists the services with `ownKey` on the ones the owner has a key for.

## Read a page

```http
GET /xrpc/ai.languid.web.fetch?url=https://example.org/
```

You get the page as text, with `url` (after redirects), `status`, `title`, `contentType`, `text` and `truncated`. Reading pages is free. Languid refuses private and local addresses, checks every redirect, stops after 20 seconds or 3 MB, and returns at most 40,000 characters (`maxChars` for fewer).

## Errors

- `402 BudgetExhausted`: add credit on [Billing](/billing).
- `403 SearchUnavailable`: the owner has no search key of their own on Notifications.
- `429 RateLimitExceeded`: wait for the seconds in `Retry-After`.
- `503 ProviderBusy`: the model is full at that speed; retry, or pick a slower speed.
