HTTP kļūdas un API atslēgu drošība
Šajā lapā
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
Authorizationgalvene - 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