HTTP vead ja API võtme turvalisus
Sellel lehel
Uuendatud 3. novembril 2026, tuginedes xAI Text to Speech ja Rate limits lehekülgedele: teksti piirang 60 000 tähemärgini, 404 viga (tundmatu hääl) ja kasutuspiirangud tasemeti. Allikad: Text to Speech · Rate limits.
Veakäsitlus ja oma mandaatide kaitsmine
Tootmises peab sinu rakendus TTS API vigu sujuvalt käsitlema ja eelkõige mitte kunagi avaldama oma API võtit kliendipoolses koodis. See tund õpetab veakoode, uuesti proovimise strateegiaid ja tagarakendi puhverserveri arhitektuuri.
HTTP veakoodid
TTS API tagastab standardsed HTTP veakoodid. Siin on juhised, kuidas igale neist reageerida.
400: Bad Request (Vigane päring)
Server ei suutnud sinu päringut töödelda. Levinud põhjused:
- Tühi tekst või tekst, mis ületab 60 000 tähemärki
- Vigane koodek (nimi on valesti kirjutatud)
- Toetamata diskreetimissagedus (sample rate)
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Paranda parameetrid ja proovi uuesti
Ära proovi 404 viga automaatselt uuesti: probleem on sinu päringus, mitte serveris. Paranda esmalt parameetrid.
401: Unauthorized (Volitamata)
API võti on vigane, aegunud või puudub:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Kontrolli, et:
- Päises
Authorizationoleks olemas - Vorming oleks
Bearer xai-...(tühik pärast sõna Bearer) - Võtit poleks xAI konsoolis tühistatud
404: Not Found (Ei leitud)
Hääle ID on tundmatu: kontrolli seda käsuga GET /v1/tts/voices sisseehitatud hääle jaoks või GET /v1/custom-voices kohandatud hääle jaoks. Nagu 400 puhul, ei kao ka 404 viga uuesti proovimisel ära.
429: Too Many Requests (Liiga palju päringuid)
Oled ületanud kasutuspiirangu: sisetasemel on TTS jaoks 50 päringut sekundis ja 100 samaaegset seanssi vastavalt leheküljele Rate limits, ning 50 samaaegset WebSocketi seanssi meeskonna kohta vastavalt leheküljele Text to Speech. xAI soovitab proovida uuesti, kasutades eksponentsiaalset tagasipöördumist (exponential backoff):
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Proovi uuesti
Rakenda 429 vigade jaoks eksponentsiaalne tagasipöördumine:
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
# Kliendi viga (400, 401): ära proovi uuesti
response.raise_for_status()
raise Exception("Failed after 5 attempts")
500 / 503: Server Error (Serveri viga)
Serveril on ajutine probleem. Proovi uuesti, kasutades tagasipöördumist:
if response.status_code in (500, 503):
# Proovi uuesti eksponentsiaalse tagasipöördumisega
pass
503 vead on sageli põhjustatud ajutisest ülekoormusest. Need lahenevad tavaliselt mõne sekundiga.
Ära kunagi avalda API võtit kliendipoolses koodis
See on kõige olulisem turvareegel. Kui sinu API võti on brauseri JavaScriptis nähtav, saab igaüks:
- Kasutada sinu kvooti tasuta
- Tekitada sinu kontole kulutusi
- Pääseda ligi kõigile xAI API lõpp-punktidele sinu võtmega
Tagarakendi puhverserveri arhitektuur
Lahenduseks on suunata TTS päringud läbi oma tagarakendi:
Brauser -> Sinu tagarakend -> xAI API
(võti puudub) (API võti) (TTS)
Express.js näide
const express = require("express");
const app = express();
app.post("/api/tts", async (req, res) => {
const { text, voice_id, language } = req.body;
// Serveripoolne valideerimine
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"
});
}
// Edasta heli kliendile
res.set("Content-Type", response.headers.get("Content-Type"));
const buffer = await response.arrayBuffer();
res.send(Buffer.from(buffer));
});
FastAPI näide (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"]
)
WebSocketi puhverserver
TTS WebSocketi jaoks peab sinu tagarakend edastama sõnumeid kliendi ja xAI API vahel:
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}` } }
);
// Edasta klient -> xAI
clientWs.on("message", (msg) => xaiWs.send(msg));
// Edasta xAI -> klient
xaiWs.on("message", (msg) => clientWs.send(msg));
// Käitle sulgemist
clientWs.on("close", () => xaiWs.close());
xaiWs.on("close", () => clientWs.close());
});
Ebaõnnestumisel avatud moderatsioon (Fail-open moderation)
TTS API teostab sisu moderatsiooni asünkroonselt. See tähendab, et moderatsioon ei blokeeri päringut: heli genereeritakse ja tagastatakse isegi siis, kui moderatsioon pole oma analüüsi veel lõpetanud.
Kui sisu märgitakse sobimatuks, jõuab aruanne kohale tagantjärele. Seetõttu peaks sinu rakendus vajadusel teostama oma moderatsiooni enne päringu saatmist.
Peamised punktid
- 400 = parameetri viga (ära proovi uuesti; paranda päring)
- 401 = vigane API võti (kontrolli päist Authorization)
- 429 = kasutuspiirang ületatud (eksponentsiaalne tagasipöördumine)
- 500/503 = ajutine serveri viga (proovi uuesti tagasipöördumisega)
- Ära kunagi avalda API võtit kliendikoodis
- Suuna kõik TTS päringud läbi oma tagarakendi
- Moderatsioon on „fail-open“: lisa vajadusel oma filtreerimine