Основы интеграции

#Базовый URL

Все эндпоинты находятся под /v1 на собственном домене этого развёртывания. Выбирать регион не нужно — маршрутизация к вышестоящим провайдерам происходит за шлюзом.

#Заголовок аутентификации

Для аутентификации достаточно одного заголовка Authorization: Bearer. Ни подписи, ни метки времени, ни пользовательских заголовков — всего, что сверх bearer-токена требуют другие шлюзы, здесь нет.

#Формат ошибки

Отказы на стороне шлюза используют формат OpenAI с type "xiaoxiang_error". Ошибки провайдеров передаются без изменений, эндпоинты асинхронных задач отвечают плоским телом, а в двух случаях тела нет вовсе — прочитайте страницу об ошибках, прежде чем писать парсер.

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"
  }
}

Все пять форматов ошибок и таблица кодов →

#Политика повторов

Повторяйте запросы при 429 и 5xx с экспоненциальной задержкой, учитывая Retry-After, если он есть. Не повторяйте при ошибках валидации 4xx — то же тело снова не пройдёт. Для платных запросов передавайте Idempotency-Key, чтобы повтор после тайм-аута вернул первый результат, а не запустил вторую задачу.

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

Как работают ключи идемпотентности →

#Машиночитаемая спецификация

Тот же контракт в двух генерируемых форматах: OpenAPI — для генерации клиентов, Postman и других API-инструментов, и один markdown-файл, который можно вставить в агента для программирования. Оба собираются из этих страниц, поэтому не расходятся с тем, что вы читаете.

# 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

#Обзор эндпоинтов

Каждый путь принимает тело запроса в формате OpenAI — специфичные для провайдеров параметры (anthropic tool_use, gemini thinking_config) передаются без изменений. Нативные маршруты провайдеров и замороженные устаревшие маршруты перечислены отдельно на странице совместимости.