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

# Asynchroniczna zamiana mowy na tekst

> **Note**
>
> **Przewodnik krok po kroku** · Zakłada ukończenie [krótkiego wprowadzenia do Speech to Text ](/docs/pl/eleven-api/guides/cookbooks/speech-to-text).

## Omówienie

Webhooki pozwalają automatycznie otrzymywać powiadomienia po ukończeniu zadań transkrypcji Speech to Text, więc nie musisz stale odpytywać API o aktualizacje statusu. Jest to szczególnie przydatne przy długich zadaniach transkrypcji lub przetwarzaniu dużej liczby plików audio.

Po ukończeniu transkrypcji ElevenLabs wyśle żądanie POST na wskazany adres URL webhooka wraz z wynikami transkrypcji, w tym tekstem transkrypcji, wykrytym językiem i metadanymi.

## Korzystanie z webhooków

> **Note**
>
> Ten przewodnik zakłada, że [skonfigurowałeś klucz API i SDK](/docs/pl/eleven-api/quickstart). Jeśli jeszcze tego nie zrobiłeś, najpierw ukończ
> krótkie wprowadzenie.

#### Utwórz lub edytuj webhook

W panelu ElevenLabs przejdź do
[**Deweloperzy** > **Webhooki**](https://elevenlabs.io/app/developers/webhooks).
Kliknij **Utwórz webhook** lub edytuj istniejący webhook.

![Okno tworzenia webhooka z wybraną opcją Transcription completed](/docs/_fern-img/866f389106e74e16586a4d68cf8160f2d27568518ff4f984c2fab81cbd1674c9.webp)

Skonfiguruj webhook:

* **Nazwa**: Opisowa nazwa webhooka
* **Adres URL wywołania zwrotnego**: Publicznie dostępny endpoint HTTPS
* **Metoda uwierzytelniania webhooka**: `HMAC` lub `OAuth`. Klient odpowiada za wdrożenie mechanizmu weryfikacji. ElevenLabs wysyła nagłówki umożliwiające weryfikację, ale jej nie wymuszamy.
* **Zdarzenia**: Wybierz **Transcription completed**.

#### Wykonuj wywołania API z włączonym parametrem webhook

Podczas wywołań API zamiany mowy na tekst dodaj parametr `webhook` ustawiony na `true`, aby włączyć powiadomienia webhooka dla tego żądania.

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

## Dane webhooka

Po ukończeniu transkrypcji endpoint webhooka otrzyma żądanie POST z danymi transkrypcji i webhooka:

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

Szczegóły struktury odpowiedzi znajdziesz w dokumentacji [Speech-to-text API](/docs/pl/api-reference/speech-to-text/v-1-speech-to-text-realtime).

Jeśli żądanie zawierało instrukcję [`transcript_edit`](/docs/pl/eleven-api/guides/how-to/speech-to-text/batch/transcript-editing), obiekt `transcription` zawiera też pole `edited_transcript` z edytowanym tekstem.

Jeśli transkrypcja się nie powiedzie, endpoint otrzyma zdarzenie `webhook_error`. Nie ma ono obiektu `data`: zawiera główne pole `request_id` (ten sam identyfikator, który zwrócono po przyjęciu żądania), `error_message` oraz `webhook_metadata` żądania.

## Implementacja endpointu webhooka

Oto przykład implementacji endpointu webhooka do obsługi przychodzących powiadomień:

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

## Kwestie bezpieczeństwa

### Weryfikacja podpisu

Zawsze weryfikuj podpisy webhooków, aby upewnić się, że żądania pochodzą z ElevenLabs.

### Wymaganie HTTPS

Adresy URL webhooków muszą używać HTTPS, aby zapewnić bezpieczne przesyłanie danych transkrypcji.

### Ograniczanie liczby żądań

Wdróż ograniczanie liczby żądań na endpointcie webhooka, aby zapobiec nadużyciom:

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

### Odpowiedzi na błędy

Zwróć kod statusu `2xx`, aby potwierdzić odbiór webhooka.

Domyślnie webhooki transkrypcji Speech to Text są dostarczane raz. Każda odpowiedź inna niż `2xx` jest uznawana za nieudane dostarczenie, a powtarzające się błędy [automatycznie wyłączają webhook](/docs/pl/eleven-api/resources/webhooks#auto-disable-behavior).

Jeśli włączysz ponawianie prób dla webhooka, nieudane dostarczenia (`5xx`, `408`, `429` lub błędy połączenia) są ponawiane maksymalnie 5 razy: około 30 sekund, 2 minuty, 8 minut, 30 minut i 30 minut po poprzedniej próbie. Inne odpowiedzi `4xx` nie są ponawiane. Każda próba dla tego samego zdarzenia zawiera ten sam nagłówek `ElevenLabs-Webhook-Delivery-Id`, więc handler może ignorować duplikaty.

Żądania z `enable_logging` ustawionym na `false` (tryb zerowej retencji) otrzymują maksymalnie 2 szybkie ponowienia — 5 i 30 sekund po poprzedniej próbie — gdy ponawianie jest włączone. Transkrypcja nigdy nie jest zapisywana.

Jeśli dostarczenie nadal się nie powiedzie, pobierz wynik za pomocą [Get transcript](/docs/pl/api-reference/speech-to-text/get), używając `transcription_id` zwróconego po przyjęciu żądania. Transkrypcje nie są przechowywane dla żądań z `enable_logging` ustawionym na `false`.

## Testowanie webhooków

### Lokalny development

Do lokalnych testów użyj narzędzi takich jak [ngrok](https://ngrok.com/), aby udostępnić lokalny serwer:

```bash
ngrok http 3000
```

Podczas developmentu użyj podanego adresu HTTPS jako endpointu webhooka.

### Testowanie webhooka

Możesz przetestować implementację webhooka, wysyłając żądanie transkrypcji i monitorując endpoint:

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

## Kolejne kroki

#### [Streaming po stronie serwera](/docs/pl/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

Transkrybuj audio w czasie rzeczywistym za pomocą streamingowego API opartego na WebSocket.

#### [Dokumentacja API](/docs/pl/api-reference/speech-to-text)

Pełna dokumentacja Speech to Text API i parametrów.