Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

HTTP klaidos ir API rakto saugumas

Paskaita 13 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Klaidų valdymas ir prisijungimo duomenų apsauga
  2. HTTP klaidų kodai
  3. Niekada neatskleisk API rakto kliento pusėje
  4. „Fail-open“ moderavimas
  5. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d., remiantis xAI Text to Speech ir Rate limits puslapiais: tekstas ribojamas iki 60 000 simbolių, 404 klaida (nežinomas balsas) ir užklausų limitai pagal lygį. Šaltiniai: Text to Speech · Rate limits.

Klaidų valdymas ir prisijungimo duomenų apsauga

Gamybos aplinkoje tavo programa turi tinkamai apdoroti TTS API klaidas ir, svarbiausia, niekada neatskleisti savo API rakto kliento pusėje. Šioje pamokoje nagrinėjami klaidų kodai, kartojimo strategijos ir tarpinio serverio (backend proxy) architektūra.

HTTP klaidų kodai

TTS API grąžina standartinius HTTP klaidų kodus. Štai kaip reaguoti į kiekvieną iš jų.

400: Bad Request (Neteisinga užklausa)

Serveris negalėjo apdoroti tavo užklausos. Dažniausios priežastys:

  • Tuščias tekstas arba tekstas, viršijantis 60 000 simbolių
  • Netinkamas kodekas (raidybos klaida pavadinime)
  • Nepalaikomas diskretizavimo dažnis (sample rate)
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Ne kartok 400 klaidos automatiškai: problema yra tavo užklausoje, o ne serveryje. Pirmiausia sutvarkyk parametrus.

401: Unauthorized (Neteisėta prieiga)

API raktas yra neteisingas, galiojimas baigėsi arba jo trūksta:

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

Patikrink, ar:

  • Yra Authorization antraštė
  • Formatas yra Bearer xai-... (su tarpu po žodžio „Bearer“)
  • Raktas nebuvo atšauktas xAI konsolėje

404: Not Found (Nerasta)

Balso ID nežinomas: patikrink jį naudodamas GET /v1/tts/voices integruotam balsui arba GET /v1/custom-voices tinkintam balsui. Kaip ir 400 atveju, 404 klaida neišnyks, jei bandysi kartoti užklausą.

429: Too Many Requests (Per daug užklausų)

Viršijai užklausų limitą: pradiniame lygyje – 50 užklausų per sekundę ir 100 vienu metu vykdomų sesijų TTS pagal puslapį Rate limits, bei 50 vienu metu vykdomų WebSocket sesijų komandai pagal puslapį Text to Speech. xAI rekomenduoja kartoti užklausą taikant eksponentinį delsą (exponential backoff):

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

Įgyvendink eksponentinį delsą 429 klaidoms:

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 (Serverio klaida)

Serveris turi laikinų problemų. Kartok užklausą taikydamas delsą:

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

503 klaidas dažnai sukelia laikina perkrova. Jos paprastai išsprendžiamos per kelias sekundes.

Niekada neatskleisk API rakto kliento pusėje

Tai yra svarbiausia saugumo taisyklė. Jei tavo API raktas matomas naršyklės „JavaScript“ kode, bet kas gali:

  • Naudoti tavo kvotą nemokamai
  • Sukaupti mokesčius tavo sąskaitoje
  • Pasiekti kiekvieną xAI API galutinį tašką su tavo raktu

Tarpinio serverio (Backend proxy) architektūra

Sprendimas – perduoti TTS užklausas per savo tarpinį serverį:

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

„Express.js“ pavyzdys

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“ pavyzdys (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 tarpinis serveris

TTS WebSocket atveju tavo tarpinis serveris turi perduoti žinutes tarp kliento ir xAI API:

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“ moderavimas

TTS API vykdo turinio moderavimą asinchroniškai. Tai reiškia, kad moderavimas nestabdo užklausos: garso įrašas sugeneruojamas ir grąžinamas net jei moderavimas dar nėra baigęs analizės.

Jei turinys pažymimas kaip netinkamas, pranešimas ateina post factum. Todėl tavo programa turėtų vykdyti savo moderavimą iš anksto, jei to reikia.

Svarbiausi punktai

  • 400 = parametro klaida (nekartok; sutvarkyk užklausą)
  • 401 = neteisingas API raktas (patikrink „Authorization“ antraštę)
  • 429 = viršytas limitas (eksponentinis delsas)
  • 500/503 = laikina serverio klaida (kartok su delsos mechanizmu)
  • Niekada neatskleisk API rakto kliento kode
  • Visas TTS užklausas perduok per savo tarpinį serverį
  • Moderavimas veikia „fail-open“ režimu: prireikus pridėk savo filtravimą