HTTP klaidos ir API rakto saugumas
Šiame puslapyje
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
Authorizationantraš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ą