HTTP-virheet ja API-avaimen suojaus
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech - ja Rate limits -sivujen perusteella: teksti rajoitettu 60 000 merkkiin, 404-virhe (tuntematon ääni) ja käyttörajat tason mukaan. Lähteet: Text to Speech · Rate limits.
Virheiden käsittely ja tunnistetietojen suojaaminen
Tuotantoympäristössä sovelluksesi tulee käsitellä TTS-API:n virheet hallitusti, eikä ennen kaikkea saa koskaan paljastaa API-avainta asiakaspuolella. Tämä oppitunti käsittelee virhekoodeja, uudelleenyrittämisstrategioita ja backend-välityspalvelinarkkitehtuuria.
HTTP-virhekoodit
TTS-API palauttaa standardit HTTP-virhekoodit. Tässä ohjeet siihen, miten kuhunkin koodiin tulee reagoida.
400: Bad Request (Virheellinen pyyntö)
Palvelin ei pystynyt käsittelemään pyyntöäsi. Yleisimmät syyt:
- Tyhjä teksti tai teksti, joka ylittää 60 000 merkkiä
- Virheellinen koodekki (nimessä oleva kirjoitusvirhe)
- Ei-tuettu näytteenottotaajuus
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Fix the parameters and try again
Älä yritä automaattisesti uudelleen 400-virheen jälkeen: ongelma on pyynnössäsi, ei palvelimella. Korjaa parametrit ensin.
401: Unauthorized (Valtuuttamaton)
API-avain on virheellinen, vanhentunut tai puuttuu:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Tarkista, että:
Authorization-otsake on läsnä- Muoto on
Bearer xai-...(välilyönti sanan Bearer jälkeen) - Avainta ei ole mitätöity xAI-konsolissa
404: Not Found (Ei löytynyt)
Äänen ID on tuntematon: tarkista se komennolla GET /v1/tts/voices sisäänrakennetun äänen osalta tai GET /v1/custom-voices mukautetun äänen osalta. Kuten 400-virheen kohdalla, 404-virhe ei poistu uudelleenyrittämisellä.
429: Too Many Requests (Liian monta pyyntöä)
Olet ylittänyt käyttörajan: aloitustasolla raja on 50 pyyntöä sekunnissa ja 100 samanaikaista istuntoa TTS:lle Rate limits -sivun mukaan, sekä 50 samanaikaista WebSocket-istuntoa tiimiä kohden Text to Speech -sivun mukaan. xAI suosittelee uudelleenyrittämistä eksponentiaalisella viiveellä (exponential backoff):
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Try again
Toteuta eksponentiaalinen viive 429-virheille:
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 (Palvelinvirhe)
Palvelimella on väliaikainen ongelma. Yritä uudelleen eksponentiaalisella viiveellä:
if response.status_code in (500, 503):
# Retry with exponential backoff
pass
503-virheet johtuvat usein väliaikaisesta ylikuormituksesta. Ne yleensä korjaantuvat muutamassa sekunnissa.
Älä koskaan paljasta API-avainta asiakaspuolella
Tämä on tärkein turvallisuussääntö. Jos API-avaimesi on näkyvissä selaimen JavaScript-koodissa, kuka tahansa voi:
- Käyttää kiintiösi ilmaiseksi
- Aiheuttaa kuluja tilillesi
- Päästä käsiksi kaikkiin xAI-API-päätepisteisiin avaimellasi
Backend-välityspalvelinarkkitehtuuri
Ratkaisu on välittää TTS-pyynnöt oman backendisi kautta:
Browser -> Your backend -> xAI API
(no key) (API key) (TTS)
Express.js-esimerkki
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-esimerkki (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-välitys
TTS-WebSocketiä varten backendisi täytyy välittää viestejä asiakkaan ja xAI-API:n välillä:
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-moderointi
TTS-API suorittaa sisältömoderoinnin asynkronisesti. Tämä tarkoittaa, että moderointi ei estä pyyntöä: ääni generoidaan ja palautetaan, vaikka moderointi ei olisi vielä saanut analyysiään valmiiksi.
Jos sisältö merkitään sopimattomaksi, raportti saapuu jälkikäteen. Sovelluksesi tulisi siis tarvittaessa suorittaa oma moderointinsa ennakolta.
Keskeiset asiat
- 400 = parametrivirhe (älä yritä uudelleen; korjaa pyyntö)
- 401 = virheellinen API-avain (tarkista Authorization-otsake)
- 429 = käyttöraja ylitetty (eksponentiaalinen viive)
- 500/503 = väliaikainen palvelinvirhe (yritä uudelleen viiveellä)
- Älä koskaan paljasta API-avainta asiakaskoodissa
- Välitä kaikki TTS-pyynnöt backendisi kautta
- Moderointi on fail-open: lisää oma suodatuksesi tarvittaessa