> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Speech to Text asynchrone

> **Note**
>
> **Guide pratique** · Suppose que vous avez suivi le [guide de démarrage rapide de Speech to Text ](/docs/fr/eleven-api/guides/cookbooks/speech-to-text).

## Vue d’ensemble

Les webhooks vous permettent de recevoir des notifications automatiques lorsque vos tâches de transcription Speech to Text sont terminées. Vous n’avez ainsi plus besoin d’interroger continuellement l’API pour obtenir des mises à jour de statut. Cette approche est particulièrement utile pour les tâches de transcription longues ou le traitement de volumes importants de fichiers audio.

Lorsqu’une transcription est terminée, ElevenLabs envoie une requête POST à l’URL de webhook indiquée avec les résultats de la transcription, notamment le texte transcrit, la détection de la langue et les métadonnées.

## Utiliser les webhooks

> **Note**
>
> Ce guide suppose que vous avez [configuré votre clé API et votre SDK](/docs/fr/eleven-api/quickstart). Suivez
> d’abord le guide de démarrage rapide si ce n’est pas encore fait.

#### Créer ou modifier un webhook

Dans le Dashboard ElevenLabs, accédez à
[**Développeurs** > **Webhooks**](https://elevenlabs.io/app/developers/webhooks).
Cliquez sur **Créer un webhook** ou modifiez un webhook existant.

![Boîte de dialogue Créer un webhook avec Transcription terminée sélectionné](/docs/_fern-img/866f389106e74e16586a4d68cf8160f2d27568518ff4f984c2fab81cbd1674c9.webp)

Configurez le webhook avec :

* **Nom** : un nom descriptif pour votre webhook
* **URL de rappel** : votre point de terminaison HTTPS accessible publiquement
* **Méthode d’authentification du webhook** : `HMAC` ou `OAuth`. Il appartient au client d’implémenter le mécanisme de vérification. ElevenLabs envoie des en-têtes permettant la vérification, mais nous ne l’imposons pas.
* **Événements** : sélectionnez **Transcription terminée**.

#### Effectuer des appels API avec le paramètre webhook activé

Lorsque vous effectuez des appels API de conversion de parole en texte, incluez le paramètre `webhook` défini sur `true` afin d’activer les notifications par webhook pour cette requête spécifique.

```python maxLines=0
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)

def transcribe_with_webhook(audio_file):
  try:
    result = elevenlabs.speech_to_text.convert(
      file=audio_file,
      model_id="scribe_v2",
      webhook=True,
    )
    print(f"Transcription started: {result.request_id}")
    return result
  except Exception as e:
    print(f"Error starting transcription: {e}")
    raise e
```

```typescript maxLines=0
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

async function transcribeWithWebhook(audioFile) {
  try {
    const result = await elevenlabs.speechToText.convert({
      file: audioFile,
      modelId: 'scribe_v2',
      webhook: true,
    });

    console.log('Transcription started:', result.requestId);
    return result;
  } catch (error) {
    console.error('Error starting transcription:', error);
    throw error;
  }
}
```

## Charge utile du webhook

Lorsqu’une transcription est terminée, votre point de terminaison de webhook reçoit une requête POST contenant les données de transcription et du webhook :

```json
{
  type: 'speech_to_text_transcription',
  data: {
    request_id: 'some-request-id-123',
    webhook_metadata: { ... }, // if provided in the convert request
    transcription: {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello world!",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_1"
        },
        {
          "text": " ",
          "start": 0.5,
          "end": 0.5,
          "type": "spacing",
          "speaker_id": "speaker_1"
        },
        {
          "text": "world!",
          "start": 0.5,
          "end": 1.2,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}
```

Consultez le Guide de l’[API Speech-to-text](/docs/fr/api-reference/speech-to-text/v-1-speech-to-text-realtime) pour en savoir plus sur la structure de la réponse.

Si la requête inclut une instruction [`transcript_edit`](/docs/fr/eleven-api/guides/how-to/speech-to-text/batch/transcript-editing), l’objet `transcription` contient également un champ `edited_transcript` avec le texte modifié.

Si la transcription échoue, votre point de terminaison reçoit à la place un événement `webhook_error`. Il ne contient pas d’objet `data` : il comprend un `request_id` de premier niveau, identique à l’identifiant renvoyé lors de l’acceptation de la requête, un `error_message` et les `webhook_metadata` de la requête.

## Implémenter votre point de terminaison de webhook

Voici un exemple d’implémentation d’un point de terminaison de webhook pour gérer les notifications entrantes :

```javascript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import express from "express";

const elevenlabs = new ElevenLabsClient();

const app = express();

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

// The raw body is required: verification runs over the exact bytes sent.
app.post("/webhook/speech-to-text", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["elevenlabs-signature"];

  let event;
  try {
    event = await elevenlabs.webhooks.constructEvent(
      req.body.toString(),
      signature,
      WEBHOOK_SECRET
    );
  } catch (error) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  if (event.type === "speech_to_text_transcription") {
    const { request_id, transcription } = event.data;

    console.log(`Transcription ${request_id} completed`);
    console.log(`Language: ${transcription.language_code}`);
    console.log(`Text: ${transcription.text}`);

    processTranscription(request_id, transcription);
  } else if (event.type === "webhook_error") {
    console.error(`Transcription ${event.request_id} failed: ${event.error_message}`);
    handleTranscriptionError(event.request_id, event.webhook_metadata, event.error_message);
  }

  res.status(200).json({ received: true });
});

async function processTranscription(requestId, transcription) {
  console.log("Processing completed transcription...");
}

async function handleTranscriptionError(requestId, webhookMetadata, errorMessage) {
  console.log("Handling transcription error...");
}

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});
```

## Considérations de sécurité

### Vérification de signature

Vérifiez toujours les signatures des webhooks pour vous assurer que les requêtes proviennent d’ElevenLabs.

### Exigence HTTPS

Les URL de webhook doivent utiliser HTTPS afin de garantir une transmission sécurisée des données de transcription.

### Limitation du débit

Implémentez une limitation du débit sur votre point de terminaison de webhook afin d’éviter les abus :

```javascript
import rateLimit from "express-rate-limit";

const webhookLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: "Too many webhook requests from this IP",
});

app.use("/webhook", webhookLimiter);
```

### Réponses en cas d’échec

Renvoyez un code de statut `2xx` pour accuser réception du webhook.

Par défaut, les webhooks de transcription Speech to Text ne sont envoyés qu’une fois. Toute réponse autre que `2xx` est considérée comme un échec de livraison, et les échecs répétés [désactivent automatiquement le webhook](/docs/fr/eleven-api/resources/webhooks#auto-disable-behavior).

Si vous activez les nouvelles tentatives pour le webhook, les livraisons échouées (`5xx`, `408`, `429` ou erreurs de connexion) font l’objet de cinq nouvelles tentatives au maximum, environ 30 secondes, 2 minutes, 8 minutes, 30 minutes et 30 minutes après la tentative précédente. Les autres réponses `4xx` ne font pas l’objet de nouvelle tentative. Chaque tentative pour le même événement comporte le même en-tête `ElevenLabs-Webhook-Delivery-Id`, votre gestionnaire peut donc ignorer les doublons.

Les requêtes effectuées avec `enable_logging` défini sur `false` (mode zéro rétention) bénéficient au maximum de deux nouvelles tentatives rapides, 5 secondes puis 30 secondes après la tentative précédente, lorsque les nouvelles tentatives sont activées. La transcription n’est jamais stockée.

Si une livraison échoue toujours, récupérez le résultat avec [Obtenir la transcription](/docs/fr/api-reference/speech-to-text/get) à l’aide de `transcription_id`, renvoyé lorsque la requête a été acceptée. Les transcriptions ne sont pas stockées pour les requêtes effectuées avec `enable_logging` défini sur `false`.

## Tester les webhooks

### Développement local

Pour les tests en local, utilisez des outils tels que [ngrok](https://ngrok.com/) afin d’exposer votre serveur local :

```bash
ngrok http 3000
```

Utilisez l’URL HTTPS fournie comme point de terminaison de webhook pendant le développement.

### Test des webhooks

Vous pouvez tester votre implémentation de webhook en effectuant une requête de transcription et en surveillant votre point de terminaison :

```javascript
async function testWebhook() {
  const audioFile = new File([audioBuffer], "test.mp3", { type: "audio/mp3" });

  const result = await elevenlabs.speechToText.convert({
    file: audioFile,
    modelId: "scribe_v2",
    webhook: true,
  });

  console.log("Test transcription started:", result.requestId);
}
```

## Étapes suivantes

#### [Streaming côté serveur](/docs/fr/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

Transcrivez l’audio en temps réel avec l’API de streaming basée sur WebSocket.

#### [Guide de l’API](/docs/fr/api-reference/speech-to-text)

Guide complet de l’API Speech to Text et de ses paramètres.