Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Napake HTTP in varnost ključa API

Lekcija 13 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Obravnava napak in zaščita poverilnic
  2. Kode napak HTTP
  3. Nikoli ne razkrij ključa API na strani odjemalca
  4. Moderacija z načelom “fail-open”
  5. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi strani xAI Text to Speech in Rate limits: besedilo omejeno na 60.000 znakov, napaka 404 (neznani glas) in omejitve hitrosti po ravneh. Viri: Text to Speech · Rate limits.

Obravnava napak in zaščita poverilnic

V proizvodnem okolju mora tvoja aplikacija ustrezno obravnavati napake API-ja TTS in predvsem nikoli ne sme razkriti tvojega ključa API na strani odjemalca. Ta lekcija pokriva kode napak, strategije ponovnih poskusov in arhitekturo posredniškega strežnika (backend proxy).

Kode napak HTTP

API TTS vrača standardne kode napak HTTP. Tukaj je opisano, kako reagirati na vsako izmed njih.

400: Bad Request (Neveljaven zahtevek)

Strežnik ni mogel obdelati tvojega zahtevka. Pogosti vzroki:

  • Prazno besedilo ali besedilo, daljše od 60.000 znakov
  • Neveljaven kodek (napaka v imenu)
  • Nepodprta vzorčna frekvenca
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Napake 400 ne poskušaj samodejno ponoviti: težava je v tvojem zahtevku, ne na strežniku. Najprej popravi parametre.

401: Unauthorized (Nepooblaščeno)

Ključ API je neveljaven, potekel ali manjka:

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

Preveri naslednje:

  • Ali je glava Authorization prisotna
  • Ali je format Bearer xai-... (s presledkom za besedo Bearer)
  • Ali ključ ni bil preklican v konzoli xAI

404: Not Found (Ni najdeno)

ID glasu je neznan: preveri ga z GET /v1/tts/voices za vgrajeni glas ali z GET /v1/custom-voices za glas po meri. Tako kot pri napaki 400 tudi napaka 404 ne bo izginila, če poskus ponoviš.

429: Too Many Requests (Preveč zahtevkov)

Prekoračil si omejitev hitrosti: na osnovni ravni velja 50 zahtevkov na sekundo in 100 sočasnih sej za TTS glede na stran Rate limits, ter 50 sočasnih sej WebSocket na ekipo glede na stran Text to Speech. xAI priporoča ponovni poskus z eksponentnim zamikom (exponential backoff):

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

Za napake 429 implementiraj eksponentni zamik:

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 (Napaka strežnika)

Strežnik ima začasno težavo. Poskusi znova z uporabo eksponentnega zamika:

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

Napake 503 so pogosto posledica začasne preobremenitve. Običajno se razrešijo v nekaj sekundah.

Nikoli ne razkrij ključa API na strani odjemalca

To je najpomembnejše varnostno pravilo. Če je tvoj ključ API viden v JavaScriptu brskalnika, lahko kdorkoli:

  • Brezplačno porabi tvojo kvoto
  • Ti povzroči stroške na računu
  • Dostopa do vsake končne točke API xAI s tvojim ključem

Arhitektura posredniškega strežnika (Backend proxy)

Rešitev je posredovanje klicev TTS prek tvojega lastnega zaledja (backend):

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

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

Primer s 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"]
    )

Posrednik WebSocket

Za WebSocket TTS mora tvoje zaledje posredovati sporočila med odjemalcem in API-jem 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());
});

Moderacija z načelom “fail-open”

API TTS izvaja moderacijo vsebine asinhrono. To pomeni, da moderacija ne blokira zahtevka: zvok se ustvari in vrne, tudi če moderacija še ni zaključila svoje analize.

Če je vsebina označena kot neustrezna, poročilo prispe naknadno. Zato naj tvoja aplikacija po potrebi sama izvaja moderacijo vnaprej (upstream).

Ključne ugotovitve

  • 400 = napaka parametra (ne ponavljaj; popravi zahtevek)
  • 401 = neveljaven ključ API (preveri glavo Authorization)
  • 429 = omejitev hitrosti (eksponentni zamik)
  • 500/503 = začasna napaka strežnika (ponovi z zamikom)
  • Nikoli ne razkrij ključa API v kodi odjemalca
  • Vse klice TTS posreduj prek svojega zaledja
  • Moderacija deluje po načelu “fail-open”: po potrebi dodaj svoje filtriranje