Base URL, 인터페이스 및 인증

1ZheAI가 관리하는 문서입니다. 출처 및 수정 사항.

오류를 발견하셨나요? 페이지 주소와 설명을 첨부하여 고객 지원으로 문의해 주세요. API 키나 계정 정보는 보내지 마세요.

모든 요청은 동일한 도메인으로 전송되며, 프로토콜에 따라 두 가지 경로로 나뉩니다.

text

https://1zheai.com

사용 가능한 인터페이스

인터페이스	프로토콜	용도
POST /v1/messages	Anthropic 네이티브	대화. Claude Code, Anthropic SDK, Cline(Anthropic 모드)이 이 경로를 사용합니다
POST /v1/chat/completions	OpenAI 호환	대화. OpenAI SDK, Cursor, Cherry Studio(OpenAI 모드)이 이 경로를 사용합니다
GET /v1/models	OpenAI 호환	API 키(API key)로 사용 가능한 모델 목록 조회
POST /v1/messages/count_tokens	Anthropic 네이티브	입력 텍스트의 토큰 수 계산. 대화를 생성하지 않으며 요금이 부과되지 않습니다

count_tokens의 요청 본문은 /v1/messages과 동일합니다(model, messages, system 및 tools 포함 가능). 응답에는 하나의 필드만 있습니다:

json

{"input_tokens":19}

count_tokens은 전송한 내용만 계산합니다. SDK, curl 또는 서드파티 도구로 실제 호출할 때는 매 요청에 시스템 프롬프트가 추가로 첨부되어 입력 토큰 기준으로 요금이 부과됩니다(Claude Code는 첨부하지 않음). 자세한 내용은 시스템 프롬프트의 요금 부과을 참조하세요.

Prompt Caching, extended thinking, 도구 호출과 같은 Claude 고유 기능은 네이티브 /v1/messages 사용이 가장 안정적입니다. OpenAI 호환 인터페이스는 기존 OpenAI 코드가 있고 모델만 바꾸고 싶은 경우에 적합합니다.

/v1을 붙여야 하는가

각 도구가 Base URL을 다르게 해석하는 경우가 있어, 연결 시 가장 흔한 함정입니다:

도구 / SDK	입력할 값	이유
Claude Code(ANTHROPIC_BASE_URL)	https://1zheai.com	도구가 직접 /v1/messages을 조합합니다
Anthropic SDK(base_url)	https://1zheai.com	위와 동일
OpenAI SDK(base_url)	https://1zheai.com/v1	SDK는 /chat/completions만 조합합니다
Cursor(Override OpenAI Base URL)	https://1zheai.com/v1	OpenAI SDK와 동일
Cherry Studio	https://1zheai.com	/v1/...을 자동으로 추가합니다
Cline(OpenAI Compatible)	https://1zheai.com/v1	OpenAI SDK와 동일

규칙: Anthropic 계열은 루트 주소를 입력하고, OpenAI 계열은 /v1까지 입력합니다. 잘못 입력하면 전형적으로 404가 발생합니다.

인증 요청 헤더

API 키는 요청 헤더에 넣으며, 두 가지 작성법 모두 가능합니다:

Anthropic 原生

Anthropic 原生

x-api-key: sk-你的Key
anthropic-version: 2023-06-01
content-type: application/json

Bearer（两种协议都支持）

Bearer（两种协议都支持）

Authorization: Bearer sk-你的Key
content-type: application/json

• /v1/messages 호출 시 공식 프로토콜에 따라 anthropic-version을 포함하며, 현재 값은 2023-06-01입니다. 실측 결과 포함하지 않아도 호출은 되지만, 공식 SDK와 도구는 모두 포함하므로 직접 요청을 작성할 때도 포함하세요.
• Claude Code의 ANTHROPIC_AUTH_TOKEN은 Authorization: Bearer을 전송하고, ANTHROPIC_API_KEY은 x-api-key을 전송합니다. 두 방식 모두 인식합니다.
• beta 기능이 필요하면 공식 문서에 따라 anthropic-beta 헤더를 포함하세요. 알 수 없는 값을 포함해도 오류가 발생하지 않으므로, 특정 beta 기능이 적용되었는지는 응답의 실제 결과로 판단하세요.

API 키 사용 가능 여부 확인

bash

curl https://1zheai.com/v1/models \
  -H "Authorization: Bearer sk-你的Key"

모델 목록이 반환되면 API 키와 주소가 모두 올바릅니다. 401이 반환되면 API 키 문제이며, 응답은 다음과 같습니다(2026-10-15 실측):

json

{"error":{"code":"","message":"Invalid token (request id: 202610150244361675490398268d9d6eKJPmcph)","type":"authentication_error"}}

x-api-key 및 anthropic-version 헤더로 /v1/models을 요청하면 Anthropic 형식의 모델 목록(data[].id, display_name, has_more)이 반환되며, Claude Code의 모델 자동 탐색은 이 형식을 읽습니다.

기타 경우는 오류 코드 및 문제 해결을 참조하세요.

속도 제한

현재 API 키에 속도 제한을 두지 않습니다. 429를 받으면 대개 업스트림 부하가 높은 것이므로 잠시 후 재시도하면 되고, 배치 작업은 지수 백오프를 적용하세요. 자세한 내용은 오류 코드 및 문제 해결을 참조하세요.

네트워크

연결 시간 초과 또는 TLS 오류가 발생하면 터미널이 사용하는 네트워크를 먼저 확인하세요. 전역 프록시가 켜져 있다면 프록시를 끄고 직접 연결로 다시 시도하고, 회사 네트워크에 출구 화이트리스트가 있는 경우 1zheai.com을 허용해야 합니다.