Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

HTTP-hibák és az API-kulcsok biztonsága

13. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Hibakezelés és hitelesítő adataid védelme
  2. HTTP-hibakódok
  3. Soha ne tedd ki az API-kulcsot a kliens oldalon
  4. „Fail-open“ moderáció
  5. Főbb megállapítások

Frissítve: 2026. november 3., az xAI Text to Speech és Rate limits oldalai alapján: a szöveg 60 000 karakterre korlátozott, a 404-es hiba (ismeretlen hang), valamint a szintenkénti sebességkorlátok. Források: Text to Speech · Rate limits.

Hibakezelés és hitelesítő adataid védelme

Éles környezetben az alkalmazásodnak hibamentesen kell kezelnie a TTS API hibáit, és mindenekelőtt soha nem szabad kitenned az API-kulcsodat a kliens oldalon. Ez a lecke a hibakódokat, az újrapróbálkozási stratégiákat és a backend proxy architektúrát tárgyalja.

HTTP-hibakódok

A TTS API szabványos HTTP-hibakódokat ad vissza. Íme, hogyan reagálj az egyes esetekre.

400: Rossz kérés (Bad Request)

A szerver nem tudta feldolgozni a kérésedet. Gyakori okok:

  • Üres szöveg vagy 60 000 karakternél hosszabb szöveg
  • Érvénytelen kodek (elírás a névben)
  • Nem támogatott mintavételezési frekvencia
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Ne próbáld meg automatikusan újraindítani a 400-as hibát: a probléma a kérésedben van, nem a szerveren. Először javítsd a paramétereket.

401: Jogosulatlan (Unauthorized)

Az API-kulcs érvénytelen, lejárt vagy hiányzik:

if response.status_code == 401:
    raise AuthenticationError("Invalid or expired API key")

Ellenőrizd a következőket:

  • Az Authorization fejléc jelen van-e
  • A formátum Bearer xai-... (szóközzel a Bearer után)
  • A kulcsot nem vonták-e vissza az xAI konzolban

404: Nem található (Not Found)

A hangazonosító ismeretlen: ellenőrizd a GET /v1/tts/voices végponttal a beépített hangok esetén, vagy a GET /v1/custom-voices végponttal az egyéni hangoknál. Akárcsak a 400-as hiba, a 404-es sem szűnik meg újrapróbálkozásra.

429: Túl sok kérés (Too Many Requests)

Túllépted a sebességkorlátot: a belépő szinten másodpercenként 50 kérés és 100 egyidejű munkamenet engedélyezett a TTS-hez a Rate limits oldal szerint, valamint csapatonként 50 egyidejű WebSocket-munkamenet a Text to Speech oldal alapján. Az xAI exponenciális visszalépéssel (exponential backoff) történő újrapróbálkozást javasol:

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    await asyncio.sleep(retry_after)
    # Try again

Implementálj exponenciális visszalépést a 429-es hibákhoz:

async def request_with_backoff(url, payload, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, json=payload, headers=headers)

        if response.status_code == 200:
            return response

        if response.status_code == 429:
            wait = min(2 ** attempt + random.random(), 60)
            print(f"Rate limited. Waiting {wait:.1f}s")
            await asyncio.sleep(wait)
            continue

        if response.status_code >= 500:
            wait = min(2 ** attempt + random.random(), 30)
            await asyncio.sleep(wait)
            continue

        # Client error (400, 401): don't retry
        response.raise_for_status()

    raise Exception("Failed after 5 attempts")

500 / 503: Szerverhiba

A szervernek átmeneti problémája van. Próbáld újra visszalépéssel:

if response.status_code in (500, 503):
    # Retry with exponential backoff
    pass

Az 503-as hibákat gyakran ideiglenes túlterhelés okozza. Általában néhány másodpercen belül megoldódnak.

Soha ne tedd ki az API-kulcsot a kliens oldalon

Ez a legfontosabb biztonsági szabály. Ha az API-kulcsod látható a böngésző JavaScript kódjában, bárki képes lehet:

  • Ingyenesen felhasználni a kvótádat
  • Költségeket generálni a fiókod terhére
  • Hozzáférni minden xAI API-végponthoz a kulcsoddal

Backend proxy architektúra

A megoldás az, hogy a TTS-hívásokat a saját backendeden keresztül proxyzod:

Browser -> Your backend -> xAI API
 (no key)    (API key)      (TTS)

Express.js példa

const express = require("express");
const app = express();

app.post("/api/tts", async (req, res) => {
  const { text, voice_id, language } = req.body;

  // Server-side validation
  if (!text || text.length > 60000) {
    return res.status(400).json({ error: "Invalid text" });
  }

  const response = await fetch("https://api.x.ai/v1/tts", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ text, voice_id, language })
  });

  if (!response.ok) {
    return res.status(response.status).json({
      error: "TTS error"
    });
  }

  // Pass the audio on to the client
  res.set("Content-Type", response.headers.get("Content-Type"));
  const buffer = await response.arrayBuffer();
  res.send(Buffer.from(buffer));
});

FastAPI példa (Python)

from fastapi import FastAPI, HTTPException
from fastapi.responses import Response
import httpx

app = FastAPI()

@app.post("/api/tts")
async def proxy_tts(text: str, voice_id: str = "eve", language: str = "en"):
    if len(text) > 60000:
        raise HTTPException(400, "Text too long")

    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.x.ai/v1/tts",
            headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
            json={"text": text, "voice_id": voice_id, "language": language}
        )

    if response.status_code != 200:
        raise HTTPException(response.status_code, "TTS error")

    return Response(
        content=response.content,
        media_type=response.headers["content-type"]
    )

WebSocket proxy

A TTS WebSocket esetén a backendednek továbbítania kell az üzeneteket a kliens és az xAI API között:

const WebSocket = require("ws");

wss.on("connection", (clientWs) => {
  const xaiWs = new WebSocket(
    "wss://api.x.ai/v1/tts?language=en&voice=eve",
    { headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` } }
  );

  // Relay client -> xAI
  clientWs.on("message", (msg) => xaiWs.send(msg));

  // Relay xAI -> client
  xaiWs.on("message", (msg) => clientWs.send(msg));

  // Handle closing
  clientWs.on("close", () => xaiWs.close());
  xaiWs.on("close", () => clientWs.close());
});

„Fail-open“ moderáció

A TTS API a tartalommoderációt aszinkron módon végzi. Ez azt jelenti, hogy a moderáció nem blokkolja a kérést: a hanganyag generálódik és visszaadásra kerül akkor is, ha a moderáció még nem fejezte be az elemzést.

Ha a tartalmat nem megfelelőnek minősítik, a jelentés utólag érkezik. Ezért az alkalmazásodnak szükség esetén saját moderációt kell futtatnia upstream (a kérés előtt).

Főbb megállapítások

  • 400 = paraméterhiba (ne próbáld újra; javítsd a kérést)
  • 401 = érvénytelen API-kulcs (ellenőrizd az Authorization fejlécet)
  • 429 = sebességkorlát (exponenciális visszalépés)
  • 500/503 = átmeneti szerverhiba (próbáld újra visszalépéssel)
  • Soha ne tedd ki az API-kulcsot a kliens kódban
  • Minden TTS-hívást proxyzz a backendeden keresztül
  • A moderáció „fail-open“: szükség esetén alkalmazz saját szűrést