Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

HTTP kļūdas un API atslēgu drošība

Nodarbība 13 no 14 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Kļūdu apstrāde un akreditācijas datu aizsardzība
  2. HTTP kļūdu kodi
  3. Nekad neatklāj API atslēgu klienta pusē
  4. „Fail-open” moderācija
  5. Galvenās atziņas

Atjaunināts 2026. gada 3. novembrī, pamatojoties uz xAI Text to Speech un Rate limits lapām: teksts ierobežots līdz 60 000 rakstzīmēm, 404 kļūda (nezināma balss) un pieprasījumu limiti pa līmeņiem. Avoti: Text to Speech · Rate limits.

Kļūdu apstrāde un akreditācijas datu aizsardzība

Produkcijas vidē tavai lietotnei ir korekti jāapstrādā TTS API kļūdas un, pats galvenais, nekad nedrīkst atklāt API atslēgu klienta pusē. Šajā nodarbībā aplūkoti kļūdu kodi, atkārtošanas stratēģijas un aizmugures servera (backend) starpnieka arhitektūra.

HTTP kļūdu kodi

TTS API atgriež standarta HTTP kļūdu kodus. Lūk, kā reaģēt uz katru no tiem.

400: Bad Request (Nepareizs pieprasījums)

Serveris nevarēja apstrādāt tavu pieprasījumu. Biežākie cēloņi:

  • Tukšs teksts vai teksts, kas pārsniedz 60 000 rakstzīmes
  • Nederīgs kodeks (kļūda nosaukumā)
  • Neatbalstīts diskretizācijas biežums (sample rate)
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Nemēģini automātiski atkārtot 400 kļūdu: problēma ir tavā pieprasījumā, nevis serverī. Vispirms izlabo parametrus.

401: Unauthorized (Nesankcionēta piekļuve)

API atslēga ir nederīga, beigusies tās derīguma termiņš vai tā trūkst:

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

Pārbaudi, vai:

  • Ir norādīta Authorization galvene
  • Formāts ir Bearer xai-... (ar atstarpi pēc Bearer)
  • Atslēga nav atsaukta xAI konsolē

404: Not Found (Nav atrasts)

Balss ID ir nezināms: pārbaudi to, izmantojot GET /v1/tts/voices iebūvētai balsij vai GET /v1/custom-voices pielāgotai balsij. Tāpat kā 400 gadījumā, 404 kļūda nepazudīs, ja mēģināsi atkārtot pieprasījumu.

429: Too Many Requests (Pārāk daudz pieprasījumu)

Esi pārsniedzis pieprasījumu limitu: ieejas līmenī tas ir 50 pieprasījumi sekundē un 100 vienlaicīgas sesijas priekš TTS saskaņā ar Rate limits lapu, kā arī 50 vienlaicīgas WebSocket sesijas uz komandu saskaņā ar Text to Speech lapu. xAI iesaka mēģināt vēlreiz, izmantojot eksponenciālu pauzi (exponential backoff):

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

Ievies eksponenciālu pauzi 429 kļūdām:

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 (Servera kļūda)

Serverim ir pagaidu problēmas. Mēģini vēlreiz ar pauzi:

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

503 kļūdas bieži izraisa pagaidu pārslodze. Tās parasti izzūd dažu sekunžu laikā.

Nekad neatklāj API atslēgu klienta pusē

Šis ir vissvarīgākais drošības noteikums. Ja tava API atslēga ir redzama pārlūka JavaScript kodā, jebkurš var:

  • Izmantot tavu kvotu bezmaksas
  • Radīt izmaksas tavam kontam
  • Piekļūt katram xAI API galapunktam ar tavu atslēgu

Aizmugures servera starpnieka arhitektūra

Risinājums ir novirzīt TTS izsaukumus caur savu aizmugures serveri:

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

Express.js piemērs

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 piemērs (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 starpnieks

Priekš TTS WebSocket tavam aizmugures serverim ir jānodod ziņojumi starp klientu un 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” moderācija

TTS API veic satura moderāciju asinhroni. Tas nozīmē, ka moderācija nebloķē pieprasījumu: audio tiek ģenerēts un atgriezts, pat ja moderācija vēl nav pabeigusi analīzi.

Ja saturs tiek atzīmēts kā nepiemērots, ziņojums par to pienāk pēc fakta. Tāpēc tavai lietotnei vajadzētu veikt savu moderāciju iepriekš, ja tas ir nepieciešams.

Galvenās atziņas

  • 400 = parametra kļūda (neatkārto; izlabo pieprasījumu)
  • 401 = nederīga API atslēga (pārbaudi Authorization galveni)
  • 429 = sasniegts pieprasījumu limits (eksponenciāla pauze)
  • 500/503 = pagaidu servera kļūda (atkārto ar pauzi)
  • Nekad neatklāj API atslēgu klienta kodā
  • Novirzi visus TTS izsaukumus caur savu aizmugures serveri
  • Moderācija darbojas pēc „fail-open” principa: pievieno savu filtrēšanu, ja nepieciešams