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

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

Chat Completions#

Используйте /v1/chat/completions, если:

• приложение уже работает с OpenAI-совместимым форматом;

• вам нужны обычные сообщения, streaming и function calling;

• вы хотите наиболее переносимый текстовый контракт.

Запрос использует messages, ответ — choices[0].message. Поток содержит последовательность chunks с delta.

Anthropic Messages#

Используйте /v1/messages, если:

• приложение использует Anthropic SDK;

• вы хотите сохранить структуру content blocks;

• вам нужны нативные thinking и Anthropic tool blocks.

Передавайте max_tokens явно. Ответ содержит массив content, а streaming состоит из именованных SSE-событий.

Responses#

Используйте /v1/responses, если:

• модель и сценарий рассчитаны на reasoning;

• нужны типизированные Items и цепочки ответов;

• нужны встроенные инструменты, доступные выбранной модели;

• вы начинаете новую агентную интеграцию.

Запрос использует input, ответ — output. Для простого текста SDK обычно предоставляет helper output_text.

Embeddings и медиа#

Для векторов используйте /v1/embeddings. Для изображений, аудио, видео и асинхронных генераций используйте endpoint со страницы конкретной модели.

Не смешивайте форматы#

Поля с похожим смыслом называются по-разному:

• Chat Completions: messages, response_format, max_completion_tokens;

• Messages: messages, thinking, max_tokens;

• Responses: input, text.format, reasoning, max_output_tokens.

Кросс-диалектная маршрутизация помогает с совместимым подмножеством, но не превращает эти контракты в полные синонимы.