--- title: 'Voice and audio: transcription and speech on camelRun' sidebarTitle: 'Voice and audio' description: 'Send camelRun agents voice notes and recordings, transcribed before the model reads them, or transcribe audio and synthesize speech on their own.' --- [View as Markdown](https://camelai.com/docs/camelrun/voice.md) · [Docs index for coding agents](https://run.camelai.com/llms.txt) Agents hear audio. Attach a voice note or a recording to a message, and camelRun transcribes it before the model sees it, so every model, Claude included, reads what was said. `POST /v1/transcriptions` transcribes audio on its own, with no agent, and `POST /v1/speech` turns text into speech. For live calls, where a bot listens and talks back, see [Voice calls](/docs/camelrun/voice-calls). Transcription runs on OpenAI's `gpt-transcribe` with the OpenAI key a model call of yours would use: a [key scope](/docs/camelrun/models-and-keys#key-scopes)'s, your own (`PUT /v1/providers/openai/key`), else the platform's, which a prepaid account pays for per second of audio. ## Audio in a message Attach audio as any file. A file whose type is `audio/*` is transcribed by default: ```ts TypeScript const run = await agent.run("Summarize this and list the action items", { files: ["./standup.m4a"] }); ``` ```python Python run = await agent.run("Summarize this and list the action items", files=[Path("standup.m4a")]) ``` ```bash curl curl -X POST "https://run.camelai.com/v1/agents/$AGENT/prompt" -H "Authorization: Bearer $CAMELAI_API_KEY" -H "Content-Type: application/json" \ -d '{"files": [{"url": "https://example.com/voice-message.ogg"}]}' ``` A voice note alone needs no text: `agent.run("", { files: [voiceNote] })`. In the SDKs a file is also `{ url }` (Python `{"url"}`), and takes `transcribe: true | false`. A file is attached as [Files](/docs/camelrun/files#attach-files-to-a-message) describes (uploaded, inline base64 up to 4 MiB, or `{path}` of a file in the agent's mounts), or by URL: `{url, name?, contentType?}`, which camelRun fetches from the public internet (at most 64 MiB, three redirects). camelRun transcribes the audio **before it accepts the message**. The prompt's answer comes once the transcript is ready (a second or two for a voice note, longer for a long recording). A transcription that fails fails the request, and nothing runs. The message, its events and the agent's history keep the audio file's reference with its transcript: ```json { "type": "file", "path": "/workspace/uploads/r1/voice-message.ogg", "contentType": "audio/ogg", "size": 12538, "transcript": { "text": "Hello from camelRun.", "language": "en", "seconds": 5, "model": "gpt-transcribe" }, ... } ``` The model reads it as text: ``` [Audio /workspace/uploads/r1/voice-message.ogg (audio/ogg, 0:05, en), transcript: Hello from camelRun. ] ``` The audio stays in the agent's workspace like any attachment, for its tools to use. * `transcribe: false` on a file keeps audio a plain file (named to the model, not transcribed). * `transcribe: true` transcribes a file whose type does not say audio (`application/octet-stream`, or a video such as `video/mp4` or `video/webm`, whose sound is transcribed). * Audio transcribed by default that can't be (no OpenAI key, a format or length it doesn't take, the provider failing) is attached without a transcript, and the model is told why (`[File …: not transcribed (…)]`). A voice note from a channel still reaches the agent. A file you asked to transcribe (`transcribe: true`) fails the request instead. * A spend limit refuses the request either way: the agent's, or the run's own `spendLimit`, which pays for the message's audio first (what is left is the run's to spend on its model). [Channels](/docs/camelrun/channels) get this with no setup: a Discord or Telegram voice message, or any audio file sent in a channel, reaches the agent with its transcript. [Stateless runs](/docs/camelrun/stateless-runs) take audio as input parts: `{"type": "file", "url": "…"}` or `{"type": "file", "data": "…"}`. Audio in `initialMessages` isn't transcribed: transcribe it first with `POST /v1/transcriptions` and import the text. ## Transcribe on its own ```ts TypeScript const { text } = await agents.transcriptions.create({ file: await readFile("voice-message.ogg"), language: "en" }); ``` ```python Python result = await agents.transcriptions.create(Path("voice-message.ogg"), language="en") ``` ```bash curl curl -X POST "https://run.camelai.com/v1/transcriptions" -H "Authorization: Bearer $CAMELAI_API_KEY" -F file=@voice-message.ogg -F language=en ``` ```json { "text": "Hello from camelRun.", "language": "en", "durationSeconds": 5, "model": "openai/gpt-transcribe", "costUsd": 0.000375 } ``` It takes the audio as multipart (`file`) or JSON: `{"data": ""}` or `{"url": "https://…"}`. With either: | Field | | | ----------------------------- | --------------------------------------------------------------------------------------------- | | `language` | ISO 639-1 (`en`) or a locale (`pt-BR`); detected when left out | | `prompt` | Names, jargon or the conversation so far, as a hint (at most 2,000 characters) | | `keyScope` | A key scope whose OpenAI key goes first | | `subject`, `context`, `actor` | Who it is for and who asked, carried to its `usage.recorded` event, as an agent's identity is | Nothing is kept: the audio goes to the provider and the transcript comes back to you. A retry transcribes (and bills) again; it takes no `Idempotency-Key`. API tokens and OAuth tokens may transcribe; browser tokens may not. Runs-per-minute limits count each transcription as a run. ## Speech `POST /v1/speech` turns text into speech and streams the audio back as it is made: ```bash curl -sS https://run.camelai.com/v1/speech -H "Authorization: Bearer $CAMELAI_API_KEY" -H "Content-Type: application/json" \ -d '{"text": "Hi, I am your bot.", "voice": "coral", "format": "wav"}' -o hello.wav ``` | Field | | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | At most 4,000 characters | | `format` | `pcm` (the default: raw 16-bit little-endian mono at 24 kHz) or `wav` (the same in a WAV container, which an `