Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Chyby HTTP a zabezpečení API klíče

Lekce 13 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Zpracování chyb a ochrana pověření
  2. Chybové kódy HTTP
  3. Nikdy nezveřejňuj API klíč na straně klienta
  4. Moderace typu fail-open
  5. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě stránek xAI Text to Speech a Rate limits: text omezen na 60 000 znaků, chyba 404 (neznámý hlas) a limity rychlosti podle úrovně. Zdroje: Text to Speech · Rate limits.

Zpracování chyb a ochrana pověření

V produkčním prostředí musí tvoje aplikace elegantně zpracovávat chyby TTS API a především nikdy nezveřejňovat tvůj API klíč na straně klienta. Tato lekce pokrývá chybové kódy, strategie opakování a architekturu backendového proxy.

Chybové kódy HTTP

TTS API vrací standardní chybové kódy HTTP. Zde je návod, jak na každý z nich reagovat.

400: Bad Request (Špatný požadavek)

Server nedokázal zpracovat tvůj požadavek. Časté příčiny:

  • Prázdný text nebo text delší než 60 000 znaků
  • Neplatný kodek (překlep v názvu)
  • Nepodporovaná vzorkovací frekvence
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Chybu 400 neopakuj automaticky: problém je v tvém požadavku, ne na serveru. Nejprve oprav parametry.

401: Unauthorized (Neoprávněno)

API klíč je neplatný, vypršel nebo chybí:

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

Zkontroluj, zda:

  • Je přítomna hlavička Authorization
  • Formát je Bearer xai-... (s mezerou za slovem Bearer)
  • Klíč nebyl zrušen v konzoli xAI

404: Not Found (Nenalezeno)

ID hlasu je neznámé: ověř ho pomocí GET /v1/tts/voices pro vestavěný hlas nebo GET /v1/custom-voices pro vlastní hlas. Stejně jako u chyby 400, ani chyba 404 nezmizí, pokud požadavek zopakuješ.

429: Too Many Requests (Příliš mnoho požadavků)

Překročil jsi limit rychlosti: u vstupní úrovně je to 50 požadavků za sekundu a 100 souběžných relací pro TTS podle stránky Rate limits a 50 souběžných WebSocket relací na tým podle stránky Text to Speech. xAI doporučuje opakovat s exponenciálním zpětným čekáním (exponential backoff):

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

Pro chyby 429 implementuj exponenciální zpětné čekání:

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: Server Error (Chyba serveru)

Server má dočasný problém. Opakuj s exponenciálním zpětným čekáním:

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

Chyby 503 jsou často způsobeny dočasným přetížením. Obvykle se vyřeší během několika sekund.

Nikdy nezveřejňuj API klíč na straně klienta

Toto je nejdůležitější bezpečnostní pravidlo. Pokud je tvůj API klíč viditelný v JavaScriptu prohlížeče, kdokoli může:

  • Využívat tvou kvótu zdarma
  • Navýšit poplatky na tvém účtu
  • Přistupovat ke každému koncovému bodu API xAI s tvým klíčem

Architektura backendového proxy

Řešením je směrovat volání TTS přes tvůj vlastní backend:

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

Příklad v Express.js

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

Příklad ve FastAPI (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"]
    )

Proxy pro WebSocket

U TTS WebSocket musí tvůj backend přeposílat zprávy mezi klientem a API xAI:

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

Moderace typu fail-open

API TTS spouští moderaci obsahu asynchronně. To znamená, že moderace neblokuje požadavek: audio je vygenerováno a vráceno, i když moderace ještě nedokončila svou analýzu.

Pokud je obsah označen jako nevhodný, zpráva přijde dodatečně. Tvá aplikace by proto měla v případě potřeby spustit vlastní moderaci předem (upstream).

Klíčové poznatky

  • 400 = chyba parametru (neopakovat; opravit požadavek)
  • 401 = neplatný API klíč (zkontroluj hlavičku Authorization)
  • 429 = překročen limit rychlosti (exponenciální zpětné čekání)
  • 500/503 = dočasná chyba serveru (opakovat s exponenciálním zpětným čekáním)
  • Nikdy nezveřejňuj API klíč v kódu klienta
  • Směruj všechna volání TTS přes svůj backend
  • Moderace je typu fail-open: v případě potřeby přidej vlastní filtrování