/v1/chat/completions, /v1/responses и /v1/messages: какой endpoint AI API использовать

/v1/chat/completions vs /v1/responses vs /v1/messages: Какой endpoint AI API выбрать?#

Распространённая проблема в AI API шлюзах — это не API ключ, не модель и не SDK. Это endpoint.

Пользователь выбирает существующую модель, но отправляет запрос на неправильный endpoint. В результате:

• модель недоступна;
• endpoint не поддерживается;
• неверное тело запроса;
• tool calling не работает;
• несовпадение формата streaming;
• Claude модель работает в одном инструменте, но падает в другом.

Это руководство объясняет различия между тремя семействами endpoint:

/v1/chat/completions
/v1/responses
/v1/messages

Краткая версия:

Если ваш клиент говорит "OpenAI-compatible", начните с:

https://crazyrouter.com/v1/chat/completions

или установите base URL на:

https://crazyrouter.com/v1

и позвольте SDK добавить /chat/completions.

Если ваш инструмент специально требует OpenAI Responses API, используйте /v1/responses.

Если ваш инструмент использует Anthropic-native SDK и ожидает Claude Messages API, используйте /v1/messages.

Самая распространённая ошибка#

Самая распространённая ошибка — смешивание семейства моделей и семейства endpoint.

Например, Claude модель может быть доступна через OpenAI-совместимый шлюз, но это не означает автоматически, что тело вашего запроса должно использовать Anthropic-native /v1/messages schema.

Аналогично, инструмент, который отправляет Anthropic-native запросы на /v1/messages, не может быть исправлен только изменением имени модели. Endpoint и тело запроса должны совпадать.

Думайте об этом так:

имя модели + endpoint + schema запроса должны совпадать

Если один из трёх неправильный, модель может выглядеть недоступной, даже если сама модель работает нормально.

Что такое /v1/chat/completions#

/v1/chat/completions — это классический OpenAI-совместимый chat endpoint.

Типичный запрос выглядит так:

curl https://crazyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain API endpoints in one paragraph."}
    ]
  }'

Используйте /v1/chat/completions когда:

• приложение говорит, что поддерживает OpenAI-совместимый API;
• конфиг запрашивает OPENAI_BASE_URL или base_url;
• тело запроса использует messages с role и content;
• вы используете режим совместимости обычного OpenAI SDK;
• вы настраиваете инструменты типа Cursor-style клиентов, LiteLLM-style роутеров, FastGPT-style приложений или многих chat UI.

Для большинства пользователей это самый безопасный endpoint по умолчанию.

Что такое /v1/responses#

/v1/responses — это новый OpenAI Responses API endpoint.

Он разработан вокруг более общего объекта response и может представлять:

• текстовый вывод;
• tool calls;
• multimodal ввод;
• reasoning items;
• structured output;
• agent-подобные workflows.

Упрощённый запрос выглядит так:

curl https://crazyrouter.com/v1/responses \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Explain the difference between chat completions and responses."
  }'

Используйте /v1/responses когда:

• инструмент явно говорит, что использует OpenAI Responses API;
• конфиг упоминает responses вместо chat.completions;
• тело запроса использует input вместо messages;
• маршрут модели/провайдера поддерживает поведение Responses API;
• вам нужны новые OpenAI-style форматы tool или reasoning вывода.

Не отправляйте Chat Completions тело на /v1/responses, если шлюз явно не документирует это преобразование.

Что такое /v1/messages#

/v1/messages — это Anthropic Messages API style endpoint.

Типичный Claude-native запрос выглядит так:

curl https://crazyrouter.com/v1/messages \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Explain Claude Messages API."}
    ]
  }'

Используйте /v1/messages когда:

• клиент использует Anthropic-native;
• SDK ожидает Claude Messages API формат;
• запрос имеет top-level system вместо system сообщения внутри массива;
• запрос требует Anthropic-specific content blocks или tool schema;
• документация явно говорит вызывать /v1/messages.

Не предполагайте, что каждая Claude модель должна вызываться с /v1/messages. Если вы используете OpenAI-совместимый шлюз или SDK, Claude модели могут быть вызваны через /v1/chat/completions.

Почему ошибки endpoint делают модели недоступными#

Когда модель падает, пользователи часто предполагают, что модель не работает. Но во многих случаях модель работает нормально, а формат запроса неправильный.

Примеры распространённых несовпадений:

Base URL vs полный endpoint#

Многие инструменты запрашивают Base URL, а не полный endpoint.

Правильный Base URL:

https://crazyrouter.com/v1

Затем SDK вызывает:

https://crazyrouter.com/v1/chat/completions

Неправильный Base URL для большинства SDKs:

https://crazyrouter.com/v1/chat/completions

Почему? Потому что SDK может добавить /chat/completions снова.

Правило:

• Если поле называется base_url, используйте /v1.
• Если поле называется endpoint и запрашивает полный URL, используйте полный путь, который требует инструмент.

Какой endpoint выбрать?#

Используйте это дерево решений:

1. Ваш инструмент говорит "OpenAI-compatible API"?
   Используйте /v1/chat/completions или Base URL https://crazyrouter.com/v1.

2. Ваш инструмент специально говорит "Responses API"?
   Используйте /v1/responses.

3. Ваш инструмент использует Anthropic SDK или Claude Messages API?
   Используйте /v1/messages.

4. Вы не уверены?
   Начните с /v1/chat/completions, потому что большинство сторонних клиентов его поддерживают.

Рекомендуемая конфигурация Crazyrouter#

Для большинства OpenAI-совместимых инструментов:

API Key: ваш Crazyrouter API ключ
Base URL: https://crazyrouter.com/v1
Model: выберите модель из списка моделей Crazyrouter

Для пользователей в регионах, где глобальный маршрут нестабилен:

Base URL: https://cn.crazyrouter.com/v1

Ссылки для пользователей могут использовать UTM отслеживание:

https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=api_endpoints

API endpoints не должны:

https://api-endpoint.example.invalid/v1?utm_source=blog

Быстрый чек-лист отладки#

Перед тем как сообщить "модель недоступна", проверьте эти пять вещей:

1. Написано ли имя модели точно так же, как показано в списке моделей?
2. Правильно ли семейство endpoint: chat completions, responses или messages?
3. Соответствует ли тело запроса schema этого endpoint?
4. Точно ли Base URL /v1, не пропущен ли он и не дублируются ли пути endpoint?
5. Используете ли вы правильный режим SDK: OpenAI-совместимый или Anthropic-native?

Финальная рекомендация#

Если вы создаёте интеграции общего назначения, начните с /v1/chat/completions. Это самый широкий путь совместимости.

Используйте /v1/responses когда ваш клиент или workflow явно требует Responses API.

Используйте /v1/messages когда вы используете Anthropic-native инструменты.

Большинство проблем с endpoint исчезают, когда вы помните это правило:

OpenAI-совместимый клиент → /v1/chat/completions
OpenAI Responses клиент → /v1/responses
Anthropic-native клиент → /v1/messages

Если модель существует, но выглядит недоступной, не только меняйте имя модели. Сначала проверьте endpoint и schema запроса.