# Audio OpenAI

Le nœud **Audio OpenAI** ajoute la reconnaissance vocale (ASR) et la synthèse vocale (TTS) à un workflow sans le lier à un canal de messagerie. Le même nœud peut donc être placé entre des nœuds Telegram aujourd'hui, puis WhatsApp ou Twilio plus tard.

Il utilise les API Audio OpenAI par requête. Configurez `OPENAI_API_KEY` sur le backend AgentBuilder avant de l'exécuter. Consultez le [guide Audio officiel d'OpenAI](https://developers.openai.com/api/docs/guides/audio).

---

## Audio vers texte (ASR)

Choisissez **Audio vers texte** pour transcrire une note vocale ou un fichier audio.

| Champ | Utilisation |
| --- | --- |
| **Entrée audio** | Chemin de contexte optionnel. Laissez vide pour sélectionner automatiquement la première pièce jointe audio téléchargée. |
| **Modèle de transcription** | `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` ou `whisper-1`. |
| **Code langue** | Code ISO-639-1 optionnel, par exemple `fr` ou `en`. Laissez vide pour la détection automatique. |
| **Contexte de transcription** | Vocabulaire, noms de produits, personnes ou termes métier pouvant aider la transcription. |

L'entrée est limitée à **25 Mo**. Les notes vocales Telegram en OGG/Opus sont automatiquement converties en WAV mono 16 kHz avant la transcription. Les formats courants comprennent MP3, MP4, M4A, MPEG, MPGA, OGG, Opus, WAV, WebM et FLAC.

### Sorties ASR

Si l'identifiant du nœud est `transcribe` :

| Placeholder | Valeur |
| --- | --- |
| `{last_output}` | Transcription en texte simple. |
| `{outputs.transcribe.raw}` | Transcription en texte simple. |
| `{outputs.transcribe.parsed.text}` | Transcription dans la sortie structurée. |
| `{outputs.transcribe.parsed.language}` | Langue détectée ou configurée, si disponible. |
| `{outputs.transcribe.parsed.duration}` | Durée, lorsque OpenAI la retourne. |
| `{outputs.transcribe.parsed.source_filename}` | Nom de la pièce jointe source. |

---

## Texte vers voix (TTS)

Choisissez **Texte vers voix** pour transformer la sortie d'un nœud précédent en fichier audio.

| Champ | Utilisation |
| --- | --- |
| **Modèle vocal** | `gpt-4o-mini-tts`. |
| **Texte à prononcer** | Texte fixe ou template tel que `{last_output}`. |
| **Voix** | `marin` et `cedar` sont recommandées ; les autres voix restent disponibles. |
| **Instructions vocales** | Intention optionnelle, par exemple « Parle clairement et chaleureusement en français. » |
| **Format audio** | MP3, Opus/OGG, AAC, FLAC, WAV ou PCM. |
| **Nom du fichier** | Template de sortie, par exemple `reponse-{ts}`. |

Le fichier généré est conservé par AgentBuilder et exposé avec une URL signée. Informez l'utilisateur final que la voix est générée par une IA.

### Sorties TTS

Si l'identifiant du nœud est `speech` :

| Placeholder | Valeur |
| --- | --- |
| `{last_output}` | URL signée de téléchargement de l'audio. |
| `{outputs.speech.parsed.url}` | URL signée à transmettre à l'action du canal. |
| `{outputs.speech.parsed.preview_url}` | URL signée de prévisualisation. |
| `{outputs.speech.parsed.filename}` | Nom du fichier généré. |
| `{outputs.speech.parsed.format}` | Format de sortie sélectionné. |
| `{outputs.speech.parsed.content_type}` | Type MIME du fichier généré. |

Les URL signées sont temporaires. Envoyez le média pendant la même exécution du workflow au lieu de conserver cette URL comme adresse publique permanente.

---

## Telegram : transcrire, résumer et répondre en texte

Construisez ce workflow :

```text
Telegram Trigger
  → Audio OpenAI (Audio vers texte)
  → Agent (Résumer)
  → Telegram (Envoyer un message)
```

1. Dans **Telegram Trigger**, sélectionnez l'identifiant du bot, acceptez les updates `message` et activez **Télécharger les médias**.
2. Dans **Audio OpenAI**, choisissez **Audio vers texte** et laissez **Entrée audio** vide. La première note vocale ou pièce jointe audio sera sélectionnée automatiquement.
3. Dans **Agent**, utilisez par exemple l'instruction « Résume la note vocale suivante en trois points courts. » La transcription est déjà le `last_output` courant.
4. Dans **Telegram — Envoyer un message**, définissez le chat id sur `{event.telegram.chat_id}` et le message sur `{last_output}`.
5. Sauvegardez, publiez, enregistrez le webhook Telegram, puis envoyez une note vocale au bot.

## Telegram : répondre avec une voix IA

Construisez ce workflow :

```text
Telegram Trigger
  → Audio OpenAI (Audio vers texte)
  → Agent
  → Audio OpenAI (Texte vers voix)
  → Telegram (Envoyer un audio ou une note vocale)
```

Définissez le **Texte à prononcer** du nœud TTS avec la sortie de l'Agent. Si son identifiant est `speech`, renseignez le champ média Telegram avec :

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

Utilisez **Envoyer une note vocale** avec le format Opus/OGG pour obtenir une bulle vocale Telegram. Utilisez **Envoyer un audio** avec MP3 pour obtenir un fichier nommé et les métadonnées du lecteur.

---

## Architecture indépendante du canal

Gardez le nœud Audio indépendant des champs propres à Telegram :

```text
Trigger du canal → Audio OpenAI → Agent → Audio OpenAI → Action du canal
```

Le trigger télécharge le média dans les pièces jointes du workflow. L'action finale du canal consomme uniquement l'URL signée `.parsed.url`. Un futur adaptateur WhatsApp ou Twilio pourra ainsi remplacer les nœuds Telegram sans modifier la transcription, l'Agent ou la synthèse vocale.

## Dépannage

| Symptôme | Vérification |
| --- | --- |
| « No audio attachment was found » | Activez le téléchargement des médias dans le trigger du canal, ou configurez **Entrée audio** avec un chemin de pièce jointe valide. |
| Erreur d'authentification OpenAI | Vérifiez que `OPENAI_API_KEY` est configurée sur le backend. |
| Entrée supérieure à 25 Mo | Compressez ou raccourcissez l'audio source avant de l'envoyer. |
| Telegram reçoit le texte mais pas l'audio | Utilisez `{outputs.<id-noeud-tts>.parsed.url}` dans le champ média, pas la transcription. |
| Échec du décodage d'une note vocale Telegram | Vérifiez que FFmpeg est installé dans les images API et worker. |
| L'URL signée expire plus tard | Envoyez-la immédiatement depuis le nœud canal suivant ; ne la conservez pas comme URL permanente. |

---

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