API к моделям

API к моделям — продукт xWires для команд разработки. Компания подключает его по заявке, xWires выдаёт каждой команде или сервису свой ключ, а расход токенов по ключам админ компании видит в кабинете. API совместим с API OpenAI: готовый код и инструменты работают, если поменять адрес, ключ и модель.

Вызвать модель можно двумя способами:

Сейчас в руководстве Kimi K3 (раздел 4) и DeepSeek V4 Pro (раздел 5). GLM появится здесь своим разделом.

Это не API управления компанией. Тот нужен кадровой и учётной системам для подписок ChatGPT, у него свой адрес и свои ключи, и он описан в отдельном руководстве. Ключ API управления к моделям не подходит, и наоборот.

1. Админ компании открывает в кабинете xWires «Компания → API к моделям»: там адрес API и ID моделей. Раздел появляется, когда xWires выдал компании первый ключ. Если API ещё не подключено, оставьте заявку на странице «API к моделям».
2. Ключ команды выдаёт xWires. Положите адрес, ключ и ID модели в переменные окружения сервера:

export XWIRES_BASE_URL="адрес API из кабинета"
export XWIRES_API_KEY="ключ вашей команды"
export XWIRES_MODEL="ID модели из кабинета"

3. Отправьте первый запрос:

curl "$XWIRES_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $XWIRES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$XWIRES_MODEL"'",
    "messages": [
      {"role": "system", "content": "Ты — помощник разработчика. Отвечай кратко."},
      {"role": "user", "content": "Привет! Что ты умеешь?"}
    ]
  }'

{
  "id": "0217923680000000000000000000000000000000000000000000",
  "object": "chat.completion",
  "created": 1792368000,
  "model": "<ID модели>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Помогаю с разработкой: пишу, объясняю и отлаживаю код, отвечаю на технические вопросы.",
        "reasoning_content": "The user greets me and asks what I can do, in one short answer…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 131,
    "completion_tokens": 184,
    "total_tokens": 315,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 124
    }
  }
}

В агентах для программирования, LangChain и других инструментах выберите OpenAI-совместимого провайдера (OpenAI compatible) и укажите те же три значения: адрес API (base URL), ключ и ID модели. Код на Python и Node.js — в раздел 6.

Адрес API

Базовый адрес, к которому добавляется путь: /chat/completions или /responses. Все запросы — HTTPS POST с телом JSON и заголовком Content-Type: application/json. Адрес — в кабинете, «Компания → API к моделям»; в SDK OpenAI он передаётся как base_url (Python) или baseURL (Node.js).

Ключ

Ключ идёт в заголовке Authorization: Bearer каждого запроса. У каждой команды или сервиса свой ключ: по нему считается расход, и в кабинете он подписан названием команды. Ключи выдаёт xWires; целиком ключ есть только у команды, а в кабинете видны его начало и конец.

• Ключ живёт только на сервере: в переменной окружения или хранилище секретов. В код, репозиторий, браузер и мобильное приложение он не попадает: из них его легко достать, и тратить токены компании сможет кто угодно.
• Ключ потерян, попал в репозиторий или мог оказаться у посторонних — напишите на support@xwires.ai, и мы его заменим.
• Новой команде или сервису нужен свой ключ — напишите туда же.

ID модели

Модель выбирается полем model в каждом запросе. ID моделей — в кабинете, рядом с адресом API. В примерах этого руководства ID берётся из переменной XWIRES_MODEL: положите в неё ID нужной модели.

Рассуждение перед ответом

Модели сначала рассуждают, потом отвечают. Рассуждение приходит вместе с ответом: в Chat Completions — в message.reasoning_content, в Responses — отдельным элементом reasoning перед сообщением. Показывать его пользователю не обязательно, а язык у него бывает другим, чем у ответа. Токены рассуждения входят в токены ответа (completion_tokens, из них reasoning_tokens) и в предел max_tokens: если предел мал, модель потратит его на рассуждение и вернёт пустой ответ с finish_reason: length. Поэтому max_tokens не задавайте вовсе или оставляйте запас на сотни токенов.

Рассуждает Kimi K3 по-английски, даже когда вопрос и ответ на русском.

DeepSeek V4 Pro рассуждает на языке вопроса. На сложных задачах — коде, математике, анализе — рассуждение длинное, и ответ целиком может идти минуты: увеличьте таймаут или получайте ответ по частям (раздел 9).

POST на адрес API с путём /chat/completions — тот же запрос, что у OpenAI, поэтому подходят официальные SDK и готовый код. Пример на curl — в раздел 2.

Параметры

Python

Нужен официальный SDK OpenAI версии 1.0 или новее: pip install --upgrade "openai>=1.0".

import os

from openai import OpenAI

client = OpenAI(
    base_url=os.environ["XWIRES_BASE_URL"],
    api_key=os.environ["XWIRES_API_KEY"],
    timeout=120,
)
MODEL = os.environ["XWIRES_MODEL"]
messages = [
    {"role": "system", "content": "Ты — помощник разработчика. Отвечай кратко."},
    {"role": "user", "content": "Привет! Что ты умеешь?"},
]

# Ответ целиком
completion = client.chat.completions.create(model=MODEL, messages=messages)
print(completion.choices[0].message.content)
print(completion.usage)

# Ответ по частям, по мере того как модель его пишет
stream = client.chat.completions.create(model=MODEL, messages=messages, stream=True)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()

Node.js

Официальный SDK OpenAI: npm install openai.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.XWIRES_BASE_URL,
  apiKey: process.env.XWIRES_API_KEY,
  timeout: 120_000,
});
const model = process.env.XWIRES_MODEL;
const messages = [
  { role: "system", content: "Ты — помощник разработчика. Отвечай кратко." },
  { role: "user", content: "Привет! Что ты умеешь?" },
];

// Ответ целиком
const completion = await client.chat.completions.create({ model, messages });
console.log(completion.choices[0].message.content);
console.log(completion.usage);

// Ответ по частям, по мере того как модель его пишет
const stream = await client.chat.completions.create({ model, messages, stream: true });
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
process.stdout.write("\n");

Ответ

• choices[0].message.content — текст ответа, choices[0].message.reasoning_content — рассуждение модели перед ним.
• choices[0].finish_reason — почему модель остановилась: stop — ответ закончен, length — ответ с рассуждением дошёл до max_tokens.
• usage — токены запроса (prompt_tokens, из них взятые из кэша — prompt_tokens_details.cached_tokens), ответа (completion_tokens, из них рассуждение — completion_tokens_details.reasoning_tokens) и всего (total_tokens).
• В ответе по частям сначала идут куски с choices[0].delta.reasoning_content, потом с текстом ответа в choices[0].delta.content; примеры выше печатают только текст. С "stream_options": {"include_usage": true} в запросе последним придёт кусок без choices и с usage; кусок без choices пропускайте, как в примерах.

POST на адрес API с путём /responses — интерфейс со встроенными инструментами на стороне сервера. Главный из них — поиск в интернете, web_search: модель сама ищет и отвечает со свежими данными, без вашего поискового API и цикла вызова функций.

Параметры

Python

Тот же SDK OpenAI: в input можно передать сообщения со строкой в content. В output ответа приходят рассуждение (элемент reasoning) и сообщение с блоком output_text, а свойство SDK output_text собирает из них только текст ответа.

import os

from openai import OpenAI

client = OpenAI(
    base_url=os.environ["XWIRES_BASE_URL"],
    api_key=os.environ["XWIRES_API_KEY"],
    timeout=120,
)

response = client.responses.create(
    model=os.environ["XWIRES_MODEL"],
    input=[{"role": "user", "content": "Какие новости в мире ИИ за эту неделю?"}],
    tools=[{"type": "web_search", "max_keyword": 2}],
)
print(response.output_text)

curl, ответ по частям

В REST-запросе content — список блоков input_text. С stream: true ответ приходит событиями SSE.

curl "$XWIRES_BASE_URL/responses" \
  -H "Authorization: Bearer $XWIRES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$XWIRES_MODEL"'",
    "stream": true,
    "tools": [{"type": "web_search", "max_keyword": 3}],
    "input": [
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "Какие новости в мире ИИ за эту неделю?"}]
      }
    ]
  }'

Запросы с поиском видны в «Расходе токенов» в кабинете: среди запросов отдельно указано, сколько было с поиском в интернете.

Ошибка приходит с кодом HTTP и телом, как у OpenAI: {"error": {"code": "…", "message": "…", "type": "…"}}. SDK OpenAI превращают её в исключение с этим кодом. Если пишете нам, приложите message: в нём есть Request id.

• Таймаут. Для ответа целиком начните с 60–120 секунд и подстройте по своим запросам; DeepSeek V4 Pro на сложных задачах рассуждает дольше. Длинный ответ лучше получать по частям (stream): первые слова придут сразу, а соединение не простаивает.
• Повторы. 429, 500, 503 и обрыв соединения повторяйте с нарастающей паузой — 1, 2, 4, 8 секунд с небольшим случайным разбросом — и ограничьте число попыток. 400, 401, 403 и 404 повтором не исправить. SDK OpenAI повторяют такие ошибки сами, по умолчанию дважды (max_retries в Python, maxRetries в Node.js).
• Учёт. Пишите usage из ответа в свои логи вместе с командой или сервисом: так расход виден сразу, а не на следующий день. В ответе по частям usage придёт, если в запросе есть "stream_options": {"include_usage": true}.
• Кэш. Агенты раз за разом отправляют одно и то же начало запроса: системный промпт, код, историю. Держите это начало неизменным, а то, что меняется, ставьте в конец: повторяющееся начало модель берёт из кэша, и такие токены стоят дешевле нового ввода. Кэш включается сам, а сколько токенов запроса пришло из него, показывает usage.prompt_tokens_details.cached_tokens.

Админ компании видит расход в кабинете, «Компания → Расход токенов»: токены ввода, из кэша и ответа, запросы и ошибки по дням, моделям и ключам. Данные приходят раз в сутки, поэтому сегодняшние запросы появятся там завтра.

Лимиты на запросы и токены в минуту подбираем под объём компании. Если упираетесь в 429 или ждёте рост нагрузки, напишите на support@xwires.ai: сколько запросов в минуту и сколько одновременных запросов нужно в пике.

• Ключ — секрет компании: только на сервере, у каждой команды свой (раздел 3).
• Вопросы о подключении, ключах и лимитах — на support@xwires.ai.