#responses 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

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

EndpointРодная экосистемаЛучше всего дляСтиль запроса/v1/chat/completionsOpenAI-совместимый legacy/текущий chatБольшинство приложений, SDKs, LiteLLM, Cursor-style инструменты, простой chatmessages: [{role, content}]/v1/responsesНовый OpenAI Responses APITool use, multimodal, reasoning items, новые OpenAI-style агентыinput, tools, structured response items/v1/messagesAnthropic Claude APIClaude-native SDKs и Claude-style приложенияmessages плюс top-level system, Anthropic schema

Если ваш клиент говорит "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;

/v1/chat/completions vs /v1/responses vs /v1/messages: どのAI APIエンドポイントを使うべき？

AI APIゲートウェイにおける一般的なサポート問題は、APIキーでもなく、モデルでもなく、SDKでもありません。エンドポイントです。

ユーザーが存在するモデルを選択しても、リクエストを間違ったエンドポイントに送信してしまいます。結果は次のようになります：

モデル利用不可；

サポートされていないエンドポイント；

無効なリクエストボディ；

ツール呼び出しが機能しない；

ストリーミング形式の不一致；

Claudeモデルはあるツールでは動作するが別のツールでは失敗。

このガイドでは、3つのエンドポイントファミリーの違いを説明します：

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

簡易版：

エンドポイントネイティブエコシステム最適な用途リクエストスタイル/v1/chat/completionsOpenAI互換のレガシー/現在のチャットほとんどのアプリ、SDK、LiteLLM、Cursorスタイルツール、シンプルなチャットmessages: [{role, content}]/v1/responsesより新しいOpenAI Responses APIツール使用、マルチモーダル、推論アイテム、より新しいOpenAIスタイルのエージェントinput、tools、構造化応答アイテム/v1/messagesAnthropic Claude APIClaude ネイティブSDKとClaudeスタイルのアプリmessagesとトップレベルのsystem、Anthropicスキーマ

クライアントが「OpenAI互換」と言う場合は、以下から始めてください：

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

またはベースURLを次のように設定：

https://crazyrouter.com/v1

SDKが/chat/completionsを追加します。

ツールが特にOpenAI Responses APIを必要とする場合は、/v1/responsesを使用します。

ツールがAnthropicネイティブでClaudeのMessages APIを期待する場合は、/v1/messagesを使用します。

最も一般的な間違い

最も一般的な間違いは、モデルファミリーとエンドポイントファミリーを混ぜることです。

例えば、ClaudeモデルはOpenAI互換ゲートウェイを通じて公開できますが、それはリクエストボディがAnthropicネイティブの/v1/messagesスキーマを使用すべきということを自動的に意味しません。

同様に、Anthropicネイティブのリクエストを/v1/messagesに送信するツールは、モデル名を変更するだけでは修正できません。エンドポイントとリクエストボディが一致する必要があります。

このように考えてください：

モデル名 + エンドポイント + リクエストスキーマが一致する必要があります

この3つのうち1つが間違っていると、モデル自体が正常に動作していてもモデルが利用不可に見える場合があります。

/v1/chat/completionsとは

/v1/chat/completionsは古典的なOpenAI互換チャットエンドポイントです。

典型的なリクエストは次のようになります：

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を要求している；

リクエストボディがroleとcontentを持つmessagesを使用している；

一般的なOpenAI SDK互換モードを使用している；

Cursorスタイルクライアント、LiteLLMスタイルルーター、FastGPTスタイルアプリ、または多くのチャットUIなどのツールを設定している。

多くのユーザーにとって、これが最も安全なデフォルトエンドポイントです。

/v1/responsesとは

/v1/responsesはより新しいOpenAI Responses APIエンドポイントです。

より一般的な応答オブジェクトの周りに設計されており、以下のようなものを表現できます：

テキスト出力；

ツール呼び出し；

マルチモーダル入力；

推論アイテム；

構造化出力；

エージェントのようなワークフロー。

簡略化されたリクエストは次のようになります：

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を使用していると明示的に述べている；

/v1/chat/completions vs /v1/responses vs /v1/messages：应该使用哪个 AI API 端点？

AI API 网关中的常见支持问题不在 API 密钥、不在模型、也不在 SDK。问题在于端点。

用户选择了一个存在的模型，但将请求发送到了错误的端点。结果看起来像：

模型不可用；

不支持的端点；

无效的请求体；

工具调用不工作；

流式格式不匹配；

Claude 模型在一个工具中工作，但在另一个工具中失败。

本指南解释了三个端点族之间的区别：

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

简短版本：

端点本地生态最适合请求风格/v1/chat/completionsOpenAI 兼容旧版/当前聊天大多数应用、SDK、LiteLLM、Cursor 风格工具、简单聊天messages: [{role, content}]/v1/responses较新的 OpenAI Responses API工具使用、多模态、推理项、较新的 OpenAI 风格代理input、tools、结构化响应项/v1/messagesAnthropic Claude APIClaude 本地 SDK 和 Claude 风格应用messages 加顶级 system、Anthropic schema

如果您的客户端说"OpenAI 兼容"，从以下开始：

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

或将 Base URL 设置为：

https://crazyrouter.com/v1

并让 SDK 追加 /chat/completions。

如果您的工具特别需要 OpenAI Responses API，使用 /v1/responses。

如果您的工具是 Anthropic 本地工具且期望 Claude 的 Messages API，使用 /v1/messages。

最常见的错误

最常见的错误是混合模型族和端点族。

例如，Claude 模型可以通过 OpenAI 兼容网关公开，但这并不自动意味着您的请求体应该使用 Anthropic 的本地 /v1/messages schema。

同样，发送 Anthropic 本地请求到 /v1/messages 的工具不能仅通过更改模型名称来修复。端点和请求体必须匹配。

这样想：

model name + endpoint + request schema must match

如果三者中的任何一个错误，即使模型本身是健康的，模型看起来也可能不可用。

什么是 /v1/chat/completions

/v1/chat/completions 是经典的 OpenAI 兼容聊天端点。

典型的请求如下所示：

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；

请求体使用带有 role 和 content 的 messages；

您使用常见的 OpenAI SDK 兼容模式；

您正在配置 Cursor 风格客户端、LiteLLM 风格路由器、FastGPT 风格应用或许多聊天 UI 等工具。

对于许多用户来说，这是最安全的默认端点。

什么是 /v1/responses

/v1/responses 是较新的 OpenAI Responses API 端点。

它围绕一个更通用的响应对象设计，可以表示以下事项：

文本输出；

工具调用；

多模态输入；

推理项；

结构化输出；

类代理工作流。

简化的请求如下所示：

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；

/v1/chat/completions vs /v1/responses vs /v1/messages: Which AI API Endpoint Should You Use?

A common support issue in AI API gateways is not the API key, not the model, and not the SDK. It is the endpoint.

A user picks a model that exists, but sends the request to the wrong endpoint. The result looks like:

model unavailable;

unsupported endpoint;

invalid request body;

tool calling not working;

streaming format mismatch;

Claude model works in one tool but fails in another.

This guide explains the difference between three endpoint families:

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

Short version:

EndpointNative ecosystemBest forRequest style/v1/chat/completionsOpenAI-compatible legacy/current chatMost apps, SDKs, LiteLLM, Cursor-style tools, simple chatmessages: [{role, content}]/v1/responsesNewer OpenAI Responses APITool use, multimodal, reasoning items, newer OpenAI-style agentsinput, tools, structured response items/v1/messagesAnthropic Claude APIClaude-native SDKs and Claude-style appsmessages plus top-level system, Anthropic schema

If your client says “OpenAI-compatible”, start with:

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

or set base URL to:

https://crazyrouter.com/v1

and let the SDK append /chat/completions.

If your tool specifically requires the OpenAI Responses API, use /v1/responses.

If your tool is Anthropic-native and expects Claude’s Messages API, use /v1/messages.

The most common mistake

The most common mistake is mixing the model family and the endpoint family.

For example, a Claude model can be exposed through an OpenAI-compatible gateway, but that does not automatically mean your request body should use Anthropic’s native /v1/messages schema.

Likewise, a tool that sends Anthropic-native requests to /v1/messages cannot be fixed by only changing the model name. The endpoint and request body must match.

Think of it this way:

model name + endpoint + request schema must match

If one of the three is wrong, the model may look unavailable even when the model itself is healthy.

What /v1/chat/completions is

/v1/chat/completions is the classic OpenAI-compatible chat endpoint.

A typical request looks like this:

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."} ] }'

Use /v1/chat/completions when:

the app says it supports an OpenAI-compatible API;

the config asks for OPENAI_BASE_URL or base_url;

the request body uses messages with role and content;

you are using common OpenAI SDK compatibility mode;

you are configuring tools like Cursor-style clients, LiteLLM-style routers, FastGPT-style apps, or many chat UIs.

For many users, this is the safest default endpoint.

What /v1/responses is

/v1/responses is the newer OpenAI Responses API endpoint.

It is designed around a more general response object, and it can represent things like:

text output;

tool calls;

multimodal input;

reasoning items;

structured output;

agent-like workflows.

A simplified request looks like this:

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." }'

Use /v1/responses when:

the tool explicitly says it uses the OpenAI Responses API;