असिंक्रोनस स्पीच टू टेक्स्ट

परिचय

वेबहुक्स की मदद से आपके स्पीच टू टेक्स्ट ट्रांसक्रिप्शन टास्क पूरे होने पर आपको अपने-आप सूचनाएं मिलती हैं, इसलिए स्टेटस अपडेट के लिए API को लगातार पोल करने की जरूरत नहीं पड़ती। यह लंबे समय तक चलने वाले ट्रांसक्रिप्शन जॉब्स या बड़ी संख्या में ऑडियो फ़ाइलें प्रोसेस करते समय खास तौर पर उपयोगी है।

ट्रांसक्रिप्शन पूरा होने पर, ElevenLabs आपके तय किए गए वेबहुक URL पर ट्रांसक्रिप्शन नतीजों के साथ एक POST रिक्वेस्ट भेजेगा। इसमें ट्रांसक्रिप्ट टेक्स्ट, भाषा पहचान और कोई भी मेटाडेटा शामिल होगा।

वेबहुक्स का उपयोग

1

वेबहुक बनाएं या संपादित करें

ElevenLabs डैशबोर्ड में डेवलपर्स > वेबहुक्स पर जाएं। वेबहुक बनाएं पर क्लिक करें या किसी मौजूदा वेबहुक को संपादित करें।

वेबहुक को इन सेटिंग्स के साथ कॉन्फ़िगर करें:

• नाम: आपके वेबहुक के लिए एक वर्णनात्मक नाम
• कॉलबैक URL: आपका सार्वजनिक रूप से उपलब्ध HTTPS एंडपॉइंट
• वेबहुक ऑथ मेथड: HMAC या OAuth में से कोई एक। वेरिफ़िकेशन मैकेनिज़्म लागू करना क्लाइंट की ज़िम्मेदारी है। ElevenLabs ऐसे हेडर्स भेजता है जिनसे वेरिफ़िकेशन किया जा सकता है, लेकिन हम इसे लागू नहीं कराते।
• इवेंट्स: Transcription completed चुनें।

2

वेबहुक पैरामीटर चालू करके API कॉल करें

स्पीच-टू-टेक्स्ट API कॉल करते समय, उस खास रिक्वेस्ट के लिए वेबहुक सूचनाएं चालू करने हेतु webhook पैरामीटर को true पर सेट करें।

PythonTypeScript

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

वेबहुक पेलोड

ट्रांसक्रिप्शन पूरा होने पर, आपके वेबहुक एंडपॉइंट को ट्रांसक्रिप्शन और वेबहुक डेटा के साथ एक POST रिक्वेस्ट मिलेगी:

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

रिस्पॉन्स स्ट्रक्चर की जानकारी के लिए स्पीच-टू-टेक्स्ट API रेफरेंस देखें।

अगर रिक्वेस्ट में transcript_edit निर्देश शामिल था, तो transcription ऑब्जेक्ट में संपादित टेक्स्ट वाला edited_transcript फ़ील्ड भी होता है।

ट्रांसक्रिप्शन विफल होने पर, आपके एंडपॉइंट को इसकी जगह webhook_error इवेंट मिलता है। इसमें कोई data ऑब्जेक्ट नहीं होता: इसमें टॉप-लेवल request_id (वही id जो रिक्वेस्ट स्वीकार होने पर लौटाई गई थी), एक error_message और रिक्वेस्ट का webhook_metadata होता है।

अपना वेबहुक एंडपॉइंट लागू करना

इनकमिंग सूचनाएं संभालने के लिए वेबहुक एंडपॉइंट लागू करने का एक उदाहरण यहां दिया गया है:

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

सुरक्षा संबंधी बातें

सिग्नेचर वेरिफ़िकेशन

यह सुनिश्चित करने के लिए कि रिक्वेस्ट ElevenLabs से आई हैं, हमेशा वेबहुक सिग्नेचर्स वेरिफ़ाई करें।

HTTPS की आवश्यकता

ट्रांसक्रिप्शन डेटा का सुरक्षित ट्रांसमिशन सुनिश्चित करने के लिए वेबहुक URLs में HTTPS का उपयोग होना चाहिए।

रेट लिमिटिंग

दुरुपयोग रोकने के लिए अपने वेबहुक एंडपॉइंट पर रेट लिमिटिंग लागू करें:

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

विफलता रिस्पॉन्स

वेबहुक की पुष्टि के लिए 2xx स्टेटस कोड लौटाएं।

डिफ़ॉल्ट रूप से, स्पीच टू टेक्स्ट ट्रांसक्रिप्शन वेबहुक्स एक बार डिलीवर किए जाते हैं। हर गैर-2xx रिस्पॉन्स को असफल डिलीवरी माना जाता है और बार-बार विफल होने पर वेबहुक अपने-आप निष्क्रिय हो जाता है।

अगर आप वेबहुक के लिए रिट्राइज़ चालू करते हैं, तो असफल डिलीवरी (5xx, 408, 429 या कनेक्शन एरर) को पिछली कोशिश के लगभग 30 सेकंड, 2 मिनट, 8 मिनट, 30 मिनट और 30 मिनट बाद, 5 और बार रिट्राइ किया जाता है। अन्य 4xx रिस्पॉन्स को रिट्राइ नहीं किया जाता। एक ही इवेंट की हर कोशिश में वही ElevenLabs-Webhook-Delivery-Id हेडर होता है, इसलिए आपका हैंडलर डुप्लीकेट्स को अनदेखा कर सकता है।

enable_logging को false (ज़ीरो रिटेंशन मोड) पर सेट करके की गई रिक्वेस्ट्स को, रिट्राइज़ चालू होने पर, पिछली कोशिश के 5 सेकंड और 30 सेकंड बाद अधिकतम 2 त्वरित रिट्राइ मिलते हैं। ट्रांसक्रिप्ट कभी स्टोर नहीं किया जाता।

अगर डिलीवरी फिर भी विफल हो जाए, तो रिक्वेस्ट स्वीकार होने पर लौटाए गए transcription_id का उपयोग करके ट्रांसक्रिप्ट पाएं से नतीजा पाएं। enable_logging को false पर सेट करके की गई रिक्वेस्ट्स के ट्रांसक्रिप्ट स्टोर नहीं होते।

वेबहुक्स की टेस्टिंग

लोकल डेवलपमेंट

लोकल टेस्टिंग के लिए, अपने लोकल सर्वर को एक्सपोज़ करने हेतु ngrok जैसे टूल्स का उपयोग करें:

ngrok http 3000

डेवलपमेंट के दौरान दिए गए HTTPS URL को अपने वेबहुक एंडपॉइंट के रूप में उपयोग करें।

वेबहुक टेस्टिंग

आप ट्रांसक्रिप्शन रिक्वेस्ट करके और अपने एंडपॉइंट को मॉनिटर करके अपने वेबहुक इम्प्लीमेंटेशन को टेस्ट कर सकते हैं:

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

अगले कदम