HTTP-hibák és az API-kulcsok biztonsága
Ezen az oldalon
Frissítve: 2026. november 3., az xAI Text to Speech és Rate limits oldalai alapján: a szöveg 60 000 karakterre korlátozott, a 404-es hiba (ismeretlen hang), valamint a szintenkénti sebességkorlátok. Források: Text to Speech · Rate limits.
Hibakezelés és hitelesítő adataid védelme
Éles környezetben az alkalmazásodnak hibamentesen kell kezelnie a TTS API hibáit, és mindenekelőtt soha nem szabad kitenned az API-kulcsodat a kliens oldalon. Ez a lecke a hibakódokat, az újrapróbálkozási stratégiákat és a backend proxy architektúrát tárgyalja.
HTTP-hibakódok
A TTS API szabványos HTTP-hibakódokat ad vissza. Íme, hogyan reagálj az egyes esetekre.
400: Rossz kérés (Bad Request)
A szerver nem tudta feldolgozni a kérésedet. Gyakori okok:
- Üres szöveg vagy 60 000 karakternél hosszabb szöveg
- Érvénytelen kodek (elírás a névben)
- Nem támogatott mintavételezési frekvencia
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Fix the parameters and try again
Ne próbáld meg automatikusan újraindítani a 400-as hibát: a probléma a kérésedben van, nem a szerveren. Először javítsd a paramétereket.
401: Jogosulatlan (Unauthorized)
Az API-kulcs érvénytelen, lejárt vagy hiányzik:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Ellenőrizd a következőket:
- Az
Authorizationfejléc jelen van-e - A formátum
Bearer xai-...(szóközzel a Bearer után) - A kulcsot nem vonták-e vissza az xAI konzolban
404: Nem található (Not Found)
A hangazonosító ismeretlen: ellenőrizd a GET /v1/tts/voices végponttal a beépített hangok esetén, vagy a GET /v1/custom-voices végponttal az egyéni hangoknál. Akárcsak a 400-as hiba, a 404-es sem szűnik meg újrapróbálkozásra.
429: Túl sok kérés (Too Many Requests)
Túllépted a sebességkorlátot: a belépő szinten másodpercenként 50 kérés és 100 egyidejű munkamenet engedélyezett a TTS-hez a Rate limits oldal szerint, valamint csapatonként 50 egyidejű WebSocket-munkamenet a Text to Speech oldal alapján. Az xAI exponenciális visszalépéssel (exponential backoff) történő újrapróbálkozást javasol:
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Try again
Implementálj exponenciális visszalépést a 429-es hibákhoz:
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: Szerverhiba
A szervernek átmeneti problémája van. Próbáld újra visszalépéssel:
if response.status_code in (500, 503):
# Retry with exponential backoff
pass
Az 503-as hibákat gyakran ideiglenes túlterhelés okozza. Általában néhány másodpercen belül megoldódnak.
Soha ne tedd ki az API-kulcsot a kliens oldalon
Ez a legfontosabb biztonsági szabály. Ha az API-kulcsod látható a böngésző JavaScript kódjában, bárki képes lehet:
- Ingyenesen felhasználni a kvótádat
- Költségeket generálni a fiókod terhére
- Hozzáférni minden xAI API-végponthoz a kulcsoddal
Backend proxy architektúra
A megoldás az, hogy a TTS-hívásokat a saját backendeden keresztül proxyzod:
Browser -> Your backend -> xAI API
(no key) (API key) (TTS)
Express.js példa
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 példa (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
A TTS WebSocket esetén a backendednek továbbítania kell az üzeneteket a kliens és az xAI API között:
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áció
A TTS API a tartalommoderációt aszinkron módon végzi. Ez azt jelenti, hogy a moderáció nem blokkolja a kérést: a hanganyag generálódik és visszaadásra kerül akkor is, ha a moderáció még nem fejezte be az elemzést.
Ha a tartalmat nem megfelelőnek minősítik, a jelentés utólag érkezik. Ezért az alkalmazásodnak szükség esetén saját moderációt kell futtatnia upstream (a kérés előtt).
Főbb megállapítások
- 400 = paraméterhiba (ne próbáld újra; javítsd a kérést)
- 401 = érvénytelen API-kulcs (ellenőrizd az Authorization fejlécet)
- 429 = sebességkorlát (exponenciális visszalépés)
- 500/503 = átmeneti szerverhiba (próbáld újra visszalépéssel)
- Soha ne tedd ki az API-kulcsot a kliens kódban
- Minden TTS-hívást proxyzz a backendeden keresztül
- A moderáció „fail-open“: szükség esetén alkalmazz saját szűrést