Настройка собственной интеграции¶

Соблюдайте общий порядок на странице подключения клиентов. Для Anthropic Messages передавайте anthropic-version: 2023-06-01 и max_tokens больше нуля. Без этого заголовка Nexus отклоняет вызов.

Граница совместимости¶

Собственная интеграция совместима с Nexus, если она умеет задать:

https://api.nexus-hub.tech/v1 для OpenAI Chat или Responses;
https://api.nexus-hub.tech для Anthropic Messages;
https://api.nexus-hub.tech/v1beta для Gemini-compatible;
Bearer или другой поддерживаемый API-key header;
модель из GET /v1/models;
JSON и, если нужно, SSE streaming.

OpenAI Python SDK¶

Официальный SDK позволяет задать base_url и api_key:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEXUS_API_KEY"],
    base_url="https://api.nexus-hub.tech/v1",
)
response = client.responses.create(
    model=os.environ["NEXUS_MODEL"],
    input="Reply exactly OK.",
    max_output_tokens=16,
)
print(response.output_text)

Передайте NEXUS_MODEL значением из GET /v1/models. Для Chat Completions используйте client.chat.completions.create и соответствующий лимит вывода.

Anthropic Python SDK¶

Для Messages задайте base_url без /v1. SDK отправляет anthropic-version: 2023-06-01. max_tokens должен быть больше нуля:

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["NEXUS_API_KEY"],
    base_url="https://api.nexus-hub.tech",
)
message = client.messages.create(
    model=os.environ["NEXUS_MODEL"],
    max_tokens=16,
    messages=[{"role": "user", "content": "Reply exactly OK."}],
)
print(message.content)

Retries, timeouts и streaming¶

Задайте timeout явно и обрабатывайте сетевые сбои по правилам идемпотентности:

Для безопасных повторов при сбоях сети или таймаутах передавайте заголовок Idempotency-Key (в официальных Python SDK используйте параметр extra_headers={"Idempotency-Key": key}). При повторе с тем же ключом и телом Nexus возвращает сохранённый ответ с заголовком Idempotency-Replayed: true без повторного списания с баланса.
Не отправляйте один и тот же x-request-id для разных логических запросов: он служит для сквозной трассировки уникальной сетевой попытки.
При получении ошибок 429 или 503 ориентируйтесь на заголовок Retry-After.
Для streaming обрабатывайте SSE до terminal event и закрывайте соединение при ошибке; не записывайте body в логи.
Полная матрица повторов и детали жизненного цикла описаны в руководстве Повторы и идемпотентность.

Ключи и эксплуатация¶

Храните key в переменной окружения или менеджере секретов.
Не коммитьте его и не включайте в исключения, traces, screenshots или prompt.
После компрометации отзовите key и создайте новый.
В поддержку отправляйте только метод, маршрут, код ошибки, версию SDK и x-request-id.

Официальные SDK: openai-python и anthropic-sdk-python. Поля маршрутов описаны в справочнике API Nexus.