# OpenAI Audio

The **OpenAI Audio** node adds speech recognition (ASR) and speech synthesis (TTS) to a workflow without coupling the workflow to a messaging channel. The same node can therefore sit between Telegram nodes today and WhatsApp or Twilio nodes later.

It uses the OpenAI request-based Audio APIs. Configure `OPENAI_API_KEY` on the AgentBuilder backend before running it. See the [official OpenAI Audio guide](https://developers.openai.com/api/docs/guides/audio).

---

## Audio to text (ASR)

Choose **Audio to text** to transcribe a voice note or audio file.

| Field | Usage |
| --- | --- |
| **Audio input** | Optional context path. Leave empty to select the first downloaded audio attachment automatically. |
| **Transcription model** | `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, or `whisper-1`. |
| **Language code** | Optional ISO-639-1 code such as `fr` or `en`. Leave empty for automatic detection. |
| **Transcription context** | Optional vocabulary, product names, people, or domain terms that may help transcription. |

The input is limited to **25 MB**. Telegram OGG/Opus voice notes are converted automatically to a 16 kHz mono WAV file before transcription. Common inputs include MP3, MP4, M4A, MPEG, MPGA, OGG, Opus, WAV, WebM, and FLAC.

### ASR outputs

If the node id is `transcribe`:

| Placeholder | Value |
| --- | --- |
| `{last_output}` | Transcript as plain text. |
| `{outputs.transcribe.raw}` | Transcript as plain text. |
| `{outputs.transcribe.parsed.text}` | Transcript from the structured output. |
| `{outputs.transcribe.parsed.language}` | Detected or configured language, when available. |
| `{outputs.transcribe.parsed.duration}` | Audio duration, when returned by OpenAI. |
| `{outputs.transcribe.parsed.source_filename}` | Name of the source attachment. |

---

## Text to speech (TTS)

Choose **Text to speech** to turn a previous node's output into an audio file.

| Field | Usage |
| --- | --- |
| **Speech model** | `gpt-4o-mini-tts`. |
| **Text to speak** | A fixed string or template such as `{last_output}`. |
| **Voice** | `marin` and `cedar` are recommended; the other voices remain selectable. |
| **Voice instructions** | Optional delivery guidance, for example “Speak warmly and clearly in French.” |
| **Audio format** | MP3, Opus/OGG, AAC, FLAC, WAV, or PCM. |
| **Filename template** | Output name, for example `reply-{ts}`. |

The generated file is stored by AgentBuilder and exposed through a signed URL. Tell end users that the voice is AI-generated.

### TTS outputs

If the node id is `speech`:

| Placeholder | Value |
| --- | --- |
| `{last_output}` | Signed audio download URL. |
| `{outputs.speech.parsed.url}` | Signed URL to pass to a channel action. |
| `{outputs.speech.parsed.preview_url}` | Signed preview URL. |
| `{outputs.speech.parsed.filename}` | Generated filename. |
| `{outputs.speech.parsed.format}` | Selected output format. |
| `{outputs.speech.parsed.content_type}` | MIME type of the generated file. |

Signed URLs are temporary. Send the media in the same workflow execution instead of storing the URL as a permanent public address.

---

## Telegram: transcribe, summarize, and reply with text

Build this flow:

```text
Telegram Trigger
  → OpenAI Audio (Audio to text)
  → Agent (Summarize)
  → Telegram (Send message)
```

1. In **Telegram Trigger**, select the bot credential, accept `message` updates, and enable **Download media**.
2. In **OpenAI Audio**, select **Audio to text** and leave **Audio input** empty. The first voice/audio attachment is selected automatically.
3. In **Agent**, use instructions such as “Summarize the following voice note in three short bullet points.” The transcript is already the current `last_output`.
4. In **Telegram — Send message**, set the chat id to `{event.telegram.chat_id}` and the message to `{last_output}`.
5. Save, publish, register the Telegram webhook, and send the bot a voice note.

## Telegram: answer with an AI voice

Build this flow:

```text
Telegram Trigger
  → OpenAI Audio (Audio to text)
  → Agent
  → OpenAI Audio (Text to speech)
  → Telegram (Send audio or Send voice)
```

Set the TTS node's **Text to speak** to the Agent output. If its node id is `speech`, set the Telegram media field to:

```text
{outputs.speech.parsed.url}
```

Use **Send voice** with Opus/OGG for a Telegram-style voice bubble. Use **Send audio** with MP3 when you want a named audio file and player metadata.

---

## Channel-neutral design

Keep the audio node independent of Telegram-specific fields:

```text
Channel trigger → OpenAI Audio → Agent → OpenAI Audio → Channel action
```

The trigger is responsible for downloading media into workflow attachments. The final channel action only consumes the signed `.parsed.url`. A future WhatsApp or Twilio adapter can therefore replace the Telegram nodes without changing the transcription, Agent, or speech nodes.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| “No audio attachment was found” | Enable media download in the channel trigger, or configure **Audio input** with a valid attachment context path. |
| OpenAI authentication error | Verify that `OPENAI_API_KEY` is configured on the backend. |
| Input exceeds 25 MB | Compress or shorten the source audio before sending it. |
| Telegram receives text but no audio | Use `{outputs.<tts-node-id>.parsed.url}` in the media field, not the transcript. |
| Telegram voice note fails to decode | Verify that FFmpeg is installed in the API and worker images. |
| The signed URL later expires | Send it immediately from the downstream channel node; do not persist it as a permanent URL. |

---

*Source: https://agentbuilder.systalink.sn/docs/node-openai-audio — human documentation.*
*Other language: [/docs-md/fr/node-openai-audio.md](/docs-md/fr/node-openai-audio.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*