Conceptos básicos de integración

#URL base

Todos los endpoints están bajo /v1 en el dominio propio de este despliegue. No hay selección de región — el enrutamiento a los proveedores upstream ocurre detrás del gateway.

#Encabezado de autenticación

Un único encabezado Authorization: Bearer es toda la autenticación. Sin firma, sin timestamp y sin encabezado por usuario — nada de lo que otros gateways exigen además del bearer token existe aquí.

#Envoltorio de error

Los rechazos del lado del gateway usan el envoltorio con formato OpenAI y type "xiaoxiang_error". Los errores upstream se reenvían sin cambios, los endpoints de tareas asíncronas responden con un cuerpo plano y dos casos no llevan cuerpo — lee la página de errores antes de escribir tu 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"
  }
}

Los cinco envoltorios y la tabla de códigos de error →

#Política de reintentos

Reintenta los 429 y 5xx con backoff exponencial, respetando Retry-After cuando esté presente. No reintentes los errores de validación 4xx — el mismo cuerpo volverá a fallar. En los envíos facturables, envía una Idempotency-Key para que un reintento tras un timeout reproduzca el primer resultado en lugar de iniciar un segundo trabajo.

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()

Cómo funcionan las claves de idempotencia →

#Especificación legible por máquina

El mismo contrato en dos formatos generados: OpenAPI para generar clientes, Postman y herramientas de API, y un único archivo markdown para pegar en un agente de código. Ambos se reconstruyen a partir de estas páginas, así que no pueden desviarse de lo que estás leyendo.

# 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

#Resumen de endpoints

Todas las rutas aceptan el cuerpo de solicitud de OpenAI — los parámetros específicos del proveedor (anthropic tool_use, gemini thinking_config) se reenvían sin cambios. Las rutas nativas del proveedor y las heredadas congeladas se listan por separado en la página de compatibilidad.