Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Żbalji HTTP u sigurtà tal-API key

Lezzjoni 13 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Immaniġġja l-iżbalji u pproteġi l-kredenzjali tiegħek
  2. Kodiċijiet ta’ żball HTTP
  3. Qatt tesponi l-API key fuq il-klijent
  4. Moderazzjoni “Fail-open”
  5. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru 2026, ibbażat fuq il-paġni Text to Speech u Rate limits ta’ xAI: it-test limitat għal 60,000 karattru, l-iżball 404 (vuċi mhux magħrufa), u l-limiti tar-rata skont il-livell. Sorsi: Text to Speech · Rate limits.

Immaniġġja l-iżbalji u pproteġi l-kredenzjali tiegħek

Fil-produzzjoni, l-app tiegħek trid timmaniġġja l-iżbalji tal-API TTS b’mod korrett u, l-aktar importanti, qatt ma tesponi l-API key tiegħek fuq il-klijent. Din il-lezzjoni tkopri kodiċijiet ta’ żball, strateġiji ta’ retry, u l-arkitettura tal-proxy tal-backend.

Kodiċijiet ta’ żball HTTP

L-API TTS tirritorna kodiċijiet ta’ żball HTTP standard. Hawnhekk hawn kif għandek tirreaġixxi għal kull wieħed.

400: Talba Ħażina (Bad Request)

Is-server ma setax jipproċessa t-talba tiegħek. Kawżi komuni:

  • Test vojt jew test ta’ aktar minn 60,000 karattru
  • Codec invalidu (typo fl-isem)
  • Rata ta’ kampjunar (sample rate) mhux appoġġjata
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Tippruvax terġa’ tagħmel awtomatikament (retry) żball 400: il-problema hija fit-talba tiegħek, mhux fis-server. Issolvi l-parametri l-ewwel.

401: Mhux Awtorizzat (Unauthorized)

L-API key hija invalida, skadiet, jew nieqsa:

if response.status_code == 401:
    raise AuthenticationError("Invalid or expired API key")

Iċċekkja li:

  • L-header Authorization huwa preżenti
  • Il-format huwa Bearer xai-... (b’spazju wara Bearer)
  • Iċ-ċavetta ma ġietx revokata fil-console ta’ xAI

404: Ma Nstabx (Not Found)

L-ID tal-vuċi mhux magħruf: iċċekkjah ma’ GET /v1/tts/voices għal vuċi integrata, jew GET /v1/custom-voices għal vuċi personalizzata. Bħal 400, 404 ma jisparixx jekk tipprova terġa’ tagħmel it-talba.

429: Wisq Talbiet (Too Many Requests)

Qbiżt limitu ta’ rata: fil-livell tad-dħul, 50 talba kull sekonda u 100 sessjoni konkorrenti għal TTS skont il-paġna Rate limits, u 50 sessjoni WebSocket konkorrenti kull tim skont il-paġna Text to Speech. xAI jirrakkomanda li tipprova terġa’ tagħmel it-talba b‘“exponential backoff”:

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    await asyncio.sleep(retry_after)
    # Try again

Implimenta exponential backoff għal żbalji 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: Żball tas-Server

Is-server għandu problema temporanja. Erġa’ pprova b’backoff:

if response.status_code in (500, 503):
    # Retry with exponential backoff
    pass

L-iżbalji 503 spiss ikunu kkawżati minn tagħbija żejda temporanja. Ġeneralment jisolvu fi ftit sekondi.

Qatt tesponi l-API key fuq il-klijent

Din hija l-aktar regola importanti tas-sigurtà. Jekk l-API key tiegħek tkun viżibbli fil-JavaScript tal-browser, kulħadd jista’:

  • Juża l-kwota tiegħek b’xejn
  • Iġib spejjeż fuq il-kont tiegħek
  • Jaċċessa kull endpoint tal-API ta’ xAI bil-key tiegħek

Arkitettura tal-proxy tal-backend

Is-soluzzjoni hija li tgħaddi s-sejħiet TTS permezz tal-backend tiegħek stess:

Browser -> Your backend -> xAI API
 (no key)    (API key)      (TTS)

Eżempju 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));
});

Eżempju 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 WebSocket

Għal TTS WebSocket, il-backend tiegħek irid jgħaddi l-messaġġi bejn il-klijent u l-API ta’ 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());
});

Moderazzjoni “Fail-open”

L-API TTS tmexxi l-moderazzjoni tal-kontenut b’mod asinkronu. Dan ifisser li l-moderazzjoni ma timblokkax it-talba: l-awdjo jiġi ġġenerat u rritornat anke jekk il-moderazzjoni ma tkunx lesta l-analiżi tagħha.

Jekk il-kontenut jiġi mmarkat bħala mhux xieraq, ir-rapport jiġi wara l-fatt. Għalhekk, l-app tiegħek għandda tmexxi l-moderazzjoni tagħha stess minn qabel jekk ikun meħtieġ.

Punti Ewlenin

  • 400 = żball fil-parametru (terġax tipprova; issolvi t-talba)
  • 401 = API key invalida (iċċekkja l-header Authorization)
  • 429 = limitu tar-rata milħuq (exponential backoff)
  • 500/503 = żball temporanju tas-server (erġa’ pprova b’backoff)
  • Qatt tesponi l-API key fil-kodiċi tal-klijent
  • Għaddi s-sejħiet TTS kollha permezz tal-backend tiegħek
  • Il-moderazzjoni hija fail-open: żid il-filtrazzjoni tiegħek stess jekk ikun meħtieġ