Skip to main content

개요

TokenLab는 하나의 API 키로 Chat Completions, Responses, Anthropic Messages, Gemini 네이티브의 네 가지 프로토콜 표면을 제공합니다. 네이티브 진입점은 모델이 해당 형식을 공개하고 동일 프로토콜 upstream 경로가 있을 때만 사용할 수 있으며 Chat Completions로 fallback하지 않습니다. 다른 프로토콜로 단방향 컴파일할 수 있는 것은 Chat 진입점뿐입니다.

OpenAI 형식

/v1/chat/completions 표준 형식, 가장 넓은 호환성

Responses

/v1/responses 네이티브 Responses 수명 주기와 이벤트

Anthropic 형식

/v1/messages 확장 사고, Claude 고유 기능 지원

Gemini 형식

/v1beta/models/:model:generateContent Google 생태계 통합

멀티 포맷을 사용하는 이유

형식 비교

OpenAI 형식

기존 OpenAI SDK 통합과 이식 가능한 채팅 또는 임베딩 플로우에는 이 호환 경로를 사용하세요. Claude 또는 Gemini 네이티브 동작에는 아래의 Anthropic 또는 Gemini 형식을 사용하세요.
적합한 용도:
  • 일반적인 사용
  • 기존 OpenAI SDK 통합
  • 최대 호환성

Anthropic 형식

Anthropic Messages API의 네이티브 형식입니다. 확장 사고와 같은 Claude 전용 기능을 사용하려면 필요합니다.

확장 사고 (Claude Opus 4.6)

Anthropic 형식에서만 사용할 수 있습니다:
적합한 용도:
  • Claude 전용 기능
  • 확장 사고 모드
  • 네이티브 Anthropic SDK 사용자

Gemini 형식

Google 생태계 통합을 위한 네이티브 Google Gemini API 형식입니다.

스트리밍

적합한 용도:
  • Google Cloud 통합
  • 기존 Gemini SDK 코드
  • 네이티브 Gemini 기능
Gemini Files 및 Cache: 네이티브 Gemini 경로에서 /upload/v1beta/files, /v1beta/files, /v1beta/files:register, /v1beta/cachedContents를 사용할 수 있습니다. Files는 Gemini File API 호환 업스트림 채널을 사용하고, 명시적 Cache 리소스는 Vertex AI 채널로도 라우팅할 수 있습니다. TokenLab를 통해 생성한 리소스는 같은 업스트림 채널/key에 바인딩되며 이후 generateContent 호출도 이 바인딩을 사용합니다.

도구 호환성 경계

함수 도구의 단방향 컴파일은 Chat 진입점에서만 가능하며 대상이 전체 도구 루프를 표현할 수 있어야 합니다. 공급자 네이티브 도구는 해당 네이티브 경로에 그대로 남아 있어야 합니다.
  • OpenAI Responses의 호스팅 및 네이티브 도구, 예를 들어 tool_search, web_search, file_search, code_interpreter, MCP, shell/apply_patch, computer-use 도구는 /v1/responses가 필요합니다.
  • Anthropic server/native 도구, 예를 들어 web_search_*, web_fetch_*, code_execution_*, tool_search_*, bash, computer-use, text-editor 도구는 /v1/messages가 필요합니다.
  • Gemini 내장 도구, 예를 들어 googleSearch, codeExecution, urlContext, computerUse 및 유사한 tools 필드는 /v1beta가 필요합니다.
TokenLab는 네이티브 프로토콜 요청을 Chat Completions로 낮추지 않습니다. 알 수 없는 필드와 도구 조합은 best-effort로 전달되며 지원 여부는 선택된 upstream이 결정합니다.

적절한 형식 선택

마이그레이션 가이드

OpenAI 공식 API에서

Anthropic 공식 API에서

Google AI Studio에서

이식 가능한 Chat 호환성

하나의 client가 서로 다른 upstream 프로토콜로 제공되는 모델에 접근해야 할 때는 /v1/chat/completions를 사용하세요. 이식 가능한 Chat 요청은 완전히 표현할 수 있을 때 Responses, Messages 또는 Gemini로 단방향 컴파일할 수 있습니다. Responses, Messages, Gemini 네이티브 요청은 Chat으로 변환되지 않으며 모델명이나 공급자명만으로 네이티브 가용성을 판단하지 않습니다.

Responses 및 Gemini 경계

현재 Responses 표면은 create, compact, retrieve, delete와 SSE를 포함합니다. background는 HTTP에서만 동작합니다. WebSocket은 response.create만 받으며 stream은 암시적입니다. 이 transport에서는 backgroundresponse.cancel을 제공하지 않습니다. delete는 cancel이 아닙니다. Gemini에서는 ProtoJSON lowerCamelCase와 원래 proto snake_case 이름이 모두 공식이며 혼합 요청에서도 그대로 보존됩니다. 현재 표면은 model list/get, generateContent, streamGenerateContent, countTokens, embedContent, batchEmbedContents를 포함하고 Interactions와 Live는 포함하지 않습니다. 알 수 없는 필드는 best-effort로 전달되며 지원 여부는 upstream이 결정합니다.