> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# IDE & SDK 호환성
> AI 코딩 도구, SDK 및 프레임워크를 위한 검증된 호환성 가이드
## 개요
TokenLab은 일반적인 코딩 도구, SDK 및 프레임워크가 최소한의 접착 코드(glue code)로 통합될 수 있도록 다양한 API 형식을 제공합니다.
이 페이지는 마케팅용 매트릭스보다 의도적으로 더 구체적인 정보를 담고 있습니다:
* **지원됨(Supported)**: 구체적인 설정 경로를 문서화했으며, TokenLab이 해당 경로에서 기대하는 프로토콜 형태를 노출함을 의미합니다.
* **강력한 네이티브 경로(Strong native path)**: 해당 리포지토리에 해당 프로토콜 제품군을 위한 직접적인 어댑터나 요청 형식 증거가 있음을 의미합니다.
* **최선형 지원(Best-effort)**: 통합이 작동할 수는 있지만, 업스트림 클라이언트가 이 사용자 지정 게이트웨이 워크플로우를 안정적인 계약으로 취급하지 않음을 의미합니다.
지원되지 않는 필드는 일관되게 처리되지 않습니다. 호환성 경로에서 일부 필드는 무시되거나 정규화됩니다. `/v1/responses` 경로에서는 해당 경로가 요청된 동작을 보장할 수 없을 때 명시적인 `400` 또는 `503` 오류를 반환할 수 있습니다.
## 지원되는 API 형식
| 엔드포인트 | 형식 | 사용 사례 |
| --------------------------------------- | ------------------ | -------------- |
| `/v1/chat/completions` | OpenAI Chat | 범용 호환성 |
| `/v1/responses` | OpenAI Responses | 상태 유지 대화 |
| `/v1/messages` | Anthropic Messages | Claude 네이티브 기능 |
| `/v1beta/models/:model:generateContent` | Google Gemini | Gemini 네이티브 기능 |
## IDE 및 CLI 호환성
### 문서화된 도구 경로
| 도구 | 지원 수준 | 형식 | 참고 사항 |
| ------------------- | ------------ | ---------------- | --------------------------------------------------------------------------------------- |
| **Cursor** | 제한적 지원 | OpenAI 호환 | BYOK 표준 채팅/에디터 흐름에는 작동하지만, Tab Completion과 같은 Cursor 관리 기능의 대체재로는 작동하지 않음 |
| **Claude Code CLI** | 강력한 네이티브 경로 | Anthropic | Thinking 및 `tool_choice`에 대한 어댑터 커버리지를 갖춘 네이티브 `/v1/messages` 경로 |
| **Codex CLI** | 모델/경로 제한적 지원 | OpenAI Responses | `/v1/responses`를 Codex 전용 워크플로우를 위한 고급 경로로 취급; 일부 Responses 전용 필드는 모든 모델 및 경로에서 보장되지 않음 |
| **Gemini CLI** | 최선형 / 실험적 | Gemini | 사용자 지정 TokenLab 베이스 URL 흐름은 공식 Gemini CLI 통합이 아님 |
| **OpenCode** | 지원됨 | OpenAI 호환 | 기본적으로 OpenAI 호환 공급자를 사용하고, 명시적으로 필요한 경우에만 Responses 기반 공급자로 전환 |
| **OpenHands** | 지원됨 | OpenAI 호환 | `openai/` 및 TokenLab의 `/v1` 베이스 URL과 함께 LiteLLM/OpenAI 호환 경로 사용 |
다른 OpenAI 호환 에디터 및 에이전트 도구도 동일한 베이스 URL 패턴으로 작동하는 경우가 많습니다. 프로덕션 환경에서 사용하기 전에 해당 도구의 자체 사용자 지정 공급자 지원 여부를 확인하십시오.
### 구성 예시
```
Base URL: https://api.tokenlab.sh/v1
API Key: sk-your-tokenlab-key
```
Cursor는 내부적으로 Anthropic 스타일의 도구 형식을 사용합니다. TokenLab은 다음 두 가지를 모두 지원합니다:
* OpenAI 형식: `{ type: "function", function: { name, parameters } }`
* Anthropic 형식: `{ name, input_schema }` (type 필드 없음)
```bash theme={null}
export ANTHROPIC_BASE_URL="https://api.tokenlab.sh"
export ANTHROPIC_API_KEY="sk-your-tokenlab-key"
```
```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
export LOCAL_ENDPOINT="https://api.tokenlab.sh/v1"
```
```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
export OPENAI_BASE_URL="https://api.tokenlab.sh/v1"
aider --model gpt-5.4
```
## SDK 호환성
### 문서화된 SDK 및 프레임워크 경로
| SDK / 프레임워크 | 언어 | 지원 수준 | 참고 사항 |
| -------------------------------------------------------- | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI SDK** | Python/JS/Go | 핵심 경로 지원 | `/v1` Chat Completions 및 Embeddings 호환 경로; 공급자별 동작에는 네이티브 공급자 경로를 사용하며, Responses 전용 필드가 모든 모델에서 작동한다고 가정하지 마십시오 |
| **Anthropic SDK** | Python/JS | 강력한 네이티브 경로 | 도구, Thinking 및 프롬프트 캐싱에 대한 직접적인 증거를 갖춘 네이티브 Messages 경로 |
| **Vercel AI SDK** | TypeScript | 권장 통합 패턴 | `@ai-sdk/openai-compatible`을 우선 사용; 명시적으로 Responses 네이티브 동작을 원할 때만 `@ai-sdk/openai` 사용 |
| **LangChain** | Python/JS | 표준 인터페이스 지원 | `ChatOpenAI` 및 `OpenAIEmbeddings`가 의도된 범위임; 공급자 네이티브 추가 기능은 범위 밖임 |
| **LlamaIndex** | Python | `OpenAILike`를 통해 지원 | TokenLab과 같은 타사 게이트웨이에는 내장 OpenAI 클래스가 아닌 `OpenAILike` 사용 |
| **OpenAI Agents SDK** | Python | 채팅 완료 경로 지원 | `OpenAIChatCompletionsModel`과 함께 `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` 사용; 네이티브 Responses 동작은 선택한 모델 및 경로에 따라 다름 |
| **AutoGen** | Python | 사용자 지정 엔드포인트 경로 지원 | `base_url: https://api.tokenlab.sh/v1`과 함께 `OpenAIChatCompletionClient` 사용 |
| **Semantic Kernel** | .NET | 사용자 지정 엔드포인트 경로 지원 | OpenAI 채팅 완료 커넥터 사용자 지정 엔드포인트를 사용하고 `https://api.tokenlab.sh/v1`을 가리킴 |
| **CrewAI** | Python | 사용자 지정 엔드포인트 경로 지원 | `OPENAI_API_BASE` 또는 `LLM(base_url=...)`을 TokenLab의 `/v1` 엔드포인트로 설정 |
| **Pydantic AI** | Python | OpenAI 호환 공급자 경로 지원 | `OpenAIProvider(base_url="https://api.tokenlab.sh/v1")`과 함께 `OpenAIChatModel` 사용 |
| **DSPy** | Python | 사용자 지정 엔드포인트 경로 지원 | `dspy.LM("openai/", api_base="https://api.tokenlab.sh/v1")` 사용 |
| **Langflow** | Python / Web | 범위 제한적 지원 | OpenAI 구성 요소의 **OpenAI API Base** 필드에 TokenLab의 `/v1` 엔드포인트 사용 |
| **Haystack** | Python | 사용자 지정 엔드포인트 경로 지원 | `OpenAIChatGenerator(api_base_url="https://api.tokenlab.sh/v1")` 사용 |
| **Graphiti** | Python | 사용자 지정 엔드포인트 경로 지원 | TokenLab의 `/v1` 엔드포인트와 함께 `OpenAIGenericClient` 사용 |
| **Dify** | - | 범위 제한적 지원 | OpenAI 공급자 및 채팅 완료 지향 흐름이 의도된 경로임; Codex 전용 Responses 또는 WebSocket 동작에는 적합하지 않음 |
| **Flowise** | Web / Node | 범위 제한적 지원 | 사용 가능한 경우 TokenLab 채팅 노드를 사용하거나 `https://api.tokenlab.sh/v1`을 가리키는 ChatOpenAI 호환 노드 사용 |
| **Mem0** | Python | 사용자 지정 엔드포인트 경로 지원 | OpenAI 공급자를 유지하고 `openai_base_url`을 TokenLab의 `/v1` 엔드포인트로 설정 |
| **Agno** | Python | 지원되는 경로 | 사용 가능한 경우 TokenLab 모델 래퍼를 사용하거나 OpenAI 호환 베이스 URL 경로 사용 |
| **Browser Use** | Python | 사용자 지정 엔드포인트 경로 지원 | TokenLab의 `/v1` 엔드포인트와 함께 `ChatOpenAILike` 사용 |
| **VoltAgent** | TypeScript | 사용자 지정 엔드포인트 경로 지원 | `baseURL: "https://api.tokenlab.sh/v1"`로 구성된 AI SDK OpenAI 공급자 전달 |
| **Ragas** | Python | 사용자 지정 엔드포인트 경로 지원 | `llm_factory`에 `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` 전달 |
| **Guardrails** | Python | 유효성 검사 경로 지원 | TokenLab의 `/v1` 엔드포인트로 구성된 OpenAI SDK 채팅 완료 호출 가능 객체 전달 |
| **Prompt flow** | Python / CLI | 사용자 지정 엔드포인트 경로 지원 | `base_url=https://api.tokenlab.sh/v1`로 OpenAI 연결 생성 |
| **Promptfoo** | CLI / Node | 지원되는 경로 | `apiBaseUrl: https://api.tokenlab.sh/v1`과 함께 OpenAI 채팅 또는 Responses 공급자 사용 |
| **Portkey Gateway** | Gateway | 지원되는 경로 | OpenAI 호환 채팅 및 Responses 트래픽을 위한 업스트림 공급자로 TokenLab 사용 |
| **Helicone** | Gateway / Observability | 관측 가능성 경로 지원 | `Helicone-Target-Url: https://api.tokenlab.sh`와 함께 Helicone Gateway를 통해 OpenAI 호환 요청 라우팅 |
| **Langfuse** | Observability | 추적 경로 지원 | TokenLab의 `/v1` 베이스 URL로 Langfuse OpenAI 통합 구성 |
| **OpenLIT** | Observability | 추적 경로 지원 | TokenLab의 `/v1` 베이스 URL로 구성된 OpenAI SDK 클라이언트 계측 |
| **OpenLLMetry** | Observability | 추적 경로 지원 | TokenLab의 `/v1` 베이스 URL로 OpenAI SDK 계측 사용 |
| **Phoenix** | Observability | 추적 경로 지원 | TokenLab의 `/v1` 베이스 URL로 구성된 OpenAI SDK 클라이언트 자동 계측 |
| **Opik** | Observability | 추적 경로 지원 | TokenLab의 `/v1` 베이스 URL로 구성된 OpenAI SDK 클라이언트 래핑 |
| **LangBot** | Bot Platform | 채팅 경로 지원 | 사용 가능한 경우 TokenLab 요청자를 사용하거나 TokenLab의 `/v1` 엔드포인트로 OpenAI 호환 요청자 구성 |
| **Open WebUI** | Web Chat | 채팅 앱 경로 지원 | TokenLab을 OpenAI 호환 API 연결로 추가하고 모델 목록 새로 고침 |
| **Chatbox / DeepChat / Jan / LibreChat / Cherry Studio** | Desktop / Web | 채팅 앱 경로 지원 | 각 앱의 OpenAI 호환 사용자 지정 공급자 흐름 사용; 이 앱들은 일반적으로 채팅 완료 지향적임 |
## 채팅 완료(Chat Completions) 매개변수
### 핵심 매개변수
| 매개변수 | 유형 | 설명 |
| ------------- | ------- | --------------- |
| `model` | string | 모델 식별자 (필수) |
| `messages` | array | 대화 메시지 (필수) |
| `max_tokens` | integer | 최대 출력 토큰 |
| `temperature` | number | 샘플링 온도 (0-2) |
| `top_p` | number | 뉴클리어스 샘플링 (0-1) |
| `stream` | boolean | 스트리밍 활성화 |
### 도구 호출(Tool Calling)
```json theme={null}
{
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
},
"strict": true
}
}
],
"tool_choice": "auto",
"parallel_tool_calls": true
}
```
### 도구 선택 옵션
| 형식 | 예시 | 설명 |
| ---------------- | --------------------------------------------------------------------- | ----------------- |
| String | `"auto"`, `"none"`, `"required"` | 단순 선택 |
| OpenAI Object | `{ "type": "function", "function": { "name": "fn" } }` | 특정 함수 강제 |
| Anthropic Object | `{ "type": "tool", "name": "fn", "disable_parallel_tool_use": true }` | Anthropic 네이티브 형식 |
### 고급 매개변수
| 매개변수 | 유형 | 설명 |
| ------------------- | ------------ | ---------------------------------------------------------- |
| `stream_options` | object | Chat Completions 전용: 토큰 수 계산을 위한 `{ include_usage: true }` |
| `reasoning_effort` | string | 추론 활성화 GPT-5 모델을 위한 `"low"`, `"medium"`, `"high"` |
| `service_tier` | string | `"auto"` 또는 `"default"` |
| `seed` | integer | 결정론적 출력 |
| `logprobs` | boolean | 로그 확률 반환 |
| `top_logprobs` | integer | 상위 로그 확률 개수 (0-20) |
| `logit_bias` | object | 토큰 편향 맵 (-100 \~ 100) |
| `frequency_penalty` | number | 반복 페널티 (-2 \~ 2) |
| `presence_penalty` | number | 주제 페널티 (-2 \~ 2) |
| `stop` | string/array | 중지 시퀀스 |
| `n` | integer | 완료 개수 (1-128) |
| `user` | string | 추적을 위한 사용자 식별자 |
### OpenAI 고급 기능
| 매개변수 | 유형 | 설명 |
| ------------ | ------- | ---------------------------- |
| `modalities` | array | 멀티모달을 위한 `["text", "audio"]` |
| `audio` | object | 오디오 출력 구성 (음성, 형식) |
| `prediction` | object | 더 빠른 완료를 위한 예측 출력 |
| `metadata` | object | 추적을 위한 키-값 쌍 |
| `store` | boolean | 나중에 검색할 수 있도록 저장 |
### 공급자별 옵션
```json theme={null}
{
"anthropic_options": {
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"prompt_caching": true
},
"google_options": {
"safety_settings": [...],
"google_search": true,
"code_execution": true
}
}
```
## Anthropic Messages 매개변수
### 핵심 매개변수
| 매개변수 | 유형 | 설명 |
| ------------ | ------------ | ----------------- |
| `model` | string | 모델 식별자 |
| `messages` | array | 대화 메시지 |
| `max_tokens` | integer | 최대 출력 (최대 128000) |
| `system` | string/array | 시스템 프롬프트 |
| `stream` | boolean | 스트리밍 활성화 |
### 도구 호출(Tool Calling)
```json theme={null}
{
"tools": [
{
"name": "get_weather",
"description": "Get weather",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
}
}
],
"tool_choice": {
"type": "auto",
"disable_parallel_tool_use": false
}
}
```
### 확장된 Thinking
```json theme={null}
{
"model": "claude-opus-4-6",
"thinking": {
"type": "enabled",
"budget_tokens": 10000
}
}
```
## Responses API 매개변수
### 핵심 매개변수
| 매개변수 | 유형 | 설명 |
| ---------------------- | ------------ | -------- |
| `model` | string | 모델 식별자 |
| `input` | string/array | 입력 콘텐츠 |
| `instructions` | string | 시스템 지침 |
| `max_output_tokens` | integer | 최대 출력 토큰 |
| `previous_response_id` | string | 대화 이어가기 |
### 고급 매개변수
| 매개변수 | 유형 | 설명 |
| --------------------- | ------ | --------------------------------- |
| `truncation_strategy` | string | `"auto"` 또는 `"disabled"` |
| `include` | array | `["reasoning.encrypted_content"]` |
| `reasoning_effort` | string | 추론 모델용 |
| `service_tier` | string | 우선순위 계층 |
### 도구 형식
OpenAI 및 Anthropic 도구 형식을 모두 지원합니다:
```json theme={null}
// OpenAI 형식
{ "type": "function", "name": "fn", "parameters": {...} }
// Anthropic 형식 (Cursor 호환성)
{ "name": "fn", "input_schema": {...} }
```
## Gemini API 매개변수
### 핵심 매개변수
| 매개변수 | 유형 | 설명 |
| ------------------- | ------ | -------- |
| `contents` | array | 대화 콘텐츠 |
| `systemInstruction` | object | 시스템 프롬프트 |
| `generationConfig` | object | 생성 설정 |
### 도구(Tools)
```json theme={null}
{
"tools": [{
"functionDeclarations": [{
"name": "search",
"description": "Search the web",
"parameters": {...}
}],
"codeExecution": {},
"googleSearch": {}
}],
"toolConfig": {
"functionCallingConfig": {
"mode": "AUTO"
}
}
}
```
### 안전 설정(Safety Settings)
```json theme={null}
{
"safetySettings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"threshold": "BLOCK_MEDIUM_AND_ABOVE"
}
]
}
```
### 추가 매개변수
| 매개변수 | 유형 | 설명 |
| ------------------ | ------ | -------------------------------------- |
| `cachedContent` | string | 캐시된 콘텐츠 참조 |
| `responseMimeType` | string | `"text/plain"` 또는 `"application/json"` |
| `responseSchema` | object | 구조화된 출력을 위한 JSON 스키마 |
## 스트리밍
채팅 완료 및 Responses를 포함하여 `stream: true`를 노출하는 생성 엔드포인트는 서버 전송 이벤트(SSE)를 사용합니다:
```bash theme={null}
# Chat Completions
curl https://api.tokenlab.sh/v1/chat/completions \
-H "Authorization: Bearer sk-xxx" \
-d '{"model": "gpt-4o", "messages": [...], "stream": true}'
# Chat Completions 사용량 추적
-d '{"...", "stream_options": {"include_usage": true}}'
```
## 오류 처리
TokenLab은 OpenAI 호환 오류 응답을 반환합니다:
```json theme={null}
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}
```
자세한 내용은 [오류 처리 가이드](/guides/error-handling)를 참조하십시오.
## 모범 사례
알 수 없는 매개변수는 선택한 공개 경로와 모델이 지원하는 경우에만 전달됩니다.
Chat Completions 스트리밍의 경우, 정확한 토큰 수를 위해 `stream_options.include_usage`를 활성화하십시오. Responses는 자체 스트리밍 계약을 가지고 있으며 이 Chat 전용 옵션을 노출하지 않습니다.
SDK에서 기대하는 형식과 일치시키십시오. TokenLab은 OpenAI 및 Anthropic 형식을 모두 허용합니다.