Conceitos básicos de integração

#URL base

Todos os endpoints ficam sob /v1 no próprio domínio desta implantação. Não há seleção de região — o roteamento para os provedores upstream acontece por trás do gateway.

#Cabeçalho de autenticação

Um único cabeçalho Authorization: Bearer é toda a autenticação. Sem assinatura, sem timestamp e sem cabeçalho por usuário — nada além do bearer token que outros gateways exigem existe aqui.

#Envelope de erro

As rejeições do lado do gateway usam o envelope no formato da OpenAI com type "xiaoxiang_error". Erros do upstream são encaminhados sem alteração, os endpoints de tarefas assíncronas respondem com um corpo plano, e dois casos não trazem corpo nenhum — leia a página de erros antes de escrever seu 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"
  }
}

Os cinco envelopes e a tabela de códigos de erro →

#Política de novas tentativas

Repita 429 e 5xx com backoff exponencial, respeitando Retry-After quando presente. Não repita erros de validação 4xx — o mesmo corpo vai falhar de novo. Em envios cobrados, envie uma Idempotency-Key para que uma nova tentativa após um timeout reproduza o primeiro resultado em vez de iniciar um segundo trabalho.

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

Como funcionam as chaves de idempotência →

#Especificação legível por máquina

O mesmo contrato em dois formatos gerados: OpenAPI para geração de clientes, Postman e ferramentas de API, e um único arquivo markdown para colar em um agente de código. Os dois são gerados a partir destas páginas, então não ficam diferentes do que você está lendo.

# 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

#Visão geral dos endpoints

Todos os caminhos aceitam o corpo de requisição da OpenAI — parâmetros específicos do provedor (anthropic tool_use, gemini thinking_config) são repassados sem alteração. As rotas nativas de provedores e as rotas legadas congeladas estão listadas à parte na página de compatibilidade.