Nozioni di integrazione

#URL di base

Tutti gli endpoint si trovano sotto /v1 sul dominio di questa installazione. Non c'è selezione della regione — il routing verso i fornitori upstream avviene dietro il gateway.

#Header di autenticazione

Un solo header Authorization: Bearer è tutta l'autenticazione. Nessuna firma, nessun timestamp e nessun header per utente — tutto ciò che altri gateway richiedono oltre al bearer token qui non esiste.

#Struttura dell'errore

I rifiuti lato gateway usano la struttura in formato OpenAI con type "xiaoxiang_error". Gli errori upstream vengono inoltrati invariati, gli endpoint dei task asincroni rispondono con un corpo piatto e due casi non hanno alcun corpo — leggi la pagina degli errori prima di scrivere il tuo parser.

HTTP/1.1 402 Payment Required
X-Oneapi-Request-Id: 2026091023...

{
  "error": {
    "message": "insufficient account balance, please top up to continue (request id: 2026091023...)",
    "type": "xiaoxiang_error",
    "code": "insufficient_user_quota"
  }
}

Tutte e cinque le strutture e la tabella dei codici di errore →

#Politica di retry

Riprova i 429 e i 5xx con backoff esponenziale, rispettando Retry-After quando presente. Non riprovare gli errori di validazione 4xx — lo stesso corpo fallirà di nuovo. Per gli invii fatturabili, invia una Idempotency-Key, così un nuovo tentativo dopo un timeout riproduce il primo risultato invece di avviare un secondo job.

import time, requests

def call_with_backoff(url, headers, body, tries=5):
    for i in range(tries):
        r = requests.post(url, headers=headers, json=body)
        if r.status_code not in (429, 500, 502, 503, 504):
            return r
        # 429 and 413 have no JSON body — never parse before checking status.
        wait = int(r.headers.get("Retry-After", 2 ** i))
        time.sleep(wait)
    r.raise_for_status()

Come funzionano le chiavi di idempotenza →

#Specifica leggibile dalle macchine

Lo stesso contratto in due formati generati: OpenAPI per la generazione di client, Postman e strumenti API, e un unico file markdown da incollare in un agente di coding. Entrambi sono ricostruiti da queste pagine, quindi non possono discostarsi da ciò che stai leggendo.

# Any OpenAPI generator works; this is the common one.
npx @openapitools/openapi-generator-cli generate \
  -i https://www.aisplice.store/openapi.json \
  -g python \
  -o ./gateway-client

#Panoramica degli endpoint

Ogni percorso accetta il corpo di richiesta OpenAI — i parametri specifici del fornitore (anthropic tool_use, gemini thinking_config) vengono inoltrati invariati. Le route native dei fornitori e quelle legacy congelate sono elencate a parte nella pagina sulla compatibilità.