/v1/chat/completions vs /v1/responses vs /v1/messages: 어떤 AI API 엔드포인트(Endpoint)를 사용해야 할까요?

AI API 게이트웨이(Gateway)에서 발생하는 흔한 지원 이슈는 API 키도, 모델(Model)도, SDK도 아닙니다. 바로 엔드포인트(Endpoint)입니다.

사용자가 존재하는 모델을 선택했지만, 잘못된 엔드포인트로 요청을 보내는 경우입니다. 그 결과는 다음과 같이 나타납니다:

• model unavailable (모델 사용 불가);
• unsupported endpoint (지원되지 않는 엔드포인트);
• invalid request body (유효하지 않은 요청 본문);
• tool calling (도구 호출) 작동 불능;
• streaming (스트리밍) 형식 불일치;
• Claude 모델이 한 도구에서는 작동하지만 다른 도구에서는 실패함.

이 가이드는 다음 세 가지 엔드포인트 제품군(Endpoint families)의 차이점을 설명합니다:

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

요약 버전:

엔드포인트 (Endpoint)	네이티브 생태계 (Native ecosystem)	최적 용도	요청 스타일 (Request style)
/v1/chat/completions	OpenAI 호환 레거시/현재 채팅	대부분의 앱, SDK, LiteLLM, Cursor 스타일 도구, 단순 채팅	messages: [{role, content}]
...

만약 클라이언트가 "OpenAI 호환(OpenAI-compatible)"이라고 말한다면, 다음으로 시작하세요:

또는 기본 URL(Base URL)을 다음과 같이 설정하세요:

그리고 SDK가 /chat/completions를 추가하도록 하십시오.

만약 사용 중인 도구가 구체적으로 OpenAI Responses API를 요구한다면, /v1/responses를 사용하십시오.

만약 사용 중인 도구가 Anthropic 네이티브(Anthropic-native)이며 Claude의 Messages API를 기대한다면, /v1/messages를 사용하십시오.

가장 흔한 실수

가장 흔한 실수는 모델 제품군(Model family)과 엔드포인트 제품군(Endpoint family)을 혼합하는 것입니다.

예를 들어, Claude 모델은 OpenAI 호환 게이트웨이를 통해 노출될 수 있지만, 그렇다고 해서 귀하의 요청 본문(Request body)이 자동으로 Anthropic의 네이티브 /v1/messages 스키마(Schema)를 사용해야 한다는 의미는 아닙니다.

마찬가지로, /v1/messages로 Anthropic 네이티브 요청을 보내는 도구는 모델 이름만 변경한다고 해서 해결되지 않습니다. 엔드포인트와 요청 본문이 반드시 일치해야 합니다.

이렇게 생각하십시오:

모델 이름(Model name) + 엔드포인트(Endpoint) + 요청 스키마(Request 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" \
...

다음과 같은 경우에 /v1/chat/completions를 사용하세요:

• 앱이 OpenAI 호환 API (OpenAI-compatible API)를 지원한다고 명시한 경우
• 설정에서 OPENAI_BASE_URL 또는 base_url을 요구하는 경우
• 요청 본문 (Request body)에서 role과 content가 포함된 messages를 사용하는 경우
• 일반적인 OpenAI SDK 호환 모드 (Compatibility mode)를 사용하는 경우
• Cursor 스타일의 클라이언트, LiteLLM 스타일의 라우터 (Router), FastGPT 스타일의 앱, 또는 많은 채팅 UI와 같은 도구를 설정하는 경우

많은 사용자에게 이것은 가장 안전한 기본 엔드포인트 (Default endpoint)입니다.

/v1/responses란 무엇인가

/v1/responses는 더 최신인 OpenAI Responses API 엔드포인트입니다.

이것은 더 일반적인 응답 객체 (Response object)를 중심으로 설계되었으며, 다음과 같은 것들을 나타낼 수 있습니다:

• 텍스트 출력 (Text output)
• 도구 호출 (Tool calls)
• 멀티모달 입력 (Multimodal input)
• 추론 항목 (Reasoning items)
• 구조화된 출력 (Structured output)
• 에이전트 방식의 워크플로우 (Agent-like workflows)

단순화된 요청은 다음과 같습니다:

curl https://crazyrouter.com/v1/responses \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
...

다음과 같은 경우에 /v1/responses를 사용하세요:

• 도구가 OpenAI Responses API를 사용한다고 명시적으로 밝힌 경우
• 설정에서 chat.completions 대신 responses를 언급하는 경우
• 요청 본문에서 messages 대신 input을 사용하는 경우
• 모델/제공자 라우트 (Model/provider route)가 Responses API 동작을 지원하는 경우
• 최신 OpenAI 스타일의 도구 (Tool) 또는 추론 (Reasoning) 출력 형식이 필요한 경우

게이트웨이에서 해당 변환을 명시적으로 문서화하지 않는 한, /v1/responses로 Chat Completions 본문을 보내지 마세요.

/v1/messages란 무엇인가

/v1/messages는 Anthropic Messages API 스타일의 엔드포인트입니다.

전형적인 Claude 네이티브 (Claude-native) 요청은 다음과 같습니다:

curl https://crazyrouter.com/v1/messages \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
...

다음과 같은 경우에 /v1/messages를 사용하세요:

• 클라이언트가 Anthropic-native(Anthropic 전용)인 경우;
• SDK가 Claude Messages API 형식을 기대하는 경우;
• 요청에 배열 내부의 system 메시지 대신 최상위(top-level) system 필드가 있는 경우;
• 요청에 Anthropic 전용 콘텐츠 블록(content blocks) 또는 도구 스키마(tool schema)가 필요한 경우;
• 문서에서 명시적으로 /v1/messages를 호출하라고 안내하는 경우.

모든 Claude 모델을 /v1/messages로 호출해야 한다고 가정하지 마세요. 만약 OpenAI 호환 게이트웨이(gateway) 또는 SDK를 사용 중이라면, Claude 모델은 대신 /v1/chat/completions를 통해 호출될 수 있습니다.

엔드포인트(Endpoint) 실수가 모델을 사용할 수 없는 것처럼 보이게 만드는 이유

모델 호출에 실패하면 사용자들은 종종 모델이 다운되었다고 가정합니다. 하지만 많은 경우, 모델은 정상이며 요청 형식(request format)이 잘못된 것입니다.

일반적인 불일치 사례:

실수	발생하는 현상	해결 방법
/v1/responses로 messages 채팅 본문을 전송함	잘못된 요청 본문(invalid request body) 또는 필드 무시	/v1/chat/completions를 사용하거나 본문을 input으로 변경
...

Base URL vs 전체 엔드포인트(Full Endpoint)

많은 도구들이 전체 엔드포인트가 아닌 Base URL(기본 URL)을 요구합니다.

올바른 Base URL:

그러면 SDK는 다음과 같이 호출합니다:

대부분의 SDK에서 잘못된 Base URL:

이유는 무엇일까요? SDK가 /chat/completions를 다시 붙일 수 있기 때문입니다.

규칙:

• 필드 이름이 base_url인 경우, /v1을 사용하세요.
• 필드 이름이 endpoint이고 전체 URL을 요구하는 경우, 해당 도구가 요구하는 전체 경로(full path)를 사용하세요.

어떤 엔드포인트를 선택해야 할까요?

다음 의사결정 트리(decision tree)를 사용하세요:

1. 사용 중인 도구가 “OpenAI 호환 API(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 key
Base URL: https://crazyrouter.com/v1
Model: Crazyrouter 모델 목록에서 모델을 선택하세요

글로벌 경로(Global route)가 불안정한 지역의 사용자의 경우:

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

사용자 대상 링크(Human-facing links)는 UTM 트래킹을 사용할 수 있습니다:

API 엔드포인트(Endpoints)는 다음과 같이 해서는 안 됩니다:

빠른 디버깅 체크리스트

"모델 사용 불가(model unavailable)"를 보고하기 전에, 다음 다섯 가지 사항을 확인하세요:

1. 모델 이름이 모델 목록에 표시된 것과 정확히 일치하게 철자가 작성되었습니까?
2. 엔드포인트 제품군(Endpoint family)이 올바릅니까: chat completions, responses, 또는 messages?
3. 요청 본문(Request body)이 해당 엔드포인트의 스키마(Schema)와 일치합니까?
4. Base URL이 정확히 /v1입니까? /v1을 누락하거나 엔드포인트 경로를 중복해서 작성하지 않았습니까?
5. 올바른 SDK 모드를 사용 중입니까: OpenAI 호환(OpenAI-compatible) 또는 Anthropic 네이티브(Anthropic-native)?

최종 권장 사항

일반적인 앱 통합(App integrations)을 구축하고 있다면, /v1/chat/completions로 시작하세요. 이것이 가장 폭넓은 호환성을 제공하는 경로입니다.

클라이언트 또는 워크플로우(Workflow)에서 Responses API를 명시적으로 요구하는 경우에는 /v1/responses를 사용하세요.

Anthropic 네이티브(Anthropic-native) 도구를 사용하는 경우에는 /v1/messages를 사용하세요.

대부분의 엔드포인트 문제는 다음 규칙을 기억하면 해결됩니다:

OpenAI 호환 클라이언트 (OpenAI-compatible client) → /v1/chat/completions
OpenAI Responses 클라이언트 (OpenAI Responses client) → /v1/responses
Anthropic 네이티브 클라이언트 (Anthropic-native client) → /v1/messages

모델이 존재하지만 사용 불가능한 것으로 나타난다면, 모델 이름만 변경하지 마세요. 먼저 엔드포인트와 요청 스키마(Request schema)를 확인하세요.