> 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.

# Asynchrones Speech to Text

> **Note**
>
> **Anleitung** · Setzt voraus, dass Sie den [Speech to Text Schnellstart](/docs/de/eleven-api/guides/cookbooks/speech-to-text) abgeschlossen haben.

## Überblick

Webhooks ermöglichen automatische Benachrichtigungen, wenn Ihre Speech-to-Text-Transkriptionsaufgaben abgeschlossen sind. So müssen Sie die API nicht kontinuierlich nach Statusupdates abfragen. Das ist besonders nützlich für lang laufende Transkriptionsjobs oder die Verarbeitung großer Mengen an Audiodateien.

Wenn eine Transkription abgeschlossen ist, sendet ElevenLabs eine POST-Anfrage mit den Transkriptionsergebnissen an Ihre angegebene Webhook-URL, einschließlich Transkripttext, Spracherkennung und Metadaten.

## Webhooks verwenden

> **Note**
>
> Diese Anleitung setzt voraus, dass Sie [Ihren API-Schlüssel und das SDK eingerichtet haben](/docs/de/eleven-api/quickstart). Schließen Sie
> zuerst den Schnellstart ab, falls noch nicht geschehen.

#### Webhook erstellen oder bearbeiten

Öffnen Sie im ElevenLabs-Dashboard
[**Entwickler** > **Webhooks**](https://elevenlabs.io/app/developers/webhooks).
Klicken Sie auf **Webhook erstellen** oder bearbeiten Sie einen vorhandenen Webhook.

![Dialog zum Erstellen eines Webhooks mit ausgewählter Option Transkription abgeschlossen](/docs/_fern-img/866f389106e74e16586a4d68cf8160f2d27568518ff4f984c2fab81cbd1674c9.webp)

Konfigurieren Sie den Webhook mit:

* **Name**: Ein aussagekräftiger Name für Ihren Webhook
* **Callback-URL**: Ihr öffentlich zugänglicher HTTPS-Endpunkt
* **Webhook-Authentifizierungsmethode**: Entweder `HMAC` oder `OAuth`. Die Implementierung des Verifizierungsmechanismus liegt beim Client. ElevenLabs sendet Header zur Verifizierung, erzwingt diese jedoch nicht.
* **Ereignisse**: Wählen Sie **Transkription abgeschlossen**.

#### API-Aufrufe mit aktiviertem Webhook-Parameter ausführen

Fügen Sie bei Speech-to-Text-API-Aufrufen den Parameter `webhook` mit dem Wert `true` hinzu, um Webhook-Benachrichtigungen für diese Anfrage zu aktivieren.

```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;
  }
}
```

## Webhook-Payload

Wenn eine Transkription abgeschlossen ist, erhält Ihr Webhook-Endpunkt eine POST-Anfrage mit Transkriptions- und Webhook-Daten:

```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"
        }
      ]
    }
  }
}
```

Details zur Struktur der Antwort finden Sie in der Referenz zur [Speech-to-Text-API](/docs/de/api-reference/speech-to-text/v-1-speech-to-text-realtime).

Wenn die Anfrage eine [`transcript_edit`](/docs/de/eleven-api/guides/how-to/speech-to-text/batch/transcript-editing)-Anweisung enthielt, enthält das `transcription`-Objekt zusätzlich ein Feld `edited_transcript` mit dem bearbeiteten Text.

## Ihren Webhook-Endpunkt implementieren

Hier ist ein Beispiel für die Implementierung eines Webhook-Endpunkts zur Verarbeitung eingehender Benachrichtigungen:

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

const elevenlabs = new ElevenLabsClient();

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/speech-to-text', (req, res) => {
  try {
    const signature = req.headers['elevenlabs-signature'];
    const payload = JSON.stringify(req.body);
    let event;

    try {
      // Verify the webhook signature.
      event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
    } catch (error) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    if (event.type === 'speech_to_text.completed') {
      const { requestId, status, text, language_code } = event.data;

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

      processTranscription(requestId, text, language_code);
    } else if (status === 'failed') {
      console.error(`Transcription ${requestId} failed`);
      handleTranscriptionError(requestId);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

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

async function handleTranscriptionError(requestId) {
  console.log('Handling transcription error...');
}

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

## Sicherheitsaspekte

### Signaturverifizierung

Verifizieren Sie Webhook-Signaturen immer, um sicherzustellen, dass Anfragen von ElevenLabs stammen.

### HTTPS-Anforderung

Webhook-URLs müssen HTTPS verwenden, damit Transkriptionsdaten sicher übertragen werden.

### Ratenbegrenzung

Implementieren Sie eine Ratenbegrenzung für Ihren Webhook-Endpunkt, um Missbrauch zu verhindern:

```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);
```

### Fehlerantworten

Geben Sie passende HTTP-Statuscodes zurück:

* `200-299`: Erfolg – Webhook wurde erfolgreich verarbeitet
* `400-499`: Client-Fehler – Webhook wird nicht erneut versucht
* `500-599`: Serverfehler – Webhook wird erneut versucht

## Webhooks testen

### Lokale Entwicklung

Für lokale Tests können Sie Tools wie [ngrok](https://ngrok.com/) verwenden, um Ihren lokalen Server öffentlich zugänglich zu machen:

```bash
ngrok http 3000
```

Verwenden Sie während der Entwicklung die bereitgestellte HTTPS-URL als Ihren Webhook-Endpunkt.

### Webhook-Tests

Sie können Ihre Webhook-Implementierung testen, indem Sie eine Transkriptionsanfrage ausführen und Ihren Endpunkt überwachen:

```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);
}
```

## Nächste Schritte

#### [Serverseitiges Streaming](/docs/de/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

Transkribieren Sie Audio in Echtzeit mit der WebSocket-basierten Streaming-API.

#### [API-Referenz](/docs/de/api-reference/speech-to-text)

Vollständige Speech-to-Text-API-Referenz und Parameter.