---
title: "Base URL, 인터페이스 및 인증"
description: "1折AI의 Base URL, 사용 가능한 인터페이스, 요청 헤더 작성법, 그리고 각 도구에서 /v1을 붙여야 하는지 여부."
headingIds: {"사용 가능한 인터페이스":"section-1","/v1을 붙여야 하는가":"section-2","인증 요청 헤더":"section-3","API 키 사용 가능 여부 확인":"section-4","속도 제한":"section-5","네트워크":"section-6"}
---
모든 요청은 동일한 도메인으로 전송되며, 프로토콜에 따라 두 가지 경로로 나뉩니다.
```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는 첨부하지 않음). 자세한 내용은 [시스템 프롬프트의 요금 부과](/ko/docs/pricing-explained/#section-3)을 참조하세요.
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 키는 요청 헤더에 넣으며, 두 가지 작성법 모두 가능합니다:
```text title="Anthropic 原生"
x-api-key: sk-你的Key
anthropic-version: 2023-06-01
content-type: application/json
```
```text title="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의 모델 자동 탐색은 이 형식을 읽습니다.
기타 경우는 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
## 속도 제한
현재 API 키에 속도 제한을 두지 않습니다. 429를 받으면 대개 업스트림 부하가 높은 것이므로 잠시 후 재시도하면 되고, 배치 작업은 지수 백오프를 적용하세요. 자세한 내용은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
## 네트워크
연결 시간 초과 또는 TLS 오류가 발생하면 터미널이 사용하는 네트워크를 먼저 확인하세요. 전역 프록시가 켜져 있다면 프록시를 끄고 직접 연결로 다시 시도하고, 회사 네트워크에 출구 화이트리스트가 있는 경우 `1zheai.com`을 허용해야 합니다.