Kimi API совместим с интерфейсом OpenAI, и при миграции обычно меняются три вещи: Base URL, API-ключ и имя модели. Но в интерфейсе 2026 года есть несколько ловушек: старые модели сняты с поддержки, max_tokens устарел, K3 по умолчанию использует максимальную силу рассуждения, а usage потокового запроса приходит только в последнем блоке.

Пройдём подключение с нуля: сначала сайт и протокол, затем выбор модели, первые вызовы curl и Python, в конце — чек-лист миграции и таблица ошибок. Модели и цены — на странице тарифов.

Примечание: Moonshot и Kimi — товарные знаки их правообладателей; статья носит технический характер. Список моделей, длина контекста и правила параметров могут меняться; ориентируйтесь на текущую официальную документацию.

1. Три вещи перед подключением

  1. Сайт: китайский — platform.kimi.com, международный — platform.kimi.ai. Аккаунты, баланс и ключи двух сайтов полностью независимы.
  2. Протокол: большинство проектов используют OpenAI-совместимый Chat Completions; проекты с Anthropic SDK могут использовать совместимый вход Messages.
  3. Модель: сначала проверьте, какие модели видны аккаунту, и только потом вписывайте их в код. Не копируйте руководства нескольких месяцев давности.

Домен запросов китайского сайта — https://api.moonshot.cn, международного — https://api.moonshot.ai. Домен и ключ должны соответствовать друг другу; это одна из самых частых причин 401.

2. Base URL и пути интерфейса

Протокол Base URL Путь интерфейса
OpenAI Chat Completions https://api.moonshot.cn/v1 /chat/completions
OpenAI Responses https://api.moonshot.cn/v1 /responses
Anthropic Messages https://api.moonshot.cn/anthropic /v1/messages
Список моделей https://api.moonshot.cn/v1 /models
Проверка баланса https://api.moonshot.cn/v1 /users/me/balance

Для международного сайта замените домен на api.moonshot.ai, пути не меняются. В OpenAI SDK base_url указывается до /v1 — SDK сам добавит /chat/completions; в curl нужно писать полный путь. При смешении появляется лишний или пропущенный /v1, что даёт 404.

Base URL совместимого входа Anthropic не содержит /v1 — это отличие от входа OpenAI. При подключении через Claude Code или другой Anthropic SDK указывайте https://api.moonshot.cn/anthropic, как в официальном примере.

3. Как выбрать имя модели

Имя модели Контекст Для каких задач Примечание
kimi-k3 1M Сложные рассуждения, разработка ПО, работа со знаниями, очень длинные документы По умолчанию reasoning_effort = max
kimi-k2.7-code 256K Генерация кода, вопросы по репозиторию, агенты Лучше следует инструкциям на длинном контексте
kimi-k2.7-code-highspeed 256K Автодополнение с низкой задержкой, интерактивное кодирование Та же модель, но быстрее
kimi-k2.6 256K Универсальные диалоги, извлечение, изображения и текст Поддерживает режимы с размышлением и без

Старые модели сняты с поддержки: все moonshot-v1 и kimi-k2.5 — с 31 августа 2026 года, серия kimi-k2 — с 25 мая 2026 года, kimi-latest — ещё раньше. Проектам с этими именами при обновлении стоит сразу переходить на kimi-k3 или серию K2, а не искать старую документацию.

Для универсальных задач не обязательно по умолчанию брать K3. Он силён, но высокая сила рассуждения по умолчанию увеличивает задержку и число выходных токенов; для простой классификации и извлечения в фиксированном формате часто лучше kimi-k2.6. Для кода рассматривайте серию K2.7 Code.

4. Первый вызов: curl

export MOONSHOT_API_KEY="ваш-ключ"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Ответь только: подключение успешно"}
    ],
    "max_completion_tokens": 64
  }'

Если вернулся 200 и содержимое ожидаемое, значит ключ, сайт, имя модели и путь верны. При 401 сначала проверьте соответствие сайта и ключа; при 404 — имя модели и /v1; при 400 — упоминаются ли в сообщении контекст или лимит вывода.

5. Python SDK и потоковый вывод

Установите OpenAI SDK версии 1.0 или выше и измените base_url и ключ:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "В трёх пунктах объясни, каким командам подходит API-шлюз"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\nUsage:", chunk.usage)

Потоковый ответ — это SSE: каждая строка начинается с data:, завершается data: [DONE]. При include_usage перед концом приходит дополнительный блок с пустым choices и только usage. Если соединение оборвалось, этот блок может не дойти, поэтому не полагайтесь на клиент как на единственный источник учёта расхода.

6. max_completion_tokens и сила рассуждения

max_tokens устарел; в новом коде используйте max_completion_tokens. Это желаемая длина вывода, а не сумма входа и выхода. Значение по умолчанию для K3 — 131072, максимум — 1048576; если вход плюс это значение превышает окно контекста, запрос вернёт invalid_request_error.

Два практичных правила:

  • Для тестов и задач с фиксированным форматом ставьте небольшое значение, например 256–1024, чтобы модель не писала длинно.
  • При достижении лимита finish_reason равен length, при нормальном завершении — stop. Увидев length, не повторяйте сразу: сначала решите, действительно ли нужен более длинный вывод или промпт слишком открытый.

У K3 есть параметр верхнего уровня reasoning_effort со значениями low, high, max; по умолчанию max. Для простых задач low снижает задержку и расход токенов; для сложных рассуждений повышайте. В OpenAI SDK, если версия не знает параметр, передавайте его через extra_body. Размышления K3 лежат в reasoning_content; в многошаговом диалоге и при вызове инструментов их нужно возвращать как есть.

7. Миграция с OpenAI или старого Moonshot

  1. Найдите в коде и конфигурации все старые имена моделей и составьте таблицу замены.
  2. Измените base_url: китайский сайт — https://api.moonshot.cn/v1, международный — https://api.moonshot.ai/v1.
  3. Возьмите ключ соответствующего сайта, не используйте его между сайтами.
  4. Замените имена моделей, приоритет — kimi-k3 или актуальные модели серии K2.
  5. Замените max_tokens на max_completion_tokens.
  6. Замените настройку thinking из K2.x на reasoning_effort K3 и не отправляйте обе одновременно.
  7. Добавьте в потоковые запросы stream_options={"include_usage": True}.
  8. Прогоните регрессию на том же наборе реальных задач, фиксируя качество, задержку, finish_reason и usage.
  9. Сохраните старую конфигурацию на один цикл выпуска и удалите после подтверждения.

Не переключайте всё сразу. Сначала тестовая среда, затем низкорисковые сценарии, в конце ключевые цепочки; на каждом шаге оставляйте переключатель отката.

8. Типичные ошибки

Код Тип ошибки Частая причина Что делать
400 invalid_request_error Неверный параметр, слишком длинный контекст, выход за лимит вывода Исправить запрос
400 content_filter Вход или выход нарушил правила безопасности Скорректировать промпт
401 invalid_authentication_error Неверный ключ, несовпадение сайта Сменить ключ или домен
404 resource_not_found_error Ошибка в имени модели или пути Сверить список моделей
429 rate_limit_reached_error Превышены параллелизм, RPM, TPM или TPD Снизить скорость или повысить уровень
429 exceeded_current_quota_error Задолженность или нехватка средств Пополнить баланс
504 Gateway Time-out Непотоковый длинный запрос ждал слишком долго Перейти на стриминг

Непотоковый запрос может вернуть 504, если сервер ждал более 900 секунд. Для длинной генерации, анализа документов и кодовых агентов используйте стриминг: клиент получает данные непрерывно, и меньше тратится на «дождаться тайм-аута и повторить».

Частые вопросы

До какого уровня указывать Base URL?

В OpenAI SDK — https://api.moonshot.cn/v1, без /chat/completions. В curl нужен полный https://api.moonshot.cn/v1/chat/completions. В Anthropic SDK — https://api.moonshot.cn/anthropic.

Почему max_tokens не действует?

Параметр устарел; часть моделей его игнорирует или возвращает ошибку. Используйте max_completion_tokens и помните, что это лимит вывода, а не сумма входа.

Почему K3 отвечает медленнее ожидаемого?

По умолчанию reasoning_effort = max, поэтому модель рассуждает глубже. Для простых задач поставьте low или high и ограничьте длину вывода — обычно задержка заметно снижается.

Почему после стриминга нет usage?

Нужно явно задать stream_options={"include_usage": True}. Даже с этой настройкой при обрыве соединения последний блок может не прийти, поэтому в production ведите учёт на сервере отдельно.

Что ещё менять при миграции с OpenAI?

В большинстве кода — только Base URL, ключ и имя модели. Дополнительно проверьте max_tokens, usage в стриминге, сопоставление типов ошибок и стратегию повторов, особенно классификацию ошибок 429.

Что дальше

Создайте тестовый ключ в ZSQH AI Gateway, прогоните по одной реальной задаче на kimi-k3 и kimi-k2.6, убедитесь в работе цепочки и подключайте production. Доступные модели и биллинг — на странице тарифов.

Читайте также: