Earráidí HTTP agus slándáil eochracha API
Ar an leathanach seo
Nuashonraithe an 3 Samhain, 2026, bunaithe ar leathanaigh Text to Speech agus Rate limits de chuid xAI: téacs teoranta do 60,000 carachtar, an earráid 404 (guth anaithnid), agus teorainneacha ráta de réir céime. Foincí: Text to Speech · Rate limits.
Earráidí a láimhseáil agus do chreidiúintí a chosaint
Sa táirgeadh, ní mór d’fheidhmchlár earráidí TTS API a láimhseáil go réidh agus, os cionn gach rud, do eochair API a nochtadh ar an gcliant faoi sem aon uair. Clúdaíonn an ceacht seo cóid earráide, straitéisí athiarrtha, agus ailtireacht seachfhreastalaí (backend proxy).
Cóid earráide HTTP
Tugann an TTS API cóid earráide HTTP caighdeánacha ar ais. Seo conas freagairt do gach ceann acu.
400: Bad Request
Níorbh fhéidir leis an bhfreastalaí d’iarratas a phróiseáil. Cúiseanna coitianta:
- Téacs folamh nó téacs thar 60,000 carachtar
- Cóidec neamhbhailí (botún cló sa ainm)
- Ráta samplála nach dtacaítear leis
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Fix the parameters and try again
Ná déan iarracht arís go huathoibríoch ar earráid 400: is i d’iarratas atá an fhadhb, ní ar an bhfreastalaí. Deisigh na paraiméadair ar dtús.
401: Unauthorized
Tá an eochair API neamhbhailí, imithe in éag, nó ar iarraidh:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Seiceáil go bhfuil:
- An ceanntásc
Authorizationi láthair - An formáid
Bearer xai-...(le spás tar éis Bearer) - Nár cúlghaireadh an eochair sa chonsól xAI
404: Not Found
Tá ID an ghutha anaithnid: seiceáil é le GET /v1/tts/voices do ghuth ionsuite, nó GET /v1/custom-voices do ghuth saincheaptha. Cosúil le 400, ní rachaidh 404 ar ceal má dhéanann tú iarracht arís.
429: Too Many Requests
Tá tú tar éis teorainn ráta a shárú: ar an gcéad iontrála, 50 iarratas in aghaidh an tsoicind agus 100 seisiún comhthreomhar do TTS de réir an leathanaigh Rate limits, agus 50 seisiún WebSocket comhthreomhar in aghaidh an fhoirne de réir an leathanaigh Text to Speech. Molann xAI iarracht arís le cúlú easpónantúil (exponential backoff):
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Try again
Cuir cúlú easpónantúil i bhfeidhm d’earráidí 429:
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
Tá fadhb shealadach ag an bhfreastalaí. Déan iarracht arís le cúlú:
if response.status_code in (500, 503):
# Retry with exponential backoff
pass
Is minic a bhíonn earráidí 503 mar gheall ar ualach sealadach. De ghnáth, réitíonn siad laistigh de chúpla soicind.
Ná nocht an eochair API ar an gcliant riamh
Seo an riail slándála is tábhachtaí. Má tá d’eochair API le feiceáil i JavaScript an bhrabhsálaí, is féidir le duine ar bith:
- Do chuóta a úsáid saor in aisce
- Muirir a charnadh ar do chuntas
- Gach críochphointe API xAI a rochtain le d’eochair
Ailtireacht seachfhreastalaí (Backend proxy)
Is é an réiteach ná glaonna TTS a sheachfhreastalú trí do bhonnseirbhís féin:
Browser -> Your backend -> xAI API
(no key) (API key) (TTS)
Sampla 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));
});
Sampla 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"]
)
Seachfhreastalaí WebSocket
Do WebSocket TTS, caithfidh do bhonnseirbhís teachtaireachtaí a athsheoladh idir an cliant agus 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());
});
Moderation fail-open
Ritheann an TTS API modhnú ábhair go hasionchrónach. Ciallaíonn sé sin nach gcuireann an modhnú bac ar an iarratas: gintear an fuaime agus filltear í fiú mura bhfuil anailís an mhodhnaithe críochnaithe.
Má chuirtear ábhar faoi bhratach mar ábhar míchuí, tagann an tuarascáil tar éis na himeachta. Mar sin, ba chóir d’fheidhmchlár a mhodhnú féin a rith suas srutha más gá.
Príomhphointí
- 400 = earráid paraiméadair (ná déan iarracht arís; deisigh an t-iarratas)
- 401 = eochair API neamhbhailí (seiceáil an ceanntásc Authorization)
- 429 = teorainn ráta sáraithe (cúlú easpónantúil)
- 500/503 = earráid freastalaí shealadach (déan iarracht arís le cúlú)
- Ná nocht an eochair API i gcód clianta riamh
- Seachfhreastalaigh gach glao TTS trí do bhonnseirbhís
- Is modhnú fail-open é: cuir do scagadh féin leis más gá