HTTP pogreške i sigurnost API ključa
Na ovoj stranici
Ažurirano 3. studenog 2026., na temelju stranica xAI Text to Speech i Rate limits: tekst ograničen na 60.000 znakova, pogreška 404 (nepoznat glas) i ograničenja stope po razini. Izvori: Text to Speech · Rate limits.
Rukovanje pogreškama i zaštita vjerodajnica
U proizvodnji tvoja aplikacija mora pravilno obrađivati pogreške TTS API-ja i, prije svega, nikada ne smije izložiti tvoj API ključ na klijentskoj strani. Ova lekcija pokriva kodove pogrešaka, strategije ponovnih pokušaja i arhitekturu poslužiteljskog proxyja.
HTTP kodovi pogrešaka
TTS API vraća standardne HTTP kodove pogrešaka. Evo kako reagirati na svaki od njih.
400: Bad Request (Neispravan zahtjev)
Poslužitelj nije mogao obraditi tvoj zahtjev. Uobičajeni uzroci:
- Prazan tekst ili tekst dulji od 60.000 znakova
- Neispravan kodek (tipfeler u nazivu)
- Nepodržana frekvencija uzorkovanja
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Fix the parameters and try again
Nemoj automatski ponavljati pogrešku 400: problem je u tvom zahtjevu, a ne na poslužitelju. Prvo ispravi parametre.
401: Unauthorized (Neovlašteno)
API ključ je neispravan, istekao ili nedostaje:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Provjeri sljedeće:
- Zaglavlje
Authorizationje prisutno - Format je
Bearer xai-...(s razmakom nakon Bearer) - Ključ nije opozvan u xAI konzoli
404: Not Found (Nije pronađeno)
ID glasa je nepoznat: provjeri ga s GET /v1/tts/voices za ugrađeni glas ili GET /v1/custom-voices za prilagođeni glas. Kao i kod 400, pogreška 404 neće nestati ako pokušaš ponovno.
429: Too Many Requests (Previše zahtjeva)
Premašio/la si ograničenje stope: na ulaznoj razini, 50 zahtjeva u sekundi i 100 istovremenih sesija za TTS prema stranici Rate limits, te 50 istovremenih WebSocket sesija po timu prema stranici Text to Speech. xAI preporučuje ponovni pokušaj s eksponencijalnim kašnjenjem (exponential backoff):
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Try again
Implementiraj eksponencijalno kašnjenje za pogreške 429:
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 (Pogreška poslužitelja)
Poslužitelj ima privremeni problem. Pokušaj ponovno s eksponencijalnim kašnjenjem:
if response.status_code in (500, 503):
# Retry with exponential backoff
pass
Pogreške 503 često su uzrokovane privremenim preopterećenjem. Obično se riješe unutar nekoliko sekundi.
Nikada ne izlaži API ključ na klijentu
Ovo je najvažnije sigurnosno pravilo. Ako je tvoj API ključ vidljiv u JavaScriptu preglednika, bilo tko može:
- Besplatno koristiti tvoju kvotu
- Napraviti troškove na tvom računu
- Pristupiti svakoj xAI API endpoint točki s tvojim ključem
Arhitektura poslužiteljskog proxyja
Rješenje je proksimirati TTS pozive kroz vlastiti backend:
Browser -> Your backend -> xAI API
(no key) (API key) (TTS)
Primjer s 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));
});
Primjer s FastAPI-jem (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
Za TTS WebSocket, tvoj backend mora proslijeđivati poruke između klijenta i xAI API-ja:
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 tipa „fail-open“
TTS API pokreće moderaciju sadržaja asinkrono. To znači da moderacija ne blokira zahtjev: audio se generira i vraća čak i ako moderacija nije završila svoju analizu.
Ako se sadržaj označi kao neprikladan, izvještaj stiže naknadno. Stoga bi tvoja aplikacija trebala pokrenuti vlastitu moderaciju unaprijed ako je potrebno.
Ključne točke
- 400 = pogreška parametra (nemoj ponavljati; ispravi zahtjev)
- 401 = neispravan API ključ (provjeri zaglavlje Authorization)
- 429 = ograničena stopa (eksponencijalno kašnjenje)
- 500/503 = privremena pogreška poslužitelja (ponovi s kašnjenjem)
- Nikada ne izlaži API ključ u klijentskom kodu
- Proksimiraj sve TTS pozive kroz svoj backend
- Moderacija je tipa „fail-open“: dodaj vlastito filtriranje ako je potrebno