Chyby HTTP a zabezpečení API klíče
Na této stránce
Aktualizováno 3. listopadu 2026 na základě stránek xAI Text to Speech a Rate limits: text omezen na 60 000 znaků, chyba 404 (neznámý hlas) a limity rychlosti podle úrovně. Zdroje: Text to Speech · Rate limits.
Zpracování chyb a ochrana pověření
V produkčním prostředí musí tvoje aplikace elegantně zpracovávat chyby TTS API a především nikdy nezveřejňovat tvůj API klíč na straně klienta. Tato lekce pokrývá chybové kódy, strategie opakování a architekturu backendového proxy.
Chybové kódy HTTP
TTS API vrací standardní chybové kódy HTTP. Zde je návod, jak na každý z nich reagovat.
400: Bad Request (Špatný požadavek)
Server nedokázal zpracovat tvůj požadavek. Časté příčiny:
- Prázdný text nebo text delší než 60 000 znaků
- Neplatný kodek (překlep v názvu)
- Nepodporovaná vzorkovací frekvence
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Fix the parameters and try again
Chybu 400 neopakuj automaticky: problém je v tvém požadavku, ne na serveru. Nejprve oprav parametry.
401: Unauthorized (Neoprávněno)
API klíč je neplatný, vypršel nebo chybí:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Zkontroluj, zda:
- Je přítomna hlavička
Authorization - Formát je
Bearer xai-...(s mezerou za slovem Bearer) - Klíč nebyl zrušen v konzoli xAI
404: Not Found (Nenalezeno)
ID hlasu je neznámé: ověř ho pomocí GET /v1/tts/voices pro vestavěný hlas nebo GET /v1/custom-voices pro vlastní hlas. Stejně jako u chyby 400, ani chyba 404 nezmizí, pokud požadavek zopakuješ.
429: Too Many Requests (Příliš mnoho požadavků)
Překročil jsi limit rychlosti: u vstupní úrovně je to 50 požadavků za sekundu a 100 souběžných relací pro TTS podle stránky Rate limits a 50 souběžných WebSocket relací na tým podle stránky Text to Speech. xAI doporučuje opakovat s exponenciálním zpětným čekáním (exponential backoff):
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Try again
Pro chyby 429 implementuj exponenciální zpětné čekání:
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 (Chyba serveru)
Server má dočasný problém. Opakuj s exponenciálním zpětným čekáním:
if response.status_code in (500, 503):
# Retry with exponential backoff
pass
Chyby 503 jsou často způsobeny dočasným přetížením. Obvykle se vyřeší během několika sekund.
Nikdy nezveřejňuj API klíč na straně klienta
Toto je nejdůležitější bezpečnostní pravidlo. Pokud je tvůj API klíč viditelný v JavaScriptu prohlížeče, kdokoli může:
- Využívat tvou kvótu zdarma
- Navýšit poplatky na tvém účtu
- Přistupovat ke každému koncovému bodu API xAI s tvým klíčem
Architektura backendového proxy
Řešením je směrovat volání TTS přes tvůj vlastní backend:
Browser -> Your backend -> xAI API
(no key) (API key) (TTS)
Příklad v 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));
});
Příklad ve FastAPI (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"]
)
Proxy pro WebSocket
U TTS WebSocket musí tvůj backend přeposílat zprávy mezi klientem a API xAI:
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());
});
Moderace typu fail-open
API TTS spouští moderaci obsahu asynchronně. To znamená, že moderace neblokuje požadavek: audio je vygenerováno a vráceno, i když moderace ještě nedokončila svou analýzu.
Pokud je obsah označen jako nevhodný, zpráva přijde dodatečně. Tvá aplikace by proto měla v případě potřeby spustit vlastní moderaci předem (upstream).
Klíčové poznatky
- 400 = chyba parametru (neopakovat; opravit požadavek)
- 401 = neplatný API klíč (zkontroluj hlavičku Authorization)
- 429 = překročen limit rychlosti (exponenciální zpětné čekání)
- 500/503 = dočasná chyba serveru (opakovat s exponenciálním zpětným čekáním)
- Nikdy nezveřejňuj API klíč v kódu klienta
- Směruj všechna volání TTS přes svůj backend
- Moderace je typu fail-open: v případě potřeby přidej vlastní filtrování