# 1折AI · 전체 문서
# 1ZheAI 문서
Source: https://1zheai.com/ko/docs/
Markdown: https://1zheai.com/ko/docs/index.md
---
title: "1ZheAI 문서"
description: "모델 API, 완제 계정 및 구독 대충전의 사용 진입점, 구매 유의사항, 주문 및 애프터세일 규칙."
headingIds: {"모델 API 연동":"section-1","무엇을 하시겠습니까":"section-2","조회 및 지원":"section-3","사용 전 가장 자주 묻는 질문":"section-4","개발자 빠른 참조":"section-5"}
---
모델 API 연결, AI 계정 구매, 기존 계정의 구독 활성화 중 필요한 작업부터 시작하세요.
플랫폼, 구독 등급, 제공 내용 및 최초 로그인 유의사항을 확인합니다.계정 조건, 필요한 자료 및 개통 절차를 확인합니다.지역, 유효기간, 교환 방법 및 적용 계정을 확인합니다.취소, 제공 이상, 계정 정지 및 환불 규칙을 확인합니다.
## 모델 API 연동
1折AI는 Claude 및 OpenAI / GPT API를 제공하며, Anthropic Messages, OpenAI Responses 및 Chat Completions를 지원합니다. 주요 인터페이스로는 Anthropic 네이티브의 `/v1/messages` 및 OpenAI 호환의 `/v1/chat/completions`이 있습니다. 보유한 코드와 도구는 일반적으로 두 곳만 변경하면 됩니다: Base URL과 API 키(API key).
```text
Anthropic Base URL https://1zheai.com
OpenAI Base URL https://1zheai.com/v1
API Key sk-...（在控制台创建）
```
Claude 입력 및 출력은 각 모델의 할인율로 과금되며, 캐시 읽기 및 캐시 쓰기는 공식 정가로 할인 없이 과금됩니다. GPT, MiMo 및 이미지 생성 모델의 가격과 과금 단위는[모델 및 가격](https://1zheai.com/en/pricing/)에서 확인하세요.
Claude, GPT, MiMo 및 이미지 생성 모델이 출시되었으며, 전체 목록은[지원 모델](/ko/docs/models/)에서 확인하세요.
## 무엇을 하시겠습니까
Claude Code, Codex CLI, Cursor, Cline, Cherry Studio 및 CC Switch. 먼저 지원 범위를 확인한 후 단계에 따라 구성하세요.Anthropic SDK, OpenAI SDK 또는 curl로 시작하여 스트리밍 출력을 계속 알아보세요.기계 판독 문서, 페이지 목록 및 복사 가능한 AI 연동 작업 설명.회원가입, API 키 생성 후 첫 번째 요청을 완료하세요.
## 조회 및 지원
엔드포인트, 프로토콜, 예제 및 호환 범위를 찾습니다.비용, 호출 기록 및 문제 해결 경로를 확인합니다.
## 사용 전 가장 자주 묻는 질문
반환 필드와 사용량을 확인하세요; 이러한 확인만으로는 모델 출처를 단독으로 증명할 수 없습니다.
캐시를 어떻게 활성화하고, 적중을 어떻게 확인하며, 적중 시 얼마나 저렴해지는지.
401, 404, 429, 5xx가 각각 어떤 상황인지.
결제 수단, 7일 환불, 인voice 규칙.
## 개발자 빠른 참조
| 작업 | 바로 보기 |
| --- | --- |
| 처음 코드 작성 | [완전 실행 가능한 예제](/ko/docs/code-examples/) |
| 다른 플랫폼에서 전환 | [마이그레이션 가이드](/ko/docs/migration/) |
| 모델 및 프로토콜 조회 | [모델 조회](/ko/docs/api-models/) · [인터페이스 참조](/ko/docs/api-reference/) |
| 타임아웃 및 속도 제한 처리 | [타임아웃 및 재시도](/ko/docs/retries/) |
| 자주 묻는 질문 찾기 | [연동 FAQ](/ko/docs/faq/) |
---
# 빠른 시작
Source: https://1zheai.com/ko/docs/quickstart/
Markdown: https://1zheai.com/ko/docs/quickstart.md
---
title: "빠른 시작"
description: "1zheai API 키를 생성하고 curl 또는 SDK로 첫 Claude / GPT 호출을 완료한 뒤, 자주 사용하는 클라이언트에 연결하세요."
headingIds: {"GPT로 시작할 수도 있습니다":"section-1","다음 단계":"section-2"}
---
목표: 5분 이내에 API 키를 받고 첫 Claude 또는 GPT 요청을 완료합니다.
[1zheai.com/register](https://1zheai.com/register?lng=ko)을 열어 회원가입하세요. 호출할 때마다 잔액에서 차감되므로 먼저 충전해야 합니다. 잔액은 USD(미국 달러)로 표시되며, 위챗페이, 알리페이, Stripe(신용카드), USDT를 지원합니다 — 정확한 결제 수단과 금액 한도는 지갑 주문 페이지 기준입니다. 충전 후 7일 이내에 사용하지 않은 원금을 원래 결제 수단으로 환불 요청할 수 있으며, 이미 사용한 금액과 결제 처리 수수료는 환불되지 않습니다. 자세한 규칙은 [충전, 환불 및 인보이스](/ko/docs/billing/)을 참조하세요.
[콘솔](https://1zheai.com/console?lng=ko)로 이동해 왼쪽 사이드바의 "API 키"를 클릭한 뒤, 오른쪽 위의 "API 키 생성"을 클릭하고 이름을 붙여 저장하세요. API 키는 `sk-`로 시작합니다 — 목록에서 복사 아이콘을 클릭해 복사하고 보관하세요. 자세한 내용은 [API 키 발급 및 관리](/ko/docs/api-keys/)을 참조하세요.
API 키를 환경 변수에 넣은 다음, curl로 Anthropic 네이티브 엔드포인트를 한 번 호출합니다:
```bash title="macOS / Linux"
export ONEZHE_API_KEY="sk-你的Key"
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 128,
"messages": [{"role": "user", "content": "用一句话解释什么是 HTTP"}]
}'
```
```powershell title="Windows PowerShell"
$env:ONEZHE_API_KEY = "sk-你的Key"
$body = @{
model = "claude-sonnet-5-5"
max_tokens = 128
messages = @(@{ role = "user"; content = "用一句话解释什么是 HTTP" })
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "https://1zheai.com/v1/messages" -Method Post `
-Headers @{ "x-api-key" = $env:ONEZHE_API_KEY; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json; charset=utf-8" `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
```
`ONEZHE_API_KEY`은 예시 변수명일 뿐이며, 어떤 이름을 써도 됩니다.
성공하면 공식과 동일한 구조의 HTTP 200을 받습니다. 두 가지를 확인하세요. `model`이 요청한 모델인지, 그리고 `usage`의 토큰 수입니다. 아래는 2026-10-15에 측정한 실제 응답입니다:
```json
{
"model": "claude-sonnet-5-5",
"id": "msg_011Cg3G8HQmyTrnqSBX6o6Pw",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "HTTP(超文本传输协议)是一种基于请求-响应模式的应用层协议,用于在客户端(如浏览器)和服务器之间传输网页、图片、API 数据等内容。"
}
],
"container": null,
"stop_reason": "end_turn",
"stop_sequence": null,
"stop_details": null,
"usage": {
"input_tokens": 530,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 0,
"ephemeral_1h_input_tokens": 0
},
"output_tokens": 69,
"output_tokens_details": {"thinking_tokens": 0},
"service_tier": "standard",
"inference_geo": "global"
},
"input_transformations": [],
"diagnostics": null,
"context_management": {"applied_edits": []}
}
```
`input_tokens`은 질문 자체보다 수백 개 더 많습니다 — 이 유형의 클라이언트(curl, SDK, 서드파티 도구)가 모든 요청에 붙이는 시스템 프롬프트이며 입력으로 과금됩니다. Claude Code는 시스템 프롬프트를 붙이지 않으니 [시스템 프롬프트 과금](/ko/docs/pricing-explained/#section-3)을 참조하세요.
그다음 콘솔 왼쪽의 "호출 로그"로 이동하면 이 호출을 확인할 수 있습니다: 시각, 사용한 API 키("토큰" 열), 모델, 입력 / 출력 토큰, 캐시 읽기/쓰기, 비용.
## GPT로 시작할 수도 있습니다
OpenAI SDK를 쓰거나 Codex 연동을 계획한다면 GPT 프로토콜을 바로 선택할 수 있습니다. 먼저 같은 터미널에서 위의 `ONEZHE_API_KEY`을 설정한 다음 실행합니다:
```bash
curl --fail-with-body https://1zheai.com/v1/chat/completions \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"用一句话解释 HTTP。"}]}'
```
이것은 macOS / Linux 셸 예시입니다. Windows에서는 [크로스 플랫폼 Python / Node.js 예시](/ko/docs/code-examples/)를 바로 실행할 수 있습니다. 텍스트는 `choices[0].message.content`에 넣습니다. 모델이 목록에 없다면 먼저 [사용 가능한 모델 조회](/ko/docs/api-models/)을 하세요. Codex는 Responses를 요구합니다 — [Codex 구성 튜토리얼](/ko/docs/quickstart-codex/)을 따라 연동하세요.
## 다음 단계
자주 쓰는 도구에 연결하세요:
환경 변수 두 개면 충분합니다.
설정 파일을 직접 편집하고 싶지 않다면 이 방법을 쓰세요.
사용자 지정 Base URL 작성법과 그 제한 사항.
이미 OpenAI 코드가 있다면 base_url만 바꾸면 됩니다.
요청이 실패하면 먼저 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 확인하세요. 반환된 필드와 사용량을 검증하려면 [모델 및 사용량 검증](/ko/docs/verify-model/)을 참조하세요.
---
# API 키 발급 및 관리
Source: https://1zheai.com/ko/docs/api-keys/
Markdown: https://1zheai.com/ko/docs/api-keys.md
---
title: "API 키 발급 및 관리"
description: "1zheAI 콘솔에서 sk- 접두사 API 키를 생성하고, 저장·교체·유출 시 피해를 최소화하는 방법을 안내합니다."
headingIds: {"API 키 생성":"section-1","도구별 API 키 하나씩":"section-2","저장 위치":"section-3","유출되었을 때":"section-4","자주 묻는 질문":"section-5"}
---
API 키는 하나의 호출 권한 세트에 대응하며, 요금은 계정 잔액에서 차감됩니다. 이 페이지에서는 API 키 생성 방법, 저장 위치, 문제가 발생했을 때의 대처 방법을 설명합니다.
## API 키 생성
[1zheai.com/console](https://1zheai.com/console?lng=ko)을 엽니다.
왼쪽 사이드바 메뉴에서 "API Keys"를 클릭한 뒤, 오른쪽 위의 "Create API Key"를 클릭합니다. 용도가 드러나는 이름을 입력합니다. 예: `claude-code-macbook`, `ci-staging`. 다른 항목은 기본값으로 두어도 정상적으로 동작합니다. "Save Changes"를 클릭합니다.
양식에서 설정할 수 있는 항목:
| 양식 항목 | 기본값 | 설명 |
|---|---|---|
| 이름 | 비어 있음 | 호출 로그에서 API 키를 구분하는 데 사용 |
| 만료 | 만료 없음 | 1시간, 1일, 1개월 중에서 선택하거나 정확한 날짜와 시각을 지정 |
| 수량 | 1 | 한 번에 여러 개 생성; 이름에 무작위 접미사가 자동 추가됨 |
| "Unlimited Quota" 토글 | 켜짐 | 끄면 "Quota (USD)" 항목이 나타나며, 이 API 키는 최대 해당 USD만큼만 사용할 수 있음 |
| 모델 제한("Advanced Settings" 아래) | 비어 있음, 즉 모든 모델 허용 | 모델을 선택하면 이 API 키는 해당 모델만 호출할 수 있음 |
| IP 허용 목록("Advanced Settings" 아래) | 비어 있음, 즉 제한 없음 | 목록에 등록된 IP 또는 CIDR 범위에서의 호출만 허용 |
API 키는 `sk-`로 시작합니다. 복사한 뒤 비밀번호 관리자나 환경 변수에 넣고, 채팅·스크린샷·코드 저장소에 붙여넣지 마세요.
## 도구별 API 키 하나씩
도구별, 기계별로 API 키를 따로 만드는 것을 권장합니다. 세 가지 이점이 있습니다.
- 호출 로그가 API 키별로 분리되어, 어느 도구가 얼마를 썼는지 한눈에 파악할 수 있습니다.
- API 키 하나가 유출되면 해당 키만 삭제하면 되므로 다른 도구에 영향이 없습니다.
- 팀에서는 각자가 자신의 API 키를 책임지고, 구성원이 퇴사하거나 기계를 바꿀 때 해당 키를 삭제합니다.
## 저장 위치
```bash title="Shell 配置（macOS / Linux）"
# 写进 ~/.zshrc 或 ~/.bashrc，只在本机生效
export ONEZHE_API_KEY="sk-你的Key"
```
```powershell title="Windows（当前用户，持久）"
[Environment]::SetEnvironmentVariable("ONEZHE_API_KEY", "sk-你的Key", "User")
# 重新打开终端后生效
```
```bash title=".env（项目本地）"
# .env 要写进 .gitignore
ONEZHE_API_KEY=sk-你的Key
```
Claude Code의 프로젝트 수준 `.claude/settings.json`은 보통 저장소에 커밋되며, Claude Code 공식 문서는 여기에 자격 증명을 쓰지 말 것을 명시적으로 권고합니다. API 키는 사용자 수준의 `~/.claude/settings.json`에 넣거나, 커밋되지 않는 프로젝트 내 `.claude/settings.local.json`에 넣으세요.
## 유출되었을 때
1. "API Keys" 목록에서 해당 키를 찾아 "Actions" 열의 "Disable" 아이콘을 클릭하거나, "⋯" 메뉴에서 "Delete"를 선택합니다. 비활성화하면 즉시 적용되어, 이후 해당 키로의 호출은 401 `Invalid token`을 반환합니다.
2. 새 API 키를 생성하고, 이전 키를 사용하던 모든 곳에 교체합니다.
3. 호출 로그(콘솔 메뉴 "Call Logs")를 열고 "Expand"를 클릭한 뒤, "Token Name"에 이 API 키의 이름을 입력해 필터링하여 최근 호출 중 본인이 시작하지 않은 것이 있는지 확인합니다.
## 자주 묻는 질문
네, API 키는 도구에 종속되지 않습니다. 다만 섞어 쓰면 로그에서 누가 돈을 썼는지 불분명해지므로, 따로 만드는 것을 권장합니다.
대부분 그렇습니다. 흔한 원인은 다음과 같습니다. 키와 함께 공백이나 줄바꿈이 복사된 경우, API 키가 이미 삭제된 경우, 도구에서 잘못된 항목에 입력한 경우입니다. 단계별 점검 방법은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
기본적으로 만료되지 않습니다. 생성하거나 편집할 때 "Expiration"에 시각을 설정할 수 있으며, 만료 후에는 호출이 401 `Invalid token`을 반환합니다. 이는 API 키를 잘못 입력했을 때와 동일한 응답입니다. 목록의 "Expiration" 열에 각 API 키의 만료 시각이 표시됩니다.
---
# 지원되는 모델
Source: https://1zheai.com/ko/docs/models/
Markdown: https://1zheai.com/ko/docs/models.md
---
title: "지원되는 모델"
description: "Claude, GPT, MiMo 및 이미지 생성 모델의 가용 범위, 모델 ID, 인터페이스 및 가격을 조회합니다."
headingIds: {"모델 목록":"section-1","두 인터페이스 모두 호출 가능":"section-2","OpenAI / GPT 모델":"section-3","MiMo 모델":"section-4","인터페이스로 최신 목록 조회":"section-5","선택 방법":"section-6","자주 묻는 질문":"section-7","이미지 모델 및 인터페이스 조회":"section-8"}
---
Claude, GPT, MiMo 및 이미지 생성 모델이 출시되었습니다. 아래에 Claude와 GPT의 모델 ID를 나열하며, 전체 가용 범위는 모델 카탈로그와 인터페이스 응답을 기준으로 합니다.
[공개 모델 및 가격](https://1zheai.com/en/pricing/)에서 견적을 확인하세요. 로그인한 사용자는 [콘솔 · 모델](https://1zheai.com/model-catalog?lng=ko)에서 모델을 조회하고 연결 방법을 확인할 수 있습니다.
## 모델 목록
요청의 `model`는 아래 표의 ID와 완전히 일치해야 하며, 날짜 접미사도 포함합니다.
| 모델 ID | 시리즈 | 설명 |
|---|---|---|
| `claude-fable-5-1` | Fable 5.1 | |
| `claude-fable-5` | Fable 5 | |
| `claude-opus-5-5` | Opus 5.5 | |
| `claude-opus-5` | Opus 5 | |
| `claude-opus-4-8` | Opus 4.8 | |
| `claude-opus-4-7` | Opus 4.7 | |
| `claude-opus-4-6` | Opus 4.6 | |
| `claude-opus-4-5-20251101` | Opus 4.5 | 날짜가 포함된 고정 버전 ID |
| `claude-sonnet-5-5` | Sonnet 5.5 | |
| `claude-sonnet-5` | Sonnet 5 | |
| `claude-sonnet-4-6` | Sonnet 4.6 | |
| `claude-sonnet-4-5-20250929` | Sonnet 4.5 | 날짜가 포함된 고정 버전 ID |
| `claude-haiku-5-5` | Haiku 5.5 | |
| `claude-haiku-4-5-20251001` | Haiku 4.5 | 날짜가 포함된 고정 버전 ID |
각 모델의 단가(입력, 출력, 캐시 읽기, 캐시 쓰기)는 [가격 페이지](https://1zheai.com/en/pricing/)에서 확인하세요. 모델의 기능, 컨텍스트 길이 및 릴리스 노트는 [Anthropic 공식 모델 문서](https://platform.claude.com/docs/en/about-claude/models/overview)를 기준으로 합니다.
## 두 인터페이스 모두 호출 가능
위 표의 모델은 모두 Anthropic 네이티브 `/v1/messages` 및 OpenAI 호환 `/v1/chat/completions`으로 호출할 수 있으며, 모델 ID 작성 방식은 동일합니다. 캐시, thinking, 도구 호출 등 Claude 고유 파라미터가 필요하면 네이티브 인터페이스를 사용하세요. [Base URL 및 인증](/ko/docs/base-url/)을 참조하세요.
## OpenAI / GPT 모델
- `gpt-5.6-luna`
- `gpt-5.6-sol`
- `gpt-5.6-terra`
- `gpt-6-astra`
GPT는 [OpenAI SDK](/ko/docs/quickstart-openai-sdk/) 및 [Codex CLI](/ko/docs/quickstart-codex/)에서 사용할 수 있습니다. 모델별 인터페이스와 과금 방식은 [콘솔 모델 카탈로그](https://1zheai.com/model-catalog?lng=ko)를 기준으로 합니다.
## MiMo 모델
MiMo 텍스트 및 음성 모델의 ID, 지원 인터페이스 및 과금 단위는 [모델 및 가격](https://1zheai.com/en/pricing/)에서 확인하세요. 텍스트는 token 기준, 음성은 해당 모델의 과금 단위로 확인하며, Claude의 캐시 및 할인 규칙을 적용하지 마세요.
## 인터페이스로 최신 목록 조회
모델은 공식 출시에 따라 증감하므로 인터페이스 응답을 기준으로 합니다:
```bash title="用你的 Key 查"
curl https://1zheai.com/v1/models \
-H "Authorization: Bearer sk-你的Key"
```
```bash title="公开价格接口（不需要 Key）"
curl -s https://1zheai.com/api/pricing | jq -r '.data[].model_name'
```
## 선택 방법
어떤 것을 선택할지 모르겠다면 다음과 같이 시작할 수 있습니다:
| 시나리오 | 권장 |
|---|---|
| 일상적인 코딩, Claude Code 주력 | `claude-sonnet-5-5` |
| 복잡한 리팩터링, 어려운 문제 디버깅 | `claude-opus-5-5` |
| 하위 작업, 요약, 분류 등 가벼운 작업 | `claude-haiku-5-5` |
Claude Code에서 opus / sonnet / haiku 세 등급을 구체적인 모델에 어떻게 매핑하는지는 [Claude Code 연결](/ko/docs/quickstart-claude-code/)을 참조하세요.
## 자주 묻는 질문
먼저 ID 철자와 날짜 접미사를 확인한 다음, 위의 `/v1/models`으로 API 키(API key)가 이 모델을 볼 수 있는지 확인하세요. 다른 제공업체의 사용자 정의 모델명(예: 접두사나 접미사가 추가된 것)은 여기서 사용할 수 없습니다.
모델이 존재하지 않거나 현재 사용할 수 없을 때 게이트웨이는 HTTP 404를 반환합니다. Anthropic 네이티브 응답의 `error.type`은 `not_found_error`입니다. OpenAI 호환 응답의 `error.code`은 `model_not_found`입니다.
먼저 ID와 키의 사용 가능 모델 목록을 확인하고, 잘못된 ID를 반복해서 재시도하지 마세요. 모델이 존재하지만 일시적으로 건강한 업스트림 서비스가 없을 때만 503이 반환될 수 있습니다. [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
정상적인 경우 응답의 `model`은 요청한 ID입니다. 일치하지 않으면 요청 시간과 응답을 support@1zheai.com으로 보내거나 [모델 및 사용량 확인](/ko/docs/verify-model/)에 따라 절차를 수행할 수 있습니다.
## 이미지 모델 및 인터페이스 조회
공개 카탈로그에는 2026-10-16 기준 `gpt-image-1.5` 및 `chatgpt-image-latest`이 나열되어 있습니다. 자세한 내용은 [이미지 생성 연결](/ko/docs/api-images/)을 참조하세요. 실제 권한과 파라미터는 키와 모델 카탈로그를 기준으로 합니다.
모델 API의 전체 예제, 두 가지 응답 형식 및 목록이 비어 있을 때의 문제 해결 방법은 [사용 가능한 모델 API 조회](/ko/docs/api-models/)을 참조하세요.
---
# 다른 서비스에서 1折AI로 마이그레이션
Source: https://1zheai.com/ko/docs/migration/
Markdown: https://1zheai.com/ko/docs/migration.md
---
title: "다른 서비스에서 1折AI로 마이그레이션"
description: "주소, 키, 모델, 프로토콜, 기능을 항목별로 마이그레이션하며 원래 설정을 복구 가능한 상태로 보존합니다."
headingIds: {"네 가지 설정을 함께 확인":"section-1","순서대로 검증":"section-2","환경 변수의 적용 범위":"section-3","전환 실패 시 복구":"section-4"}
---
마이그레이션 전에 원래 설정을 저장하세요. 별도의 터미널이나 개발 환경에서 먼저 검증하고, 성공을 확인한 후에 자주 사용하는 도구나 운영 서비스를 변경하세요.
## 네 가지 설정을 함께 확인
| 설정 | 1折AI의 작성 방식 | 흔한 누락 |
| --- | --- | --- |
| OpenAI Base URL | `https://1zheai.com/v1` | `/chat/completions`을 과도하게 추가하거나 `/v1`을 누락 |
| Anthropic Base URL | `https://1zheai.com` | SDK가 `/v1`을 한 번 더 추가 |
| API 키 | 이 사이트 콘솔에서 생성한 키 | 이전 공급자의 키를 그대로 사용 |
| 모델 ID | 이 사이트의 `/v1/models`이 반환하는 전체 ID | `vendor/` 접두사나 사용자 지정 접미사가 붙은 이름을 그대로 사용 |
원본 HTTP 요청은 전체 엔드포인트 경로가 필요합니다. SDK와 데스크톱 도구는 일반적으로 Base URL만 요구합니다. [해당 도구 튜토리얼](/ko/docs/integrations/)을 기준으로 합니다.
## 순서대로 검증
[모델 조회 인터페이스](/ko/docs/api-models/)에 따라 한 번 호출합니다. 실패하면 주소, 자격 증명 또는 접근 조건을 먼저 수정하고, 여러 비즈니스 파라미터를 동시에 조정하지 마세요.
[Chat Completions](/ko/docs/api-chat-completions/), [Responses](/ko/docs/api-responses/) 또는 [Messages](/ko/docs/api-messages/) 중에서 선택합니다. 기존 클라이언트에 필요한 프로토콜을 유지하고, 선택적 파라미터를 먼저 제거합니다.
스트리밍, 다중 턴 대화 기록, 도구 호출 및 필요한 기타 기능을 차례로 검증합니다. 한 번에 하나씩 추가하고 비교 가능한 오류 응답을 보존하세요. 일반 텍스트가 성공한다고 해서 Agent의 파일, 검색 및 보조 모델이 모두 호환된다는 의미는 아닙니다.
[호출 로그](/ko/docs/usage-logs/)에서 요청 시간과 모델을 확인합니다. 설정을 다시 불러와야 하는 터미널, IDE 또는 백그라운드 서비스를 재시작하여 이전 환경 변수를 계속 사용하지 않도록 합니다.
## 환경 변수의 적용 범위
터미널의 `export`은 현재 셸과 이후에 시작된 하위 프로세스에만 영향을 줍니다. 데스크톱 애플리케이션, 컨테이너, 예약 작업 및 시스템 서비스는 다른 환경을 사용할 수 있습니다. 실제 프로그램이 실행되는 곳에서 자격 증명을 구성하세요.
설정 파일의 동일한 이름의 필드도 환경 변수를 덮어쓸 수 있습니다. Claude Code, Codex 등의 도구는 각각의 튜토리얼을 참고하고, 모든 공급자 변수를 전역 셸 설정에 한꺼번에 쌓지 마세요.
## 전환 실패 시 복구
이전에 저장한 공급자, 주소 및 모델 설정을 복원하고 클라이언트를 다시 시작하세요. 운영 업무를 마이그레이션하는 경우 먼저 소량의 요청으로 검증한 후 범위를 확대하고, 애플리케이션 레벨의 설정 전환 방식을 유지하여 서비스를 복구하기 쉽게 하세요.
기능이 열려 있는지 확실하지 않으면 모델 카탈로그에서 확인하거나 지원팀에 문의하세요. 다른 플랫폼이 Embeddings, Batch 또는 특정 독점 이미지 모델을 제공한다고 해서 이 사이트도 동일한 서비스를 제공한다고 가정하지 마세요.
---
# API 접속 자주 묻는 질문
Source: https://1zheai.com/ko/docs/faq/
Markdown: https://1zheai.com/ko/docs/faq.md
---
title: "API 접속 자주 묻는 질문"
description: "Base URL, 모델, 스트리밍, 클라이언트, 타임아웃 및 가용성 모니터링에 대한 자주 묻는 질문을 빠르게 찾아보세요."
headingIds: {"주소, 키 및 모델":"section-1","요청 및 클라이언트":"section-2","서비스 상태 및 도움말":"section-3"}
---
## 주소, 키 및 모델
OpenAI SDK에는 `https://1zheai.com/v1`을(를) 입력하고, Anthropic SDK와 Claude Code에는 `https://1zheai.com`을(를) 입력합니다. curl을 직접 사용할 때는 전체 요청 경로를 입력합니다. 일부 데스크톱 도구는 경로를 자동으로 완성하므로 [주소 대조표](/ko/docs/base-url/)을(를) 참조하세요.
필요합니다. 본 사이트 접속에는 본 사이트 콘솔에서 생성한 API 키를 사용해야 하며, 소비자용 클라이언트의 구독은 본 사이트 API 자격 증명과는 별개의 접속 방식입니다. 도구도 사용자 지정 공급자 또는 API 주소를 지원해야 합니다.
목록에 표시되는 것은 현재 키로 볼 수 있는 모델이며, 실시간 추론 성공률이 아닙니다. 인터페이스 프로토콜, 선택적 파라미터 및 업스트림 상태도 함께 확인해야 합니다. [모델 조회 인터페이스](/ko/docs/api-models/)을(를) 참조하세요.
본 사이트 모델 목록에서 전체 ID를 복사하세요. 공급자에 따라 접두사, 별칭 및 날짜 버전이 다를 수 있으므로 추측으로 이름을 바꾸지 마세요. 마이그레이션 단계는 [마이그레이션 가이드](/ko/docs/migration/)을(를) 참조하세요.
## 요청 및 클라이언트
먼저 응답 프로토콜을 확인하세요. Chat Completions는 `choices[].message.content`을(를) 읽고, Messages는 `content` 텍스트 블록을 순회하며, Responses는 `output`을(를) 순회하거나 SDK의 `output_text`을(를) 사용합니다. 도구 호출 응답에는 일반 텍스트가 없을 수도 있습니다.
다중 대화는 클라이언트가 히스토리를 전달해야 합니다. 동일한 키를 반복 사용해도 서버 측 세션이 자동으로 생성되지 않습니다. Responses의 세션 관련 확장은 별도로 지원 여부를 확인해야 하며, 기본적으로 의존하지 마세요.
종료 이벤트 또는 최종 상태도 확인해야 합니다. 중간 오류, 스트림 끊김 및 출력 잘림은 일부 텍스트를 이미 수신한 후에도 발생할 수 있습니다. 자세한 내용은 [스트리밍 출력](/ko/docs/streaming/)을(를) 참조하세요.
권장하지 않습니다. 타임아웃은 요청이 이미 처리된 후에도 발생할 수 있습니다. 먼저 호출 로그를 확인한 다음, 제한된 횟수, 백오프 및 총 대기 시간에 따라 재시도를 실행하세요. SDK와 애플리케이션이 각각 한 번씩 재시도하지 않도록 주의하세요. [타임아웃 및 재시도](/ko/docs/retries/)을(를) 참조하세요.
키를 브라우저 스크립트나 공개 저장소에 컴파일하지 마세요. 서버가 자격 증명을 보유하고 인터페이스를 호출하게 하고, 브라우저는 자신의 백엔드에만 연결해야 합니다. 데모 코드의 환경 변수는 서버 또는 로컬 터미널용입니다.
## 서비스 상태 및 도움말
모니터링은 공식 웹사이트, 콘솔 및 API 진입점의 HTTP 접근성을 확인하며, 각 모델의 추론 성공률을 의미하지는 않습니다. 모니터링은 애플리케이션과 동일한 서버에 배포되므로 서버 전체 장애 시 모니터링도 중단됩니다. 이력 데이터는 활성화 후부터 누적됩니다.
발생 시각과 시간대, 클라이언트 버전, 모델 ID, 전체 요청 경로, HTTP 상태 코드, 요청 ID 및 마스킹된 오류 정보를 제공하세요. 키, 인증 헤더 및 개인 대화 내용은 삭제하세요. [디버깅 템플릿](/ko/docs/troubleshooting/)에 따라 정리할 수 있습니다.
---
# 스토어 구매 가이드
Source: https://1zheai.com/ko/docs/store-guide/
Markdown: https://1zheai.com/ko/docs/store-guide.md
---
title: "스토어 구매 가이드"
description: "바로 사용할 수 있는 계정, 구독 대행 충전 및 기프트카드의 차이를 이해하고, 상품 안내에 따라 주문하고 배송을 추적합니다."
headingIds: {"주문 전 확인 사항":"section-1","주문 및 배송":"section-2","구매 전 반드시 알아야 할 사항":"section-3","친구 초대 구매":"section-4"}
---
스토어에서 AI 계정, 구독 서비스 또는 기프트 카드를 선택하고 상품 설명을 확인한 후 주문하세요.
| 무엇이 필요하신가요 | 선택할 서비스 | 어디에서 확인하나요 |
| --- | --- | --- |
| 코드나 도구에서 모델 호출 | 모델 API | [API 빠른 시작](/ko/docs/quickstart/) |
| 이미 존재하는 제3자 계정 구매 | 바로 사용할 수 있는 계정 | [바로 사용할 수 있는 계정 구매 및 사용](/ko/docs/account-guide/) |
| 본인의 제3자 계정에 멤버십 개통 | 구독 대행 충전 | [대행 조건 및 절차](/ko/docs/subscription-guide/) |
| 교환 코드 또는 교환 링크 획득 | 기프트카드 | [교환 및 사용 안내](/ko/docs/gift-card-guide/) |
이 사이트의 API 키로는 ChatGPT, Claude, Grok에 로그인할 수 없으며, 제3자 플랫폼 멤버십을 구매한다고 해서 이 사이트의 API 잔액 충전이 되는 것도 아닙니다.
## 주문 전 확인 사항
상품명, 사양, 지역, 구독 기간, 현재 재고, 배송 방식, 구매 안내를 확인하세요. 카탈로그에 표시되지 않았거나 구매할 수 없는 사양은 아직 개방되지 않은 것이므로, 데모 페이지나 다른 판매자의 절차에 따라 결제하지 마세요.
상품이 갱신, 이메일 변경, 다중 사용 또는 특정 클라이언트를 지원하는지는 선택한 상품 설명을 기준으로 합니다. 명확히 설명되어 있지 않으면 먼저 지원팀에 연락해 확인하세요. 이러한 기능이 기본 포함된다고 가정하지 않습니다.
## 주문 및 배송
1. [온라인 스토어](https://1zheai.com/en/store/)에서 상품과 사양을 선택합니다.
2. 로그인 후 결제 금액, 수량, 구매 안내를 확인합니다. 대행 충전 상품은 추가로 양식에 필요한 정보를 입력해야 합니다.
3. 위험 및 애프터서비스 규칙을 읽고 동의에 체크한 후 주문합니다. 주문은 이 사이트 지갑 잔액으로 결제됩니다.
4. [내 주문](https://1zheai.com/store-orders?lng=ko)에서 상태, 배송 내용 또는 추가로 필요한 정보를 확인합니다. 잔액 충전이 성공했다고 해서 상품이 구매되었거나 대행 충전이 완료된 것은 아닙니다.
재고가 있는 자동 배송 상품, 수동 배송 상품, 주문 후 개통되는 대행 충전은 처리 방식이 다릅니다. 즉시 도착이나 고정 완료 기한을 일괄적으로 약속하지 않으며, 결제 페이지 및 주문 화면에 표시된 내용을 기준으로 합니다.
## 구매 전 반드시 알아야 할 사항
바로 사용할 수 있는 계정이 정상적으로 배송되었거나 대행 충전이 성공한 후 계정이 제3자 플랫폼에서 차단된 경우, 차단을 이유로 환불하지 않습니다. 이의 제기를 도와드릴 수는 있으나 해제 결과를 약속하지 않습니다. 약속대로 배송되지 않았거나 대행 충전이 성공하지 않은 경우, 또는 법에 따라 이 사이트가 책임을 져야 하는 경우는 해당 애프터서비스 규칙에 따라 처리합니다.
[거래 및 애프터서비스 규칙](/ko/docs/store-rules/) · [주문 문제 해결](/ko/docs/store-orders/)
## 친구 초대 구매
스토어 상품은 사양에 따라 수수료 환급에 참여할 수 있습니다. 참여 범위, 귀속 및 정산 조건은 [초대 보상 및 스토어 수수료 환급](/ko/docs/affiliate-guide/)을 참조하세요.
---
# 준비 완료 계정의 구매 및 사용
Source: https://1zheai.com/ko/docs/account-guide/
Markdown: https://1zheai.com/ko/docs/account-guide.md
---
title: "준비 완료 계정의 구매 및 사용"
description: "준비 완료 ChatGPT, Claude, Grok 계정을 구매하기 전에 확인할 사양, 배송 내용, 첫 로그인, 차단 위험."
headingIds: {"구매 전 확인 사항":"section-1","계정 수령 후":"section-2","일상 사용과 갱신":"section-3","차단과 애프터서비스":"section-4"}
---
준비 완료 계정은 선택한 상품 목록에 명시된 대로 제3자 플랫폼 계정을 배송합니다. 구독이 포함되는지, 구독 등급, 남은 기간은 모두 해당 상품과 주문에 따라 결정되므로 플랫폼 이름만 보고 판단하지 마세요.
## 구매 전 확인 사항
- 구독이 포함되는지, 구독 등급(예: Pro, Max)과 기간; 표시되지 않은 사양은 판매되지 않습니다.
- 지역, 로그인 방법, 배송 내용; 이메일 접근, 인증 코드 수신, 이메일 변경 기능이 제공되는지 여부.
- 일회성 배송인지 별도의 갱신 조치가 있는지; 자동 갱신, 이메일 전달, 갱신 알림이 포함된다고 가정하지 마세요.
- 팀, 공유, 양도 사용이 허용되는지, 그리고 제3자 플랫폼 자체의 약관과 지역 제한.
## 계정 수령 후
1. [내 주문 ](https://1zheai.com/store-orders?lng=ko)에서 상품, 사양, 배송 정보를 확인하고 주문 번호를 안전하게 보관하세요.
2. 해당 상품의 로그인 안내에 따라 해당 플랫폼에 접속하여 계정이 로그인되는지, 구독 등급, 유효 기간을 확인하세요.
3. 상품이 허용하는 방식으로 비밀번호, 복구 정보, 보안 인증을 변경하세요; 변경할 수 없는 항목은 먼저 고객 지원에 문의하여 확인하세요.
4. 배송된 정보가 유효하지 않거나, 사양이 일치하지 않거나, 로그인에 실패하면 마스킹된 스크린샷과 오류 메시지를 보관하고 공식 웹사이트의 지원 채널을 통해 상황을 설명하세요. 계정 비밀번호, 인증 코드, 복구 코드를 공개적으로 공유하지 마세요.
## 일상 사용과 갱신
플랫폼의 이용 약관을 준수하세요. 계정은 지역, 사용량, 본인 확인, 리스크 관리 제한을 받을 수 있으며, 구매에는 제한 우회, 본인 확인 대행, 영구 차단 방지에 대한 어떠한 보증도 포함되지 않습니다. 본인 확인은 플랫폼의 요구에 따라 실제 사용자가 완료해야 하며, 별도의 명시적이고 필요한 정당한 절차가 없는 한 고객 지원에 신분증 서류나 인증 코드를 보내지 마세요.
갱신이 필요할 때는 먼저 현재 상품이 지원하는 방법을 확인하세요; 본인 계정용 충전을 준비 완료 계정에 직접 적용하지 마세요, 호환되지 않는 구독을 스스로 중첩하지 마세요.
## 차단과 애프터서비스
준비 완료 계정이 정상적으로 배송되었거나 충전이 성공한 후, 제3자 플랫폼에 의해 계정이 차단되면 차단을 이유로 환불되지 않습니다. 이의 제기를 도와드릴 수 있지만, 차단 해제 결과를 약속하지 않습니다. 약속대로 배송되지 않은 경우, 실패한 충전, 또는 법률상 본 사이트가 책임을 져야 하는 상황은 해당 애프터서비스 규칙에 따라 처리됩니다.
[상세 거래 규칙 ](/ko/docs/store-rules/) · [주문 문제 해결 ](/ko/docs/store-orders/)
---
# 구독 충전 조건 및 절차
Source: https://1zheai.com/ko/docs/subscription-guide/
Markdown: https://1zheai.com/ko/docs/subscription-guide.md
---
title: "구독 충전 조건 및 절차"
description: "본인 계정으로 충전하기 전에 자격 요건, 필요 정보, 보안 유의사항, 주문 처리 방식을 확인하세요."
headingIds: {"계정 조건 먼저 확인하기":"section-1","주문 절차":"section-2","정보 보안":"section-3","처리, 실패 및 환불":"section-4"}
---
구독 충전은 기존의 제3자 플랫폼 계정에 선택한 멤버십을 활성화하는 방식이며, 새 계정은 제공되지 않습니다. 상품의 판매 여부와 지원되는 플랫폼 및 등급은 [스토어](https://1zheai.com/en/store/)에 현재 표시된 내용을 따릅니다. 본 문서는 모든 플랫폼이나 사양이 개방되어 있음을 의미하지 않습니다.
## 계정 조건 먼저 확인하기
선택한 상품이 요구하는 지역, 계정 유형, 현재 구독 상태, 미결제 잔액, 환불 이력, 갱신 제한 사항을 검토하세요. 조건은 채널에 따라 다를 수 있으며, 모든 계정을 무료(Free)로 요구하지 않고, 기존 구독의 적립, 업그레이드, 연장이 가능하다는 것을 일괄적으로 보장하지도 않습니다.
기존 구독, 미결제 잔액, 플랫폼 제한이 있거나 계정 자격 요건이 불확실한 경우 먼저 고객 지원에 문의하세요. 주문을 반복해 시도하지 말고, 다른 판매자의 운영 안내로 본 사이트의 상품 안내를 대체하지 마세요.
## 주문 절차
1. 구체적인 사양을 선택하고 가격, 기간, 적용 대상 계정, 활성화 방식을 확인합니다.
2. 해당 사양이 요구하는 정보를 본 사이트의 결제 폼에 입력합니다(예: 계정 식별자 또는 Organization ID). 항목은 상품에 따라 다릅니다.
3. 대상 계정과 정보를 검증하고, 위험 고지를 읽은 뒤 주문을 제출합니다.
4. [내 주문](https://1zheai.com/store-orders?lng=ko)에서 처리 진행 상황을 확인합니다. 원래 주문에서 수정 가능하다고 표시된 경우에만 정보를 업재정하고, 재구매하지 마세요.
5. 주문이 완료로 표시되면 제3자 플랫폼에 로그인하여 멤버십 등급과 유효 기간을 확인합니다. 아직 갱신되지 않은 것으로 표시되면 새로고침하거나 다시 로그인한 뒤 재확인하고, 계속 불일치하면 고객 지원에 문의하세요.
## 정보 보안
일부 사양은 Session JSON과 같은 로그인 세션 정보를 요구할 수 있습니다. 이 유형의 정보는 계정에 접근할 수 있게 하므로 비밀번호만큼 민감합니다. 본 사이트의 해당 주문 전용 폼을 통해서만 제출하고, 온라인 채팅, 이메일, 공개 스크린샷, 제3자 계조 조회 웹사이트로 보내지 마세요. 권한 범위와 상품 요구사항을 이해하고 수락한 뒤에만 제출하며, 수락할 수 없다면 해당 사양을 구매하지 마세요.
일반 고객 지원 메시지로 비밀번호, 인증 코드, API 키, 전체 로그인 세션을 보내지 마세요. 처리가 완료된 후에는 제3자 플랫폼이 제공하는 방법으로 로그인 기기와 세션을 확인하고 관리하세요.
## 처리, 실패 및 환불
처리는 결제 후 시작되며, 처리 단계에 들어가면 직접 취소할 수 없습니다. 시간 초과나 실패 안내가 환불을 의미하지 않으며, 활성화가 이루어지지 않았음을 반드시 의미하지도 않습니다. 원래 주문을 보관하고 상태 업데이트를 기다리거나 고객 지원에 문의해 확인하며, 중복 결제나 중복 활성화를 피하세요. 환불 결과와 수령처는 본 사이트의 주문 및 지갑 기록을 따르며, 환불이 항상 원래 결제 수단으로 반환된다고 보장하지 않습니다.
완성된 계정이 정상적으로 제공되었거나 충전이 성공한 뒤 계정이 제3자 플랫폼에 의해 차단되면, 차단을 사유로 한 환불은 이루어지지 않습니다. 이의 제기를 지원할 수는 있지만, 차단 해제 결과를 보장하지는 않습니다. 합의대로 제공되지 않은 경우, 충전이 실패한 경우, 또는 법에 따라 본 사이트가 책임을 져야 하는 상황은 해당 애프터세일즈 규칙에 따라 처리됩니다.
[거래 및 애프터세일즈 규칙](/ko/docs/store-rules/) · [주문 문제 해결](/ko/docs/store-orders/)
---
# 기프트카드 사용 안내
Source: https://1zheai.com/ko/docs/gift-card-guide/
Markdown: https://1zheai.com/ko/docs/gift-card-guide.md
---
title: "기프트카드 사용 안내"
description: "구매 및 사용 전에 지역, 유효기간, 사용 가능 계정, 카드 전달 규칙을 확인하세요."
headingIds: {"구매 전 확인 사항":"section-1","수령 후 사용 방법":"section-2","취소 및 애프터세일즈":"section-3"}
---
기프트카드는 사용 코드 또는 사용 링크로 전달되며, 구독 충전은 주문 절차를 통해 직접 활성화될 수도 있습니다. 이는 서로 다른 두 가지 전달 방식입니다 — 모든 충전을 카드 코드를 받아 외부 사이트에서 사용하는 방식으로 이해해서는 안 됩니다.
## 구매 전 확인 사항
제품에 표시된 플랫폼, 지역, 통화 또는 액면가, 구독 등급, 유효기간, 사용 가능 계정 조건을 확인하세요. 기존 구독, 모바일 구독, 중복 사용, 선물이 지원되는지는 제품 설명에서 항목별로 검토해야 합니다. 다른 판매자의 유효기간이나 사용 조건을 이 사이트의 약속으로 간주하지 마세요.
스토어에 구매 가능한 기프트카드가 없을 때는 현재 구매가 개방되지 않았다는 의미입니다. 플랫폼 규칙이나 공급 상태가 변경되면 실제 제품 표시가 우선합니다.
## 수령 후 사용 방법
1. [내 주문 ](https://1zheai.com/store-orders?lng=ko)에서 전달된 내용을 확인하고, 사용 코드나 이를 포함한 스크린샷을 공개적으로 공유하지 마세요.
2. 올바른 대상 계정에 로그인했는지 확인한 후, 제품 설명에 따라 지정된 사용 진입점으로 이동하세요. 추가 이체나 비밀번호를 요구하는 낯선 사이트를 주의하세요.
3. 사용 전에 지역과 계정 상태를 다시 확인하고, 사용 후 실제 적립된 혜택을 검증하세요.
4. 이미 사용된 코드, 무효 코드, 지역 불일치, 혜택 미적립 등을 겪으면 주문 번호, 오류 내용, 마스킹된 스크린샷을 보관하고 지원팀에 문의하세요. 문제 해결을 위해 재구매하지 마세요.
## 취소 및 애프터세일즈
아직 처리가 시작되지 않은 주문은 주문과 함께 제공된 진입점을 통해 취소할 수 있으며, 사용 코드가 전달된 후에는 직접 환불이 지원되지 않습니다. 문제가 있을 경우 검증을 위해 지원팀에 문의하세요. 합의대로 전달되지 않은 경우, 잘못된 전달, 또는 이 사이트가 법적 책임을 지는 상황은 해당 애프터세일즈 규칙에 따라 처리됩니다. 기프트카드 금지, 사용 제한, 환불 조건은 해당 제품의 구체적 공지에 따르며, API 잔액 환불 규칙은 적용되지 않습니다.
[거래 및 애프터세일즈 규칙 ](/ko/docs/store-rules/) · [주문 문제 해결 ](/ko/docs/store-orders/)
---
# 주문 상태 및 문제 해결
Source: https://1zheai.com/ko/docs/store-orders/
Markdown: https://1zheai.com/ko/docs/store-orders.md
---
title: "주문 상태 및 문제 해결"
description: "배송 내용, 처리 진행 상황, 데이터 수정 및 환불 기록을 확인하고 중복 주문을 방지합니다."
headingIds: {"상태 설명":"section-1","자주 발생하는 문제":"section-2","결제는 되었지만 계정이나 멤버십이 오지 않음":"section-3","데이터를 잘못 입력함":"section-4","주문은 완료로 표시되지만 플랫폼에 아직 멤버십이 없음":"section-5","계정이 차단되었거나 본인 인증이 필요함":"section-6","환불이 어디에 있나요":"section-7","고객 지원에 문의할 때 제공할 것":"section-8"}
---
[내 주문 ](https://1zheai.com/store-orders?lng=ko)에서 해당 주문을 선택하세요. 구매 기록, 배송 내용 및 처리 진행 상황은 해당 주문을 기준으로 하며, 잔액 충전 기록은 상품 주문이 아닙니다.
## 상태 설명
| 상태 | 의미 | 다음 단계 |
| --- | --- | --- |
| 배송 대기 | 주문이 생성되었지만 배송이 완료되지 않음 | 배송 방법과 주문 메모를 확인하세요. 취소 항목이 제공된 경우 취소를 신청할 수 있습니다 |
| 처리 중 | 수동 처리가 진행 중이거나 파트너 채널을 통한 개통이 진행 중임 | 기존 주문을 유지하고 재구매하지 마세요. 안내에 따라 데이터를 보완하거나 수정하세요 |
| 배송 완료 | 배송 내용 또는 개통 결과가 제공됨 | 완제품 계정의 경우 로그인 및 사양을 확인하세요. 프록시 충전의 경우 멤버십을 확인하세요. 기프트카드의 경우 안내에 따라 사용하세요 |
| 취소됨 | 원래 주문이 종료됨 | 취소 사유와 지갑 거래 기록을 확인하세요. 환불 여부는 실제 기록을 따릅니다 |
프록시 충전의 상세 진행 상황은 공급 대기, 개통 대기, 데이터 수정 필요, 환불 진행 중 등을 나타낼 수 있습니다. 이러한 진행 상태는 최종 완료 상태와 다르므로, 단일 오류 메시지로 개통 또는 환불 결과를 판단하지 마세요.
## 자주 발생하는 문제
### 결제는 되었지만 계정이나 멤버십이 오지 않음
먼저 주문 상세 정보를 열어 상태와 배송 내용을 확인하세요. 수동 배송 및 프록시 충전은 즉시 완료되지 않을 수 있습니다. 상품 설명에 명시된 기한을 초과했거나, 상태가 오랫동안 업데이트되지 않거나, 이상이 표시되는 경우 고객 지원에 문의하고 중복 결제하지 마세요.
### 데이터를 잘못 입력함
원래 주문에 수정 항목이 표시될 때만 업데이트하고, 대상 계정을 확인한 후 제출하세요. 항목이 없거나 주문이 이미 배송된 경우 먼저 고객 지원에 문의하세요. 이미 개통된 구독의 이전은 보장하지 않습니다.
### 주문은 완료로 표시되지만 플랫폼에 아직 멤버십이 없음
제출한 대상 계정에 로그인되어 있는지 확인하고, 새로고침하거나 다시 로그인하여 구독 설정을 확인하세요. 여전히 일치하지 않으면 마스킹된 스크린샷과 주문 번호를 보관하고 고객 지원에 문의하세요. 직접 다른 구매를 하지 마세요.
### 계정이 차단되었거나 본인 인증이 필요함
제3자 플랫폼의 공식 채널을 통해 이의 제기 또는 인증을 진행하세요. 정상적인 배송 또는 성공적인 프록시 충전 후에는 계정 차단으로 인한 환불은 이루어지지 않습니다. 이의 제기를 지원할 수 있지만 차단 해제는 보장하지 않습니다. 약속대로 배송되지 않는 등의 이상 상황은 [A/S 규정 ](/ko/docs/store-rules/)에 따라 별도로 처리됩니다.
### 환불이 어디에 있나요
주문 취소 사유와 지갑 거래 기록을 확인하세요. 지갑 잔액으로 반환되는 것과 원래 결제 수단으로의 환불은 다릅니다. 진행 중으로 표시된 환불은 아직 완료되지 않았으므로 동일한 요청을 다시 제출하지 마세요.
### 고객 지원에 문의할 때 제공할 것
주문 번호, 상품 및 사양, 발생 시간 및 시간대, 주문 상태, 마스킹된 오류 정보. 비밀번호, 인증 코드, 전체 Session JSON, 교환 코드 또는 API 키는 보내지 마세요.
---
# 스토어 거래 및 애프터세일즈 규칙
Source: https://1zheai.com/ko/docs/store-rules/
Markdown: https://1zheai.com/ko/docs/store-rules.md
---
title: "스토어 거래 및 애프터세일즈 규칙"
description: "취소, 배송 이상, 활성화 실패, 계정 밴은 주문 단계별로 처리되며, 모델 API 잔액은 충전 규칙에 따라 별도로 처리됩니다."
headingIds: {"주문 전 확인 사항":"section-1","취소 및 환불은 주문 단계별로 처리됩니다":"section-2","밴 위험은 별도로 이해해야 합니다":"section-3","API 잔액 환불과의 차이":"section-4","애프터세일즈 서비스가 필요할 때":"section-5"}
---
## 주문 전 확인 사항
가격, 사양, 수량, 지역, 기간, 배송 방법, 위험 고지 사항은 상품 페이지 또는 결제 페이지에 표시됩니다. 확인 전에 반드시 모두 읽어 주세요. 조건이 불분명하면 먼저 고객 지원에 문의하세요. 주문은 주문 시점에 확인한 상품 및 위험 고지 사항을 유지하며, 이후 페이지 업데이트가 과거 주문의 확인 기록을 다시 쓰지 않습니다.
이 사이트는 상품 구매 및 애프터세일즈 서비스 요청을 위한 진입점입니다. 공급 파트너가 관여되는 경우, 이 사이트가 주문 기준으로 검증을 처리합니다. 낯선 상위 공급자에게 별도로 결제하지 마시고, 유통 계정을 직접 등록할 필요도 없습니다.
## 취소 및 환불은 주문 단계별로 처리됩니다
| 상황 | 처리 방법 |
| --- | --- |
| 배송 대기 상태이며 주문에 취소 항목이 제공되는 경우 | 원래 주문에서 취소를 요청할 수 있습니다. 성공 후 지갑 환불 거래 기록을 확인하세요 |
| 처리 진행 중이거나 활성화 결과 확인 대기 중 | 직접 취소할 수 없습니다. 원래 주문을 유지하고 검증을 기다리며, 재구매하지 마세요 |
| 로그인 불가, 무효 배송, 또는 사양 불일치 | 주문 번호와 마스킹된 증빙을 제공하세요. 지원팀이 배송 상태를 검증합니다 |
| 충전 실패 또는 정보 오류 | 원래 주문에서 안내에 따라 수정하거나 지원팀에 문의하세요. 실패 안내가 환불이 이미 발행되었음을 의미하지는 않습니다 |
| 사용 준비 완료 계정이 정상적으로 배송되었거나 충전이 성공한 후, 제3자 플랫폼에 의해 밴된 경우 | 밴으로 인한 환불은 없습니다. 이의 제기를 지원할 수 있지만, 밴 해제를 보장하지는 않습니다 |
| 기프트 카드가 배송된 경우 | 직접 환불은 지원하지 않습니다. 무효 배송과 같은 이상은 여전히 지원팀에 문의하여 검증할 수 있습니다 |
## 밴 위험은 별도로 이해해야 합니다
사용 준비 완료 계정이 정상적으로 배송되었거나 충전이 성공한 후, 계정이 제3자 플랫폼에 의해 밴된 경우, 밴으로 인한 환불은 없습니다. 이의 제기를 지원할 수 있지만, 밴 해제 결과를 보장하지는 않습니다. 합의대로 배송되지 않은 경우, 충전이 성공하지 않은 경우, 또는 이 사이트가 법적 책임을 져야 하는 상황은 해당 애프터세일즈 규칙에 따라 처리됩니다.
제3자 플랫폼은 약관을 조정하거나, 접근을 제한하거나, 신원 확인을 요구할 수 있습니다. 이 사이트는 리스크 관리가 발생하지 않거나, 밴이 발생하지 않거나, 이의 제기가 반드시 통과될 것을 보장할 수 없습니다. 정상 배송 후 밴을 합의대로 배송되지 않은 경우나 활성화 실패와 혼동하지 마세요. 위 설명은 법적 조항에 따라 이 사이트가 부담해야 할 책임을 배제하지 않습니다.
## API 잔액 환불과의 차이
모델 API의 미사용 원금 환불은 [충전, 환불 및 인보이스](/ko/docs/billing/)에 따라 처리됩니다. 스토어 상품의 취소 가능 여부와 환불 지급 방식은 주문 단계 및 해당 상품 규칙을 따르며, API 잔액의 7일 규칙은 직접 적용되지 않습니다. 주문을 취소하여 자금을 지갑으로 반환하는 것과 지갑 충전을 원래 결제 수단으로 환불하는 것은 서로 다른 작업입니다.
## 애프터세일즈 서비스가 필요할 때
[내 주문](https://1zheai.com/store-orders?lng=ko)에서 주문 번호를 보관하고, 상품 사양, 발생 시점, 주문 상태, 제3자 플랫폼에 표시된 상태, 마스킹된 오류 스크린샷을 제공하세요. 공식 웹사이트 또는 콘솔에 게시된 지원 채널을 통해 문의하세요. 비밀번호, 인증 코드, 전체 세션, 교환 코드, 신분증 원본 이미지는 제공하지 마세요. 특정 문제를 어떻게 찾는지는 [주문 문제 해결](/ko/docs/store-orders/)을 참조하세요.
---
# 초대 보상과 쇼핑몰 커미션
Source: https://1zheai.com/ko/docs/affiliate-guide/
Markdown: https://1zheai.com/ko/docs/affiliate-guide.md
---
title: "초대 보상과 쇼핑몰 커미션"
description: "초대 귀속, 참여 상품, 정산 조건, 쇼핑몰 커미션의 상태에 대해 알아봅니다."
headingIds: {"참여 방법":"section-1","어떤 주문이 커미션을 생성하나":"section-2","언제 정산되나":"section-3","어디서 확인하나":"section-4"}
---
조건을 충족하는 스토어 주문은 추천 보상의 대상이 될 수 있습니다. 계정, 구독 활성화, 기프트 카드 상품의 참여 여부는 관리자가 상품별로 설정하며 모든 상품에 자동으로 수수료가 발생하지는 않습니다.
## 참여 방법
콘솔의 초대 항목에서 본인의 가입 링크를 복사합니다[지갑](https://1zheai.com/wallet?lng=ko). 친구가 해당 링크를 통해 가입을 완료하면 시스템에 기록된 초대 관계가 이어집니다. 친구가 주문하면 그에 따라 커미션 귀속이 결정되며, 이후 다른 사람의 링크를 클릭해도 변경되지 않고, 주문 양식을 통해 초대자 ID가 제출되지 않습니다.
이미 초대 관계가 설정된 친구의 경우, 기능 활성화 후 커미션 참여 상품을 구매한 것도 새 주문 규칙에 따라 처리됩니다. 기능 활성화 이전에 배치된 과거 주문은 소급하여 쇼핑몰 커미션을 받지 않습니다. 본인의 구매는 본인의 초대 커미션으로 계산되지 않습니다.
## 어떤 주문이 커미션을 생성하나
관리자는 상품 사양별로 고정 커미션을 설정하며, 0을 입력하면 참여하지 않는 것입니다. 실제 커미션이 아직 설정되지 않은 사양은 보상을 지급하지 않습니다. 주문 시점에 초대자, 상품, 수량, 그 시점의 커미션 금액이 기록되며, 이후 상품 가격이나 커미션을 조정해도 이미 배치된 주문의 기록은 다시 쓰지 않습니다.
쇼핑몰 커미션과 가입 보상은 별개의 기록 유형입니다. 친구가 지갑을 충전하는 것은 상품 구매와 같지 않으며, 그 근거로 자동으로 쇼핑몰 커미션이 생성되지 않습니다. 가입 보상이 지급되는지는 관리자의 기존 초대 보상 설정을 따릅니다.
## 언제 정산되나
| 주문 상태 | 커미션 처리 |
| --- | --- |
| 배송 대기, 처리 중, 활성화 결과 확인 대기 | 예상 커미션만 기록되며, 잔액으로 이전할 수 없음 |
| 바로 사용할 수 있는 계정 또는 기프트카드 배송 성공, 충전 완료 | 시스템이 정산하여 보상 잔액에 입금 |
| 주문 취소 및 환불 | 예상 커미션이 무효화되며, 보상이 지급되지 않음 |
| 주문 중복 제출 또는 완료 알림 중복 | 동일 주문은 한 번만 정산 |
주문 오류나 타임아웃이 배송 완료를 의미하지는 않으며, 단일 처리 결과만으로 커미션이 생성되었는지 판단할 수 없습니다. 정상적인 계정 배송이나 충전 성공 이후 발생한 차단은[쇼핑몰 애프터세일즈 규칙 ](/ko/docs/store-rules/)에 따라 처리됩니다.
보상 수신 계정이 비활성화되었거나 시스템 금액 한도에 도달한 경우, 커미션은 미정산 상태로 남아 조건이 복구되면 다시 시도되며, 이는 구매자의 주문 배송에 영향을 주지 않습니다. 시스템 결제 및 보상 기능이 일시 중단되면 정산도 중단됩니다.
## 어디서 확인하나
지갑의 "최근 쇼핑몰 커미션" 섹션에는 최근 참여 주문의 상품, 사양, 수량, 금액, 상태가 표시됩니다:
- **미정산**: 예상 금액이며, 아직 사용 가능한 보상으로 입금되지 않았습니다.
- **입금 완료**: 보상 잔액에 입금되었으며, 사용 가능한 보상을 계산할 때 다시 더하지 마세요.
- **무효화**: 이 커미션은 더 이상 지급되지 않습니다.
사용 가능한 보상은 기존의 잔액 이전 항목과 최소 이전 요건을 사용하며, 모델 API 소비에 사용할 수 있습니다. 보상은 현금 인출 한도가 아니며, 충전된 쇼핑몰 사용 가능 자금과도 같지 않습니다. 쇼핑몰은 여전히 자체 자금 적격 규칙에 따라 검증합니다.
초대자는 본인에게 귀속된 커미션 기록만 볼 수 있습니다. 기록에는 구매자 신원, 주문 번호, 계정 비밀번호, 교환 코드가 표시되지 않습니다. 커미션 확인이 필요할 때는 공식 웹사이트에 게시된 지원 채널을 통해 커미션 기록 번호, 상품, 발생 시각을 제공하세요. 구매자의 로그인 자격 증명을 요청하지 마세요.
---
# Claude 및 GPT 도구 연동 튜토리얼
Source: https://1zheai.com/ko/docs/integrations/
Markdown: https://1zheai.com/ko/docs/integrations.md
---
title: "Claude 및 GPT 도구 연동 튜토리얼"
description: "Claude Code, Codex CLI, OpenCode, OpenClaw, WorkBuddy, Hermes Agent, Cursor, Cline, Cherry Studio 및 CC Switch의 API 구성 튜토리얼과 지원 범위."
headingIds: {"프로그래밍 도구":"section-1","데스크톱 어시스턴트":"section-2","추가 클라이언트 및 가져오기 방식":"section-3","Agent 플랫폼":"section-4","구성 관리":"section-5","기타 사용자 지정 API를 지원하는 도구":"section-6","구성 성공 확인 방법":"section-7"}
---
사용 중인 도구에 해당하는 튜토리얼로 이동하세요. 아래 상태는 기존 연동 문서를 정리한 것으로, 모든 도구 버전이 엔드투엔드로 검증되었다는 의미는 아닙니다. 도구를 업그레이드한 후에는 페이지의 호출 검증을 다시 완료하세요.
## 프로그래밍 도구
Anthropic 네이티브 연동. 환경 변수, 구성 파일 및 자주 묻는 질문. Responses 인터페이스를 통해 OpenAI / GPT 모델 호출. v1과 v2 구성을 구분하고, OpenAI 호환 공급자를 사용자 지정. OpenAI 호환 연동. 사용자 지정 키의 적용 범위와 인터페이스 차이를 먼저 확인하세요. Anthropic 모드를 우선 사용하며, OpenAI Compatible 구성도 제공.
## 데스크톱 어시스턴트
채팅 클라이언트에 사용자 지정 공급자 추가. 모델 설정에서 사용자 지정 주소 추가, 전체 URL과 프로토콜 토글에 주의.
## 추가 클라이언트 및 가져오기 방식
가져오기 링크 또는 클립보드 JSON, 수동 백업 구성 지원. Android 공급자 QR 코드, 키 내용은 기본적으로 숨김. 사용자 지정 공급자 필드 및 모델 구성. 관리자 YAML 엔드포인트 및 사용자별 독립 키. VS Code 확장의 Anthropic 구성.
원클릭 프로토콜은 클라이언트가 공개적으로 지원하는 작업에만 사용됩니다. ChatWise의 대화 열기 프로토콜은 키 가져오기와 같지 않으며, LibreChat은 관리자 구성이 필요합니다. 모든 도구를 동일한 가져오기 링크로 취급하지 마세요.
## Agent 플랫폼
사용자 지정 Anthropic 제공자 및 기본 Agent 모델 구성. 모델 마법사 또는 명명된 provider를 통해 Chat Completions 구성. OpenCode, OpenClaw, WorkBuddy 및 Hermes Agent 튜토리얼은 공식 구성을 확인했으나, 본 사이트의 엔드투엔드 검증은 완료되지 않았습니다. 튜토리얼에 따라 실제 버전을 확인하고 호출을 검증하세요.
## 구성 관리
Claude Code의 공급자 구성을 관리하여 수동 전환을 줄임.
## 기타 사용자 지정 API를 지원하는 도구
도구가 API 주소, 키 및 모델 ID를 설정할 수 있는지 먼저 확인한 다음, 프로토콜에 따라 구성을 선택하세요:
| 도구가 지원하는 프로토콜 | 본 사이트 인터페이스 | 다음 단계 |
| --- | --- | --- |
| Anthropic Messages | `/v1/messages` | 클라이언트가 `/v1`을 자동으로 추가하는지 확인하고, [주소 설명](/ko/docs/base-url/) 참조 |
| OpenAI Chat Completions | `/v1/chat/completions` | 일반적으로 Base URL에 `https://1zheai.com/v1` 입력; 전체 엔드포인트 필드는 예외 |
| OpenAI Responses | `/v1/responses` | Base URL에 `https://1zheai.com/v1` 입력, [Codex CLI](/ko/docs/quickstart-codex/) 참조 |
| 공식 계정 로그인만 지원 | 본 사이트 API 키 미사용 | 도구에 별도의 사용자 지정 공급자 설정이 있는지 확인 |
## 구성 성공 확인 방법
1. 튜토리얼에 따라 프로토콜과 Base URL을 선택합니다. 각 도구가 `/v1`을 필요로 하는지는 [주소 대조표](/ko/docs/base-url/) 참조.
2. [지원 모델](/ko/docs/models/)에서 현재 사용 가능한 모델을 선택합니다.
3. 짧은 요청을 하나 실행하여 도구가 정상적으로 응답하는지 확인합니다.
4. [호출 로그](/ko/docs/usage-logs/)에서 해당 호출을 확인합니다. 응답 내용만으로 요청이 어느 공급자를 거쳤는지 판단하지 마세요.
문제가 발생하면 먼저 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 확인하세요. 직접 프로그램을 작성할 때는 [개발 가이드](/ko/docs/guides/)으로 이동하세요.
---
# Claude Code 연결
Source: https://1zheai.com/ko/docs/quickstart-claude-code/
Markdown: https://1zheai.com/ko/docs/quickstart-claude-code.md
---
title: "Claude Code 연결"
description: "Claude Code를 1折AI에 연결: ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN(환경 변수 또는 settings.json), Windows 작성법, 모델 매핑, VS Code 플러그인 및 자주 발생하는 오류 포함."
headingIds: {"최단 경로":"section-1","전체 단계":"section-2","ANTHROPIC_AUTH_TOKEN을 쓰는 이유":"section-3","모델 매핑":"section-4","VS Code 플러그인":"section-5","선택 설정":"section-6","자주 발생하는 문제":"section-7"}
---
Claude Code에는 두 개의 변수만 필요합니다. `ANTHROPIC_BASE_URL` 은 우리를 가리키고, `ANTHROPIC_AUTH_TOKEN` 에는 API 키(API key)를 입력합니다. Anthropic 계정 로그인은 필요하지 않습니다.
## 최단 경로
Claude Code가 이미 설치되어 있고 API 키가 있다면, 아래 두 줄을 `~/.claude/settings.json` 에 작성한 다음 `claude` 을 실행하세요:
```json title="~/.claude/settings.json"
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
파일이 이미 존재한다면, 이 두 항목을 기존 `env` 에 병합하고 다른 설정은 덮어쓰지 마세요.
## 전체 단계
이미 설치했다면 건너뛰어도 됩니다. 다음 명령은 [Claude Code 공식 설치 문서](https://code.claude.com/docs/en/setup) 에서 가져왔습니다:
```bash title="macOS / Linux"
curl -fsSL https://claude.ai/install.sh | bash
```
```powershell title="Windows PowerShell"
irm https://claude.ai/install.ps1 | iex
```
```bash title="Homebrew"
brew install --cask claude-code
```
```bash title="npm（需要 Node.js 22+）"
npm install -g @anthropic-ai/claude-code
```
npm으로 설치할 때는 `sudo` 을 붙이지 마세요.
[콘솔](https://1zheai.com/console?lng=ko) 에서 새 API 키를 만드세요. 이 기기의 Claude Code 전용으로 쓰는 것을 권장합니다. [API 키 가져오기 및 관리](/ko/docs/api-keys/) 참조.
settings.json 위치: macOS / Linux는 `~/.claude/settings.json`, Windows는 `%USERPROFILE%\.claude\settings.json` 입니다.
```json title="settings.json（推荐）"
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
```bash title="macOS / Linux 环境变量"
# 写进 ~/.zshrc 或 ~/.bashrc，然后重开终端
export ANTHROPIC_BASE_URL="https://1zheai.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的Key"
```
```powershell title="Windows PowerShell"
# 持久写入当前用户，重开终端后生效
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://1zheai.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的Key", "User")
# 只在当前窗口生效
$env:ANTHROPIC_BASE_URL = "https://1zheai.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的Key"
```
```bat title="Windows CMD"
setx ANTHROPIC_BASE_URL "https://1zheai.com"
setx ANTHROPIC_AUTH_TOKEN "sk-你的Key"
```
`ANTHROPIC_BASE_URL` 에는 루트 주소를 입력하고, `/v1` 을 붙이지 마세요. Claude Code가 알아서 `/v1/messages` 을 조합합니다.
프로젝트 디렉터리에서 `claude` 을 실행한 뒤 `/status` 을 입력하세요. 두 줄을 확인합니다:
- base URL 행에 `https://1zheai.com` 이 표시됨
- 자격 증명 행에 출처가 `ANTHROPIC_AUTH_TOKEN` 로 표시됨
그런 다음 한 문장을 입력하고 [호출 로그](/ko/docs/usage-logs/) 에 새 기록이 있는지 확인하세요. 있으면 연결된 것입니다.
대화형 인터페이스에 들어가고 싶지 않다면 비대화형 모드로 한 번 시도해 볼 수 있습니다(2026-10-15 실제 테스트 반환값 `ok`):
```bash
claude -p "say ok" --model claude-sonnet-4-6
```
## ANTHROPIC_AUTH_TOKEN을 쓰는 이유
Claude Code에는 API 키를 넣을 수 있는 두 변수가 있으며, 차이는 다음과 같습니다([공식 설명](https://code.claude.com/docs/en/authentication)):
| 변수 | 전송 방식 | 동작 |
|---|---|---|
| `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <值>` | 설정 즉시 적용, 확인 창 없음 |
| `ANTHROPIC_API_KEY` | `x-api-key: <值>` | 대화형 모드에서 처음 실행 시 이 API 키를 사용할지 확인하는 창이 뜸 |
두 방식 모두 지원하며, `ANTHROPIC_AUTH_TOKEN` 을 권장합니다. **둘 중 하나만 설정하세요**: 시스템에 이전 공식용 `ANTHROPIC_API_KEY` 이 남아 있다면 삭제하세요. 혼용하면 401이 발생할 수 있습니다.
또한 자주 걸리는 규칙 두 가지:
- `settings.json` 의 `env` 과 터미널 export에서 같은 변수를 설정한 경우, **settings.json이 우선**합니다. 터미널 변수를 바꿨는데 안 되면 먼저 settings.json을 확인하세요.
- API 키를 프로젝트의 `.claude/settings.json` 에 쓰지 마세요. 이 파일은 보통 저장소에 커밋됩니다. 프로젝트별로 구분하려면 커밋하지 않는 `.claude/settings.local.json` 을 사용하세요.
## 모델 매핑
Claude Code의 `opus`, `sonnet`, `haiku`, `fable` 은 별칭이며, 환경 변수로 각각 대응하는 실제 모델을 지정할 수 있습니다. Haiku 등급은 Claude Code가 일부 백그라운드 소형 작업을 실행하는 데도 사용됩니다.
| 변수 | 역할 | 예시 값 |
|---|---|---|
| `ANTHROPIC_MODEL` | 시작 시 사용하는 모델 | `claude-sonnet-5-5` |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 별칭이 가리키는 모델 | `claude-opus-5-5` |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 별칭이 가리키는 모델 | `claude-sonnet-5-5` |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 별칭과 백그라운드 작업에 쓰는 모델 | `claude-haiku-5-5` |
| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 별칭이 가리키는 모델 | `claude-fable-5-1` |
```json title="~/.claude/settings.json（带模型映射）"
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
"ANTHROPIC_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
}
}
```
모델 ID는 [지원 모델](/ko/docs/models/) 목록에 있는 것이어야 합니다. 실행 중에도 `/model claude-opus-5-5` 으로 임시 전환할 수 있습니다.
## VS Code 플러그인
Claude Code의 VS Code 플러그인은 시작 전에 자격 증명을 확인하며, 공식적으로는 변수를 VS Code 자체 사용자 설정에 작성할 것을 권장합니다(명령 팔레트 → Preferences: Open User Settings (JSON)):
```json title="VS Code settings.json"
{
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://1zheai.com" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-你的Key" }
]
}
```
`~/.claude/settings.json` 에만 작성하면 플러그인 자체의 로그인 확인이 읽지 못할 수 있습니다.
## 선택 설정
| 변수 | 역할 |
|---|---|
| `API_TIMEOUT_MS` | 요청 타임아웃, 기본값 600000(10분). 긴 작업이 자주 타임아웃되면 키우세요 |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | 자동 업데이트, 텔레메트리, 오류 보고 등 불필요한 트래픽을 끕니다. `0` 또는 `false` 로 설정해도 켜진 것으로 간주되며, 끄려면 이 변수를 삭제해야 합니다 |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | "Extra inputs are not permitted"류 400 오류 발생 시 사용 |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` | `/model` 목록을 `/v1/models` 에서 가져오도록 함 |
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 은 실제 테스트로 사용 가능함이 확인되었습니다(Claude Code 2.1.296, 2026-10-15): 시작 후 debug 로그에 `[gatewayDiscovery] cached 14 models` 이 나타나며, 14개 모델이 [지원 모델](/ko/docs/models/) 과 일치합니다.
`DISABLE_PROMPT_CACHING` 은 설정하지 마세요. 캐시를 끄게 되어 청구액이 눈에 띄게 증가합니다. [Prompt Caching](/ko/docs/prompt-caching/) 참조.
## 자주 발생하는 문제
Claude Code가 API 키를 읽지 못했습니다. 변수명 철자를 확인하세요. 환경 변수를 쓴다면 새로 연 터미널에서 시작했는지 확인하고, settings.json을 쓴다면 JSON 형식이 올바른지 확인하세요(쉼표 하나가 많아도 전체가 무효화됩니다).
API 키가 복사되지 않았거나, `ANTHROPIC_API_KEY` 과 `ANTHROPIC_AUTH_TOKEN` 이 동시에 존재하고 그중 하나가 이전 값입니다. 둘 중 하나만 남기세요. 자세한 내용은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/) 참조.
`ANTHROPIC_BASE_URL` 에 `/v1` 을 잘못 추가했습니다. `https://1zheai.com` 으로 바꾸세요.
Claude Code가 Haiku 등급으로 백그라운드 소형 작업을 실행하는 것입니다. 다른 모델로 바꾸려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 을 설정하세요.
위 두 변수를 삭제하거나(주석 처리하면) 공식 로그인으로 돌아갑니다. 자주 전환한다면 [CC Switch](/ko/docs/quickstart-cc-switch/) 을 사용하세요. 클릭 한 번으로 전환됩니다.
연결되지 않습니다. 1折AI에 연결할 때 Claude Code는 우리의 API 키를 사용하며, 당신의 Anthropic 계정에 로그인하지 않습니다.
---
# Codex CLI 연결
Source: https://1zheai.com/ko/docs/quickstart-codex/
Markdown: https://1zheai.com/ko/docs/quickstart-codex.md
---
title: "Codex CLI 연결"
description: "OpenAI Codex CLI를 1折AI에 연결하는 구성 방법(~/.codex/config.toml의 model_providers), Responses 인터페이스를 통해 GPT 모델 호출."
headingIds: {"구성 파일":"section-1","Codex 설치":"section-2","자주 묻는 질문":"section-3"}
---
OpenAI / GPT 모델이 출시되었습니다. Codex CLI는 OpenAI Responses 인터페이스(`/v1/responses`)를 사용하며, 본 사이트 API 키로 연결합니다. 사용 가능한 모델과 가격은 [모델 카탈로그](https://1zheai.com/model-catalog?lng=ko)에서 확인하세요.
먼저 Codex 사용자 지정 공급자 구성 방식을 명확히 설명하겠습니다. 형식은 [Codex 공식 구성 문서](https://developers.openai.com/codex/config-reference)에서 가져왔습니다.
## 구성 파일
Codex의 구성은 `~/.codex/config.toml`에 있습니다. 사용자 지정 공급자는 이 사용자 수준 파일에만 작성할 수 있으며, 프로젝트의 `.codex/config.toml`에서 `model_provider`을(를) 설정하면 무시됩니다.
```toml title="~/.codex/config.toml"
model_provider = "onezhe"
model = "gpt-6-astra"
[model_providers.onezhe]
name = "1折AI"
base_url = "https://1zheai.com/v1"
env_key = "ONEZHE_API_KEY"
wire_api = "responses"
```
예제는 `gpt-6-astra`을(를) 사용하며, 키가 지원하는 다른 GPT 모델 ID로 교체할 수 있습니다.
각 필드의 의미:
| 필드 | 설명 |
|---|---|
| `model_provider` | 어떤 공급자를 사용할지, 아래 `[model_providers.]`의 id에 해당합니다. `openai`, `ollama`, `lmstudio`은(는) 예약된 이름이므로 사용할 수 없습니다 |
| `base_url` | `/v1`을(를) 포함해야 합니다 |
| `env_key` | Codex가 이 환경 변수에서 API 키(API key)를 읽습니다. 이름이 export한 것과 정확히 일치해야 합니다 |
| `wire_api` | 공식 문서에 따르면 현재 `responses`만 지원하며, 생략 시에도 동일합니다 |
그런 다음 API 키를 환경 변수에 넣습니다:
```bash title="macOS / Linux"
export ONEZHE_API_KEY="sk-你的Key"
```
```powershell title="Windows PowerShell"
[Environment]::SetEnvironmentVariable("ONEZHE_API_KEY", "sk-你的Key", "User")
```
## Codex 설치
다음 명령은 Codex 공식 문서에서 가져왔습니다:
```bash title="npm"
npm install -g @openai/codex
```
```bash title="Homebrew"
brew install --cask codex
```
```bash title="macOS / Linux 脚本"
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```
```powershell title="Windows"
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```
## 자주 묻는 질문
`env_key`에 작성된 변수 이름이 실제 export한 것과 일치하지 않거나, 환경 변수를 설정하기 전에 터미널을 열었습니다. 양쪽 이름을 다시 확인하고, 터미널을 다시 열어 재시도하세요.
불가능합니다. Codex 공식 구성 문서에서 `wire_api`은(는) `responses`만 허용합니다. Chat Completions 인터페이스만 제공하는 서비스는 Codex에 연결하려면 별도의 프로토콜 변환 도구가 필요합니다.
[모델 카탈로그](https://1zheai.com/model-catalog?lng=ko)에서 현재 모델을 확인하고, 모델 ID를 `model`에 입력하세요. Codex를 시작한 후 짧은 요청을 보내고, [호출 로그](/ko/docs/usage-logs/)에서 모델과 상태를 확인하세요.
---
# OpenCode Claude API 연결
Source: https://1zheai.com/ko/docs/quickstart-opencode/
Markdown: https://1zheai.com/ko/docs/quickstart-opencode.md
---
title: "OpenCode Claude API 연결"
description: "OpenCode에서 1折AI Claude API 중계 주소, 키, 모델을 구성하는 튜토리얼. 프로토콜 선택, 구성 예제, 검증 단계 및 일반적인 오류를 포함합니다."
headingIds: {"OpenCode v1 구성":"section-1","OpenCode v2 구성":"section-2","연결 검증 및 문제 해결":"section-3","비용 및 기타 연결 방법":"section-4"}
---
OpenCode의 사용자 지정 공급자 기능을 사용하여 1折AI에 연결합니다. 먼저 [API 키 생성](/ko/docs/api-keys/)을 하고 [현재 사용 가능한 모델](/ko/docs/models/)을 확인하세요. 아래 모델 ID는 예시이므로 키 권한에 맞게 조정하세요.
공식 구성 확인 날짜: 2026-10-15. 아래 구성은 공식 문서에 따라 정리되었으며, 이 사이트의 엔드투엔드 검증은 아직 완료되지 않았습니다. 긴 작업에 사용하기 전에 짧은 질의응답 및 도구 호출 검증을 먼저 완료하세요. OpenAI / GPT 모델이 출시되었으며, 모델 목록과 가격은 [모델 설명](/ko/docs/models/)을 참조하세요.
## OpenCode v1 구성
[공식 v1 Providers](https://opencode.ai/docs/providers/)에 따라: `/connect`을 실행하고 Other를 선택한 다음, provider ID에 `onezhe`을 입력하고 이 사이트의 API Key를 작성하세요. 프로젝트 `opencode.json`에 병합:
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"onezhe": {
"npm": "@ai-sdk/openai-compatible",
"name": "1折AI",
"options": { "baseURL": "https://1zheai.com/v1" },
"models": {
"claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" }
}
}
}
}
```
이후 `/models`에서 해당 provider의 모델을 선택하세요. `/connect`은 자격 증명만 저장하며 provider 구성을 대체하지 않습니다. 여기서는 Chat Completions용 SDK를 명시적으로 선택합니다. Responses용 `@ai-sdk/openai`로 잘못 교체할 수 없습니다. 공식적으로는 `options.apiKey: "{env:ONEZHE_API_KEY}"`을 통해 환경 변수를 참조하는 것도 허용됩니다.
## OpenCode v2 구성
[공식 v2 Providers](https://opencode.ai/v2/docs/providers)에 따라, 네이티브 v2 필드를 사용하며 위의 v1과 혼합해서는 안 됩니다. 프로젝트 `opencode.jsonc`에 병합:
```json
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"onezhe": {
"name": "1折AI",
"env": ["ONEZHE_API_KEY"],
"package": "@opencode/ai/providers/openai-compatible",
"settings": { "baseURL": "https://1zheai.com/v1" },
"models": {
"claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" }
}
}
}
}
```
OpenCode를 시작하는 프로세스 환경에서 `ONEZHE_API_KEY`을 제공한 다음, `/models`에서 `onezhe/claude-sonnet-4-6`을 선택하세요. v2의 주요 차이는 `providers`, `package`, `settings`이며, v1의 `provider`, `npm`, `options`이 아닙니다. 사용 중인 메이저 버전은 먼저 `opencode --version`으로 확인하세요.
네이티브 Anthropic을 사용하려는 경우, v1 공식적으로는 `provider.anthropic.options.baseURL`을 재정의하는 것을 허용하며, 예제에는 `/v1`이 포함됩니다. v2는 `@opencode/ai/providers/anthropic-compatible`을 나열합니다. 이 튜토리얼은 명시적인 OpenAI 호환 구성을 따르므로, 모델 이름만으로 프로토콜을 임의로 교체하거나 캐싱 및 도구 호출이 모두 검증되었다고 주장할 수 없습니다.
## 연결 검증 및 문제 해결
1. 구성을 저장하고 다시 로드한 후, 현재 선택된 것이 `onezhe` 공급자 또는 추가한 사용자 지정 모델인지 확인하세요.
2. 짧은 질문 하나를 보내 응답이 반환되는지 확인한 다음, 되돌릴 수 있는 작은 작업을 시도하여 도구 호출과 다중 턴 대화를 별도로 확인하세요.
3. [호출 로그](/ko/docs/usage-logs/)를 열어 요청 시간, 모델, 상태 및 사용량을 확인하세요. 텍스트 응답이 한 번 성공했다고 해서 모든 Agent 기능이 호환된 것은 아닙니다.
4. 404가 발생하면 이 문서의 주소와 프로토콜이 맞는지 확인하세요. 401이 발생하면 키의 출처와 프로세스가 환경 변수를 읽었는지 확인하세요. 429가 발생하면 속도 제한 정보를 확인한 후 재시도하세요. 자세한 내용은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
키는 로컬 환경 또는 도구의 자격 증명 저장소에만 저장하며, 코드 저장소, 스크린샷 또는 공개 로그에 커밋하지 마세요. 백그라운드 서비스는 터미널 환경 변수를 상속하지 않을 수 있습니다. 보조 모델, 검색 및 기타 도구에는 별도의 공급자 설정이 있을 수 있으므로 각각 확인해야 합니다.
## 비용 및 기타 연결 방법
[Claude API 실시간 가격](https://1zheai.com/en/pricing/)과 [과금 규칙](/ko/docs/pricing-explained/)을 확인하세요. 다른 클라이언트가 필요하면 [도구 연결 디렉터리](/ko/docs/integrations/)로 돌아가세요. 직접 프로그램을 작성하려면 [SDK 및 개발 가이드](/ko/docs/guides/)를 사용하세요.
---
# Cursor 연결
Source: https://1zheai.com/ko/docs/quickstart-cursor/
Markdown: https://1zheai.com/ko/docs/quickstart-cursor.md
---
title: "Cursor 연결"
description: "Cursor에서 사용자 지정 OpenAI API 키와 Base URL을 사용하여 1折AI의 Claude 모델을 호출하는 방법과, 사용자 지정 API 키를 거치지 않는 기능에 대해 안내합니다."
headingIds: {"구성":"section-1","알려진 문제":"section-2","자주 묻는 질문":"section-3"}
---
Cursor는 설정에서 직접 API 키(API key)를 입력할 수 있으며, 채팅 모델은 이 API 키로 요청을 보냅니다. 아래는 1折AI를 연결하는 방법과, 시작 전에 반드시 알아야 할 몇 가지 제한 사항입니다.
작업을 시작하기 전에 다음 세 가지를 먼저 확인하세요:
- Cursor 공식 문서에 따르면, **사용자 지정 API 키는 채팅 모델에만 적용되며, Tab 자동완성은 항상 Cursor 자체 모델을 사용합니다**.
- 요청은 Cursor 서버를 거쳐 입력한 주소로 전달되므로, Base URL은 공개적으로 접근 가능해야 합니다(`https://1zheai.com/v1`은 문제없지만, 로컬 `localhost` 프록시는 불가합니다).
- "Override OpenAI Base URL" 스위치는 Cursor 공식 문서에 없으며, 아래 인터페이스 설명은 Cursor 포럼과 커뮤니티 튜토리얼에서 가져온 것으로, Cursor 개편 시 변경될 수 있습니다.
## 구성
Cursor → **Cursor Settings** → **Models**로 이동하여 Keys 영역을 찾습니다.
```text
OpenAI API Key sk-你的Key（1折AI 的 Key）
Override OpenAI Base URL https://1zheai.com/v1
```
Base URL에는 `/v1`을(를) 포함해야 합니다.
모델 목록에서 **Add model**을 클릭하고 모델 ID를 입력합니다(예: `claude-sonnet-5-5`). 그런 다음 해당 모델의 스위치를 켭니다. 모델 ID는 [지원되는 모델](/ko/docs/models/)을(를) 참조하세요.
Chat 패널에서 방금 추가한 모델을 선택하고 메시지를 보냅니다. 응답이 정상적으로 오면, 콘솔의 [호출 로그](/ko/docs/usage-logs/)에서 이 호출을 확인합니다.
## 알려진 문제
Cursor 포럼에 다음과 같은 피드백이 있습니다: Override OpenAI Base URL을 설정한 후, 이름이 `claude-`으로 시작하는 모델은 Cursor가 Anthropic 모델로 인식하여 Anthropic API 키로 처리하거나, 바로 오류를 반환할 수 있습니다. Claude를 선택할 때 모델 ID는 `claude-`로 시작하며, 이 문제가 발생하면 Cursor에 입력된 Anthropic API 키를 먼저 비운 후 다시 시도하세요.
참고: [포럼 게시물 144899](https://forum.cursor.com/t/anthropic-models-break-when-override-openai-baseurl-is-set/144899), [포럼 게시물 146998](https://forum.cursor.com/t/override-anthropic-base-url-automatically-switches-on-when-using-anthropic-byok/146998).
## 자주 묻는 질문
아니요. Cursor 공식 문서에 따르면, Tab 자동완성은 항상 Cursor 기본 모델을 사용하며, 사용자의 API 키를 거치지 않습니다.
먼저 Base URL에 `/v1`이(가) 포함되어 있는지 확인하세요. 커뮤니티 피드백에 따르면 Verify 버튼은 OpenAI가 아닌 모델 이름에 대해 통과하지 못할 수 있으므로, Chat에서 메시지를 직접 보내 테스트하고 호출 로그에 기록이 있는지로 판단하세요.
커뮤니티 튜토리얼의 일반적인 피드백은 Chat만 사용자 지정 API 키를 거치며, Agent, Apply, Inline Edit 등의 기능은 여전히 Cursor 자체 백엔드를 거칠 수 있다는 것입니다. 실제 호출 로그에 기록된 내용을 기준으로 판단하세요.
주로 Claude로 코드를 작성하고 싶다면, [Claude Code](/ko/docs/quickstart-claude-code/)(명령줄 또는 VS Code 플러그인)과 [Cline](/ko/docs/quickstart-cline/)이(가) 사용자 지정 주소에 대한 지원이 더 완벽합니다.
---
# Cline 연결
Source: https://1zheai.com/ko/docs/quickstart-cline/
Markdown: https://1zheai.com/ko/docs/quickstart-cline.md
---
title: "Cline 연결"
description: "VS Code의 Cline 플러그인에서 1折AI 연결: Anthropic 사용자 지정 Base URL 또는 OpenAI Compatible 두 가지 방법."
headingIds: {"방법 1: Anthropic (권장)":"section-1","방법 2: OpenAI Compatible":"section-2","자주 묻는 질문":"section-3"}
---
Cline은 VS Code의 코딩 Agent 플러그인입니다. 두 방법 모두 1折AI에 연결할 수 있으며, Anthropic 방식을 권장합니다. Claude의 네이티브 기능(캐시 포함)이 더 완전합니다.
## 방법 1: Anthropic (권장)
Cline 설정을 열고 **API Provider**에서 **Anthropic**을 선택합니다.
- **Anthropic API Key** (API 키 입력): `sk-你的Key`
- **Use custom base URL**를 체크하고 `https://1zheai.com`를 입력합니다 (`/v1`을 추가하지 마세요)
모델 드롭다운에서 1折AI [지원 모델](/ko/docs/models/) 중 하나를 선택합니다. 예: `claude-sonnet-5-5`.
## 방법 2: OpenAI Compatible
**API Provider**에서 **OpenAI Compatible**을 선택합니다.
| 필드 | 값 |
|---|---|
| Base URL | `https://1zheai.com/v1` |
| API Key | `sk-你的Key` |
| Model ID | `claude-sonnet-5-5` |
**Verify**를 클릭하여 연결을 확인한 다음, Cline에서 작은 작업을 하나 전송합니다.
Model Configuration에서 컨텍스트 윈도우와 최대 출력 길이를 입력할 수 있습니다. [Anthropic 공식 모델 문서](https://platform.claude.com/docs/en/about-claude/models/overview)에 따라 해당 모델의 값을 입력하세요.
## 자주 묻는 질문
Anthropic 방식은 네이티브 `/v1/messages`을 사용하므로 캐싱, thinking 등의 기능이 가장 완전합니다. OpenAI Compatible 방식은 `/v1/chat/completions`을 사용하며 범용성에서 강점이 있습니다. Claude 모델을 사용할 때는 Anthropic을 우선 선택하세요.
Anthropic 방식의 주소에는 `/v1`을 붙이지 마세요. OpenAI Compatible 방식의 주소에는 `/v1`을 반드시 붙여야 합니다. 두 방식은 정반대입니다.
---
# Cherry Studio 연결
Source: https://1zheai.com/ko/docs/quickstart-cherry-studio/
Markdown: https://1zheai.com/ko/docs/quickstart-cherry-studio.md
---
title: "Cherry Studio 연결"
description: "Cherry Studio에 1折AI를 사용자 지정 서비스 제공자로 추가하고, Anthropic 또는 OpenAI 엔드포인트를 선택한 후 루트 주소, API 키, 모델을 입력합니다."
headingIds: {"원클릭 가져오기":"section-1","구성":"section-2","Anthropic 엔드포인트와 OpenAI 엔드포인트 중 선택":"section-3","자주 묻는 질문":"section-4"}
---
Cherry Studio는 데스크톱용 AI 대화 클라이언트로, 1折AI를 사용자 지정 서비스 제공자로 추가할 수 있습니다.
## 원클릭 가져오기
콘솔의 **API 키 → 사용 도구 → Cherry Studio**에서 Anthropic 또는 OpenAI 프로토콜을 선택하고 **Cherry Studio 열기**를 클릭합니다. 앱 내에서 가져오기를 확인한 후 모델을 가져오고 서비스 제공자를 활성화하고 테스트합니다. 동일한 이름의 구성이 이미 있는 경우 덮어쓰기 경고를 확인합니다. 가져오기 링크에는 전체 키가 포함되어 있으므로 전달하지 마세요.
브라우저는 앱이 설치되어 있는지 확인할 수 없습니다. 호출되지 않으면 먼저 클라이언트를 설치하고 한 번 실행하거나 아래의 수동 단계를 사용하세요. 프로토콜 형식은 공식 구현을 확인했지만 실제 추론은 실제 버전과 모델에 따라 검증해야 합니다.
## 구성
설정(톱니바퀴 아이콘) → **모델 서비스** → 목록 하단의 **+ 서비스 제공자 추가**.
| 필드 | 입력 내용 |
|---|---|
| 제공자 이름 | `1折AI` |
| API 키 | `sk-你的Key` |
| 엔드포인트 | **Anthropic**(권장) 또는 **OpenAI** 선택 |
| API 주소 | `https://1zheai.com` |
API 주소에는 루트 주소만 입력하세요. Cherry Studio는 선택한 프로토콜에 따라 `/v1/...`을 자동으로 추가합니다. `/v1/messages`, `/v1/chat/completions` 같은 전체 경로를 붙여넣지 마세요. 끝에 `#`을 추가하지 마세요(`#`로 끝나면 경로가 자동으로 추가되지 않습니다).
**모델 목록 가져오기**를 클릭하고 반환된 목록에서 사용할 모델을 추가하거나, **+**를 클릭하여 모델 ID를 직접 입력하세요(예: `claude-sonnet-5-5`). 목록에 추가된 모델만 대화의 모델 선택에 표시됩니다.
서비스 제공자 페이지 오른쪽 상단의 활성화 토글을 켜고, 대화 화면으로 돌아가 1折AI 아래의 모델로 메시지를 보내세요.
## Anthropic 엔드포인트와 OpenAI 엔드포인트 중 선택
| 엔드포인트 | 적합한 경우 |
|---|---|
| Anthropic | extended thinking 등 Claude의 네이티브 기능을 사용하고 싶을 때; Agent의 프로토콜 제한은 현재 버전을 기준으로 합니다 |
| OpenAI | OpenAI 형식에 익숙하거나 다른 OpenAI 호환 서비스와 통합 관리하고 싶을 때 |
두 엔드포인트는 동일한 API 키(API key)와 동일한 모델 ID 세트를 사용합니다.
## 자주 묻는 질문
먼저 API 키에 불필요한 공백이 없는지 확인하세요. 그다음 API 주소가 `https://1zheai.com`인지, 경로가 과도하게 입력되지 않았는지 확인하세요. 가져오지 못해도 사용에는 영향이 없으며, 모델 ID를 직접 입력해도 사용할 수 있습니다.
API 주소에 전체 경로를 입력했거나 끝에 `#`을 추가한 경우입니다. 루트 주소 `https://1zheai.com`로 되돌리세요.
---
# Dify 연동
Source: https://1zheai.com/ko/docs/quickstart-dify/
Markdown: https://1zheai.com/ko/docs/quickstart-dify.md
---
title: "Dify 연동"
description: "공식 Dify OpenAI-API-compatible 플러그인을 사용하여 1折AI를 구성하는 방법을 다룹니다. 모델 설정, 대화 테스트, 첫 호출 문제 해결까지 안내합니다."
headingIds: {"전제 조건":"section-1","모델 추가":"section-2","첫 대화 시작하기":"section-3","예제 Chatflow 가져오기":"section-4","문제 해결":"section-5","연동 지원 받기":"section-6","검증 범위":"section-7","English / Русский":"section-8"}
---
Dify 사용자는 공식 **OpenAI-API-compatible** 모델 플러그인을 통해 1折AI의 OpenAI 호환 엔드포인트를 구성할 수 있습니다. 먼저 텍스트 모델을 확인한 다음 워크플로우에서 사용하세요. 검증되지 않은 서드파티 플러그인을 설치할 필요는 없습니다.
## 전제 조건
- 모델 플러그인을 설치할 수 있는 Dify 워크스페이스.
- 본인의 1折AI API 키와 해당 키로 호출이 허용된 모델 ID. [콘솔](https://1zheai.com/console)에서 확인하세요.
- 계정에 충분한 잔액. 모델 저장 시의 검증 요청과 애플리케이션 테스트는 일반 API 요금이 발생할 수 있습니다.
전체 키를 고객 지원에 보내지 마세요. 워크플로우 설명, 스크린샷, 공개 저장소에 기록하지 마세요. Dify의 API Key 필드에만 저장하세요. 서드파티 호스팅 Dify를 사용하는 경우 해당 인스턴스가 키를 보유하고 요청을 전달합니다.
## 모델 추가
1. Dify 플러그인 마켓플레이스에서 **OpenAI-API-compatible**을 찾고 게시자가 **langgenius**인지 확인하세요.
2. 워크스페이스 설정에서 모델 프로바이더를 열고 이 플러그인을 찾아 LLM 모델을 추가하세요.
3. 아래 항목을 입력하고 저장하세요. 인터페이스 라벨은 Dify 버전에 따라 다를 수 있습니다.
| 항목 | 입력 방법 |
| --- | --- |
| Model Name | 1折AI 콘솔에서 전체 모델 ID를 복사하세요. 표시 이름으로 대체하지 마세요 |
| API Key | 본인의 1折AI 키 |
| API Base URL | `https://1zheai.com/v1` |
| Completion mode | `Chat` |
| API 엔드포인트의 모델 이름 | 보통 비워 두세요. 설정하는 경우 실제 모델 ID와 일치해야 합니다 |
| 모델 컨텍스트 크기 | 선택한 모델의 실제 능력에 맞춰 입력하세요. 다른 모델의 컨텍스트 길이를 복사하지 마세요 |
여기서는 `/v1`이(가) 필요합니다. 전체 `/v1/chat/completions`을(를) 입력하지 마세요. `/v1/v1`(으)로 중복 입력하지 마세요. 루트 주소만 요구하는 다른 클라이언트의 지침을 적용하지 마세요.
## 첫 대화 시작하기
빈 채팅 앱을 만들고 방금 저장한 모델을 선택한 다음 "한 문장으로 당신이 할 수 있는 일을 중국어로 소개해 주세요."를 입력하세요. 완전한 텍스트 응답이 확인되면 다음으로 스트리밍 출력을 확인하세요.
1折AI 콘솔의 호출 로그에서 해당 요청 시간, 모델, 결과를 확인하세요. 앱이 연결되었다는 증거로 Dify의 "저장되었습니다"만 신뢰하지 마세요. 첫 성공 후에 도구 호출, 비전 입력, 지식 베이스 검색을 구성하세요. 이 기능들은 특정 모델과 인터페이스에 따라 다르며, 텍스트 대화가 성공했다고 해서 모든 것이 사용 가능하다는 의미는 아닙니다.
## 예제 Chatflow 가져오기
[키 없는 Chatflow 템플릿 다운로드](/ko/docs/downloads/1zheai-dify-chatflow.yml)한 다음 Dify Studio에서 **Create → Import DSL file**을 선택하여 업로드하세요. 템플릿은 `User Input → LLM → Answer`이며, DSL 버전은 0.7.0이고 공식 호환 플러그인 0.0.68을 사용합니다.
먼저 위 단계에 따라 본인의 자격 증명을 추가하세요. 가져온 후 LLM 노드를 열고 본인의 프로바이더와 모델이 선택되었는지 확인하세요. Dify의 체험 모델이 선택되면 안 됩니다. 예제 모델 ID는 `claude-haiku-4-5-20251001`입니다. 본인 계정에서 사용할 수 없는 경우 접근 가능한 모델로 전환하고 기능 설정을 확인하세요. 템플릿에는 API 키가 포함되어 있지 않으며 무료 호출 크레딧을 제공하지 않습니다.
## 문제 해결
| 증상 | 먼저 확인할 사항 |
| --- | --- |
| 503 / 사용 가능한 계정 없음 | 현재 업스트림이 속도 제한이 걸렸거나 용량이 부족할 수 있습니다. 먼저 서비스 상태와 호출 로그를 확인하고, 나중에 백오프를 두고 재시도하거나 지원팀에 문의하세요. 높은 빈도로 계속 재시도하지 마세요. 키를 반복해서 재생성하지 마세요 |
| 401 / 잘못된 키 | 추가 공백이 있는지, 키가 취소되었는지, 다른 플랫폼의 키를 실수로 사용했는지 |
| 404 | Base URL이 정확히 `https://1zheai.com/v1`인지; 모델 ID가 존재하는지 |
| 모델 허용 안 됨 또는 잔액 부족 | 현재 키의 모델 제한, 계정의 가용 잔액, 선택한 모델 |
| 저장은 성공했지만 앱이 호출할 수 없음 | 앱이 올바른 프로바이더와 모델을 선택했는지; 워크스페이스 서버가 API에 도달할 수 있는지 |
| 일반 응답은 정상, 스트리밍은 실패 | 프록시의 SSE 지원, 플러그인 버전, 스트리밍 사용 설정을 확인하세요. 문제 해결을 위해 마스킹된 오류를 보관하세요 |
| 도구 호출 또는 비전 실패 | 먼저 선택한 모델이 해당 기능을 실제로 지원하는지 확인하세요. 플러그인 스위치만 토글하여 강제로 켜지 마세요 |
자체 호스팅 Dify의 요청은 해당 서버에서 전송됩니다. 브라우저에서 공식 사이트를 열 수 있다는 사실이 Dify 서버가 API에 연결할 수 있다는 의미는 아닙니다.
## 연동 지원 받기
공식 사이트의 온라인 고객 지원을 통해 Dify 버전, 플러그인 버전, 모델 ID, 오류 타임스탬프, 요청 ID, 마스킹된 오류 세부 정보를 제공하세요. 전체 키, 고객 데이터, 워크플로우의 비공개 프롬프트를 보내지 마세요.
## 검증 범위
2026-10-19에 공식 플러그인 0.0.68을 사용하여 Dify Cloud에서 Haiku 텍스트 대화와 스트리밍 호출을 완료했고 게이트웨이 로그와 대조했습니다. 내보낸 키 없는 DSL을 동일한 워크스페이스에 새 앱으로 가져왔습니다. 가져온 후 재테스트에서 업스트림 속도 제한으로 인한 503이 발생하여, 이번 라운드는 가져오기 후 실행 통과로 기록되지 않습니다.
이는 정의된 시간 창을 가진 내부 테스트이며 지속적인 가용성 보장이 아닙니다. 새 워크스페이스, 이전 Dify 버전, 도구 호출, 비전, 지식 베이스 검색은 검증되지 않았습니다. 속도 제한이 걸린 본인의 키로 첫 테스트를 완료하세요.
[공식 플러그인 소스](https://github.com/langgenius/dify-official-plugins/tree/main/models/openai_api_compatible) · [Dify 플러그인 마켓플레이스](https://marketplace.dify.ai/)
## English / Русский
**English:** Install the official OpenAI-API-compatible plugin by langgenius. Set API Base URL to `https://1zheai.com/v1`, use your own API key and an exact model ID available to your account, and select Chat mode. Test a simple conversation before adding tools or vision. Text and streaming calls were verified in Dify Cloud on 2026-10-19. DSL import into a new app in the same workspace succeeded; its subsequent run encountered an upstream-capacity 503. Fresh-workspace import and advanced capabilities remain unverified. Never share your key with support.
**Русский:** Установите официальный плагин OpenAI-API-compatible от langgenius. Укажите API Base URL `https://1zheai.com/v1`, собственный API-ключ и точный ID модели, доступной вашему аккаунту; выберите режим Chat. Сначала проверьте простой диалог, затем потоковый вывод. Текстовые и потоковые вызовы проверены в Dify Cloud 19 октября 2026 года. Импорт DSL в новое приложение того же рабочего пространства прошёл, но повторный вызов вернул 503 из-за недоступной мощности upstream. Новое рабочее пространство и расширенные функции ещё не проверены. Не отправляйте ключ службе поддержки. Доступность из конкретной сети и способы оплаты проверяются отдельно.
---
# WorkBuddy Claude API 연결
Source: https://1zheai.com/ko/docs/quickstart-workbuddy/
Markdown: https://1zheai.com/ko/docs/quickstart-workbuddy.md
---
title: "WorkBuddy Claude API 연결"
description: "WorkBuddy에서 1折AI Claude API 중계 주소, 키, 모델을 구성하는 튜토리얼로, 프로토콜 선택, 구성 예제, 검증 단계 및 일반적인 오류를 포함합니다."
headingIds: {"연결 검증 및 문제 해결":"section-1","비용 및 기타 연결 방식":"section-2"}
---
WorkBuddy의 사용자 지정 공급자 기능을 사용하여 1折AI에 연결합니다. 먼저 [API 키 생성](/ko/docs/api-keys/)을 하고 [현재 사용 가능한 모델](/ko/docs/models/)을 확인하세요. 아래의 모델 ID는 예제이므로 키 권한에 맞게 조정하세요.
공식 구성 확인 날짜: 2026-10-15. 아래 구성은 공식 문서에 따라 정리되었으며, 이 사이트의 엔드투엔드 검증은 아직 완료되지 않았습니다. 긴 작업에 사용하기 전에 짧은 질문-답변 및 도구 호출 검증을 완료하세요. OpenAI / GPT 모델이 출시되었으며, 모델 목록과 가격은 [모델 설명](/ko/docs/models/)을 참조하세요.
[공식 모델 구성](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model)에 따라: 설정 → 모델 → 모델 추가 → 사용자 지정/Custom. 이 사이트의 키와 모델 `claude-sonnet-4-6`을 입력합니다.
전체 요청 주소 구성 방식 사용: 고급 설정에서 「사용자 지정 프로토콜」을 켜고, URL에 `https://1zheai.com/v1/chat/completions`을 입력한 후 저장하고 대화 모델 선택기에서 해당 모델을 선택합니다. 공식 설명에 따르면 이 스위치를 켜면 입력한 URL을 그대로 사용하며, 경로 검증 및 자동 완성을 하지 않습니다. 끌 때는 표준 `/chat/completions`에 따라 완성됩니다. 따라서 전체 URL과 스위치는 반드시 함께 설명되어야 합니다.
여기서의 「사용자 지정 프로토콜」은 OpenAI 요청을 Anthropic 요청으로 자동 변환할 수 있다는 의미가 아니며, `/v1/messages`을 입력한 후 네이티브 Claude 프로토콜이 연결되었다고 주장할 수 없습니다. UI를 우선 사용하며, 검증되지 않은 `models.json` 수동 형식은 제공하지 않습니다. 공식 페이지에는 현재 로컬 구성 경로와 이전 `~/.codebuddy/models.json` 마이그레이션 설명이 함께 표시되므로, 이를 근거로 이전 경로를 일반적인 현재 경로로 작성하지 마세요. 화면의 도구 기능 표시도 이 사이트의 엔드투엔드 검증을 대체할 수 없습니다.
## 연결 검증 및 문제 해결
1. 구성 저장 후 다시 로드하여 현재 선택된 것이 `onezhe` 공급자 또는 추가한 사용자 지정 모델인지 확인합니다.
2. 짧은 질문 하나를 보내 응답이 반환되는지 확인한 후, 되돌릴 수 있는 작은 작업을 시도하여 도구 호출과 다중 대화를 별도로 확인합니다.
3. [호출 로그](/ko/docs/usage-logs/)를 열어 요청 시간, 모델, 상태 및 사용량을 확인합니다. 텍스트 응답이 한 번 성공했다고 해서 모든 Agent 기능이 호환된 것은 아닙니다.
4. 404가 발생하면 본 문서의 주소와 프로토콜이 맞는지 확인하고, 401이 발생하면 키 출처와 프로세스가 환경 변수를 읽었는지 확인하며, 429가 발생하면 속도 제한 정보를 확인한 후 재시도합니다. 자세한 내용은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
키는 로컬 환경 또는 도구의 자격 증명 저장소에만 저장하고, 코드 저장소, 스크린샷 또는 공개 로그에 커밋하지 마세요. 백그라운드 서비스는 터미널 환경 변수를 상속하지 않을 수 있습니다. 보조 모델, 검색 및 기타 도구에는 별도의 공급자 구성이 있을 수 있으므로 각각 확인해야 합니다.
## 비용 및 기타 연결 방식
[Claude API 실시간 가격](https://1zheai.com/en/pricing/)과 [과금 규칙](/ko/docs/pricing-explained/)을 확인하세요. 다른 클라이언트가 필요하면 [도구 연결 디렉터리](/ko/docs/integrations/)로 돌아가세요. 직접 프로그램을 작성하려면 [SDK 및 개발 가이드](/ko/docs/guides/)를 사용하세요.
---
# Chatbox 원클릭 가져오기 및 구성
Source: https://1zheai.com/ko/docs/quickstart-chatbox/
Markdown: https://1zheai.com/ko/docs/quickstart-chatbox.md
---
title: "Chatbox 원클릭 가져오기 및 구성"
description: "API Key 페이지에서 Chatbox를 가져오고 API Host, 경로, 모델, 키를 확인합니다."
headingIds: {"원클릭 가져오기":"section-1","클립보드 및 수동 구성":"section-2","문제 해결":"section-3"}
---
Chatbox 1.15.1부터 제공자 JSON 및 `chatbox://provider/import`을 지원합니다. 데스크톱 버전은 먼저 설치하고 한 번 실행해야 합니다. 웹 버전 또는 등록 프로토콜이 없는 시스템에서는 클립보드 가져오기를 사용하세요.
## 원클릭 가져오기
1. 콘솔의 **API 키**를 열어 사용할 키를 찾고 **도구 사용 → Chatbox**로 들어갑니다.
2. 이 키에서 사용 가능한 채팅 모델을 선택한 다음 **Chatbox 열기**를 클릭하여 브라우저가 앱을 열도록 허용합니다.
3. Chatbox에서 가져오기를 확인하고 제공자 주소 및 모델을 점검합니다. 동일한 이름의 구성이 이미 있는 경우 덮어쓰기 범위를 먼저 확인합니다.
4. 짧은 메시지를 하나 보내고 이 사이트의 호출 로그에서 모델과 요청 시간을 확인합니다.
## 클립보드 및 수동 구성
앱이 열리지 않으면 같은 패널에서 **Chatbox JSON**을 복사하고 Chatbox 설정의 제공자 관리에서 클립보드에서 가져오기를 선택합니다. 다른 사람에게 공유하기 전에 `settings.apiKey`을 반드시 삭제해야 합니다.
| 필드 | 값 |
| --- | --- |
| 유형 | OpenAI API compatible |
| API Host | `https://1zheai.com` |
| API Path | `/v1/chat/completions` |
| API Key | 현재 키 |
| Model ID | 현재 키에서 사용 가능한 채팅 모델 |
Host와 Path는 따로 입력하며, `/v1`을 두 필드에 동시에 추가하지 마세요. 모델이 없으면 먼저 모델 목록을 가져오거나 수동으로 추가하세요. 이미지, 임베딩, 도구 호출 등의 기능은 각각 별도로 검증해야 하며, 임의의 모델을 채팅 모델로 취급하지 마세요.
## 문제 해결
- 앱이 팝업되지 않음: 설치 및 실행 여부를 확인하고, 브라우저의 이 프로토콜 차단을 해제하거나 클립보드 가져오기를 사용하세요.
- 가져오기 후 401: 키가 유효한지, 공백이 없는지 확인하세요.
- 404: 최종 경로가 `/v1/chat/completions`인지, 중복으로 연결되지 않았는지 확인하세요.
- 모델이 존재하지 않음: 모델 목록에 정확히 있는 ID를 사용하세요. 표시 별칭으로 추측하지 마세요.
공식: [구성 가져오기 프로토콜](https://docs.chatboxai.app/guides/providers/import-config), [클라이언트 소스코드](https://github.com/chatboxai/chatbox/blob/main/src/renderer/utils/provider-config.ts).
프로토콜 및 공식 자료와 대조 확인일 2026-10-19. 이 사이트는 구성 생성 및 프런트엔드 회귀 테스트를 구현했습니다. 모든 클라이언트, 시스템, 모델에 대한 실제 추론 검증은 완료되지 않았습니다. 클라이언트 업데이트 후 다시 검증하세요. 사용자 지정 연결은 공식 협력이나 내장 추천을 의미하지 않습니다.
더 보기: [API 키](/ko/docs/api-keys/), [모델 목록](/ko/docs/models/), [호출 로그](/ko/docs/usage-logs/), [주소 설명](/ko/docs/base-url/).
---
# RikkaHub QR 코드 가져오기
Source: https://1zheai.com/ko/docs/quickstart-rikkahub/
Markdown: https://1zheai.com/ko/docs/quickstart-rikkahub.md
---
title: "RikkaHub QR 코드 가져오기"
description: "Android RikkaHub에서 QR 코드로 OpenAI 호환 제공자를 가져오고, 모델을 구성하며 문제를 해결합니다."
headingIds: {"QR 코드 구성":"section-1","수동 대체":"section-2","문제 해결":"section-3"}
---
RikkaHub는 Android AI 클라이언트입니다. 이 사이트는 `ai-provider:v1:` 공유 형식을 사용하여 로컬 QR 코드를 생성하며, 제3자 QR 코드 웹사이트를 호출하지 않습니다.
## QR 코드 구성
1. 콘솔에서 **API 키 → 도구 사용 → RikkaHub**로 이동합니다.
2. 비공개 환경에서 **가져오기 QR 코드 표시**를 클릭합니다. QR 코드는 전체 키와 동일하므로 스크린샷을 공유하면 안 됩니다.
3. RikkaHub에서 **설정 → 제공자 설정 → 가져오기**에서 QR 코드 스캔을 선택합니다. 양쪽이 같은 휴대폰에 있는 경우 클라이언트의 이미지에서 가져오기 기능을 사용하고, 가져온 후 키가 포함된 스크린샷을 삭제합니다.
4. 가져온 후 모델 목록을 가져오고, 채팅 모델을 선택하며, 짧은 메시지를 보낸 다음 이 사이트의 호출 로그에서 확인합니다.
5. 완료 후 QR 코드를 숨깁니다. 실수로 다른 사람에게 전송한 경우 해당 키를 폐기하고 새로 생성합니다.
## 수동 대체
| 필드 | 값 |
| --- | --- |
| 유형 | OpenAI |
| Base URL | `https://1zheai.com/v1` |
| Chat Completions Path | `/chat/completions` |
| API Key | 현재 키 |
가져오기는 모델 능력이나 컨텍스트 길이를 사전 설정하지 않으며, Responses 스위치도 활성화하지 않습니다. Responses가 필요한 경우 선택한 모델과 클라이언트 버전을 먼저 확인한 다음 별도로 검증합니다.
## 문제 해결
QR 코드 스캔이 실패하면 QR 코드가 완전한지, 화면이 선명한지, 클라이언트 버전을 먼저 확인합니다. 그래도 안 되면 수동 필드를 사용합니다. 모델 목록 가져오기가 실패하면 키와 주소를 확인합니다. 권한 부족은 QR 코드를 다시 스캔하는 것으로 해결할 수 없습니다.
공식 문서: [빠른 시작](https://github.com/rikkahub/docs/blob/main/quickstart.mdx), [공유 형식 구현](https://github.com/rikkahub/rikkahub/blob/master/app/src/main/java/me/rerere/rikkahub/ui/components/ui/ShareSheet.kt).
프로토콜 및 공식 자료와 대조 확인일: 2026-10-19. 이 사이트는 구성 생성 및 프런트엔드 회귀 테스트를 구현했습니다. 모든 클라이언트, 시스템 및 모델에 대한 실제 추론 검증은 완료되지 않았습니다. 클라이언트 업그레이드 후 다시 검증하십시오. 사용자 지정 연결은 공식 협력이나 내장 추천을 의미하지 않습니다.
더 보기: [API 키](/ko/docs/api-keys/), [모델 목록](/ko/docs/models/), [호출 로그](/ko/docs/usage-logs/), [주소 설명](/ko/docs/base-url/).
---
# ChatWise 사용자 지정 공급자
Source: https://1zheai.com/ko/docs/quickstart-chatwise/
Markdown: https://1zheai.com/ko/docs/quickstart-chatwise.md
---
title: "ChatWise 사용자 지정 공급자"
description: "ChatWise 설정에서 OpenAI 호환 공급자를 추가하고 키, 주소, 모델을 입력합니다."
headingIds: {"가져오기 기능 및 검증":"section-1"}
---
ChatWise의 **Settings → Providers → +**에서 사용자 지정 OpenAI-compatible 공급자를 생성합니다. 콘솔의 **API 키 → 도구 사용 → ChatWise**에서 복사 가능한 필드를 제공합니다.
| 필드 | 값 |
| --- | --- |
| API URL / Base URL | `https://1zheai.com/v1` |
| API Key | 현재 키 |
| 모델 | 모델 가져오기 후 선택하거나 모델 ID를 직접 입력 |
모델 목록 인터페이스는 `/v1/models`입니다. 현재 버전이 Base URL이 아닌 전체 요청 주소를 요구하는 경우 `https://1zheai.com/v1/chat/completions`를 입력하되, 필드 설명을 기준으로 합니다. 필요하지 않은 타사 프록시를 끄고 나서 직접 연결을 테스트하세요.
## 가져오기 기능 및 검증
공식 공개된 `chatwise://chat`은 대화를 여는 용도이며 공급자 키 가져오기에는 사용하지 않습니다. 이를 설정 가져오기 버튼처럼 위장하지 않습니다. 이미지, 추론 및 도구 기능은 모델이 실제로 지원하는 경우에 따라 설정하고, 기본적으로 모두 켜지 마세요.
짧은 메시지를 보내고 이 사이트의 로그를 확인하세요. 401은 키를 확인하고, 404는 주소 필드가 전체 경로를 기대하는지 확인하며, 모델이 없으면 현재 사용 가능한 ID를 먼저 직접 입력하세요.
공식: [사용자 지정 공급자](https://docs.chatwise.app/custom-provider), [앱 열기 프로토콜](https://docs.chatwise.app/open-from-other-apps).
프로토콜은 공식 자료와 대조하여 2026-10-19에 확인했습니다. 이 사이트는 구성 생성 및 프런트엔드 회귀 테스트를 구현했습니다. 모든 클라이언트, 시스템 및 모델에 대한 실제 추론 검증은 완료하지 않았습니다. 클라이언트 업데이트 후 다시 검증하세요. 사용자 지정 연결은 공식 협력이나 내장 추천을 의미하지 않습니다.
더 보기: [API 키](/ko/docs/api-keys/), [모델 목록](/ko/docs/models/), [호출 로그](/ko/docs/usage-logs/), [주소 설명](/ko/docs/base-url/).
---
# LibreChat 사용자 지정 엔드포인트
Source: https://1zheai.com/ko/docs/quickstart-librechat/
Markdown: https://1zheai.com/ko/docs/quickstart-librechat.md
---
title: "LibreChat 사용자 지정 엔드포인트"
description: "관리자가 LibreChat 사용자 지정 엔드포인트를 구성하고, 사용자는 각자의 API 키를 직접 입력합니다."
headingIds: {"관리자 구성":"section-1","검증 및 문제 해결":"section-2"}
---
LibreChat는 배포 관리자가 사용자 지정 엔드포인트를 허용해야 하며, 일반 사용자는 이 사이트의 버튼으로 원격 서버 구성을 덮어쓸 수 없습니다. 콘솔의 **API 키 → 도구 사용 → LibreChat**에서 구성 조각을 제공합니다.
## 관리자 구성
기존 `librechat.yaml`에 `endpoints.custom`을 병합하고, 다른 엔드포인트를 덮어쓰지 마세요:
```yaml
endpoints:
custom:
- name: '1折AI'
apiKey: user_provided
baseURL: 'https://1zheai.com/v1'
models:
default: []
fetch: true
```
현재 버전에서 요구하는 구성 검증을 적용하고 서비스를 재시작한 다음, 사용자가 LibreChat의 API 키 설정에서 자신의 키를 입력하도록 하세요. 공유 구성에는 실제 키가 포함되지 않습니다. 모델 가져오기에 실패하면 관리자가 `default`을 검증된 사용 가능한 모델 ID로 설정하고 서버의 아웃바운드 연결을 확인할 수 있습니다.
## 검증 및 문제 해결
새 엔드포인트와 모델을 선택하여 짧은 요청을 보낸 다음, 이 사이트의 호출 로그를 확인하세요. 엔드포인트가 표시되지 않으면 구성 마운트 위치와 재시작이 적용되었는지 먼저 확인하세요. 401은 사용자가 입력한 키를 확인하세요. 404는 Base URL이 전체 요청 경로가 아닌 `/v1`인지 확인하세요. 신뢰할 수 없는 공개 LibreChat 인스턴스에 키를 보관하지 마세요.
공식: [사용자 지정 엔드포인트 필드](https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/custom_endpoint).
프로토콜 및 공식 자료와 대조 확인일: 2026-10-19. 이 사이트는 구성 생성 및 프런트엔드 회귀 테스트를 구현했습니다. 모든 클라이언트, 시스템 및 모델에 대한 실제 추론 검증은 완료되지 않았습니다. 클라이언트 업그레이드 후 다시 검증하세요. 사용자 지정 연결은 공식 협업이나 내장 추천을 의미하지 않습니다.
더보기: [API 키](/ko/docs/api-keys/), [모델 목록](/ko/docs/models/), [호출 로그](/ko/docs/usage-logs/), [주소 설명](/ko/docs/base-url/).
---
# OpenClaw Claude API 연결
Source: https://1zheai.com/ko/docs/quickstart-openclaw/
Markdown: https://1zheai.com/ko/docs/quickstart-openclaw.md
---
title: "OpenClaw Claude API 연결"
description: "OpenClaw에서 1折AI Claude API 중계 주소, 키, 모델을 구성하는 튜토리얼로, 프로토콜 선택, 구성 예제, 검증 단계 및 일반적인 오류를 포함합니다."
headingIds: {"연결 검증 및 문제 해결":"section-1","비용 및 기타 연결 방법":"section-2"}
---
OpenClaw의 사용자 지정 공급자 기능을 사용하여 1折AI에 연결합니다. 먼저 [API 키 생성](/ko/docs/api-keys/)을 하고 [현재 사용 가능한 모델](/ko/docs/models/)을 확인하세요. 아래 모델 ID는 예제이므로 키 권한에 맞게 조정하세요.
공식 구성 확인 날짜: 2026-10-15. 다음 구성은 공식 문서에 따라 정리되었으며, 이 사이트의 엔드투엔드 검증은 아직 완료되지 않았습니다. 짧은 Q&A와 도구 호출 검증을 먼저 완료한 후 장기 작업에 사용하세요. OpenAI / GPT 모델이 출시되었으며, 모델 목록과 가격은 [모델 설명](/ko/docs/models/)을 참조하세요.
[사용자 지정 공급자](https://docs.openclaw.ai/gateway/config-tools/custom-providers)와 [구성 예제](https://docs.openclaw.ai/gateway/configuration-examples)에 따라 `~/.openclaw/openclaw.json`에 병합합니다:
```json
{
"agents": {
"defaults": {
"model": { "primary": "onezhe/claude-sonnet-4-6" },
"models": { "onezhe/claude-sonnet-4-6": { "alias": "1折AI Claude" } }
}
},
"models": {
"mode": "merge",
"providers": {
"onezhe": {
"baseUrl": "https://1zheai.com",
"apiKey": "${ONEZHE_API_KEY}",
"api": "anthropic-messages",
"models": [
{ "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" }
]
}
}
}
}
```
실제로 Gateway를 실행하는 프로세스가 `ONEZHE_API_KEY`을 읽을 수 있는지 확인하세요. 터미널의 환경 변수는 기존 백그라운드 서비스에 전달되지 않을 수 있습니다. [공식 Synthetic 문서](https://docs.openclaw.ai/providers/synthetic)에 따르면 Anthropic 클라이언트는 자동으로 `/v1`을 추가하므로, 여기에는 `/v1`을 포함하지 않고 전체 `/v1/messages`도 입력하지 않습니다.
Chat Completions로 전환할 때는 `baseUrl: "https://1zheai.com/v1"`과 `api: "openai-completions"`로 쌍을 교체합니다. 이름에 completions가 포함되어 있지만 이 어댑터는 `/v1/chat/completions`에 해당합니다. `openai-responses`을 잘못 선택하지 마세요. 기존 모델 허용 목록은 다른 항목을 유지하면서 새 모델을 추가해야 합니다. 예제는 비용이나 컨텍스트 매개변수를 지어내지 않았습니다. 현재 설치된 버전의 검증에 추가 메타데이터가 필요하다면, 실제 모델 기능을 먼저 확인한 후 보완하세요.
## 연결 검증 및 문제 해결
1. 구성을 저장하고 다시 로드하여 현재 선택된 공급자가 `onezhe` 공급자 또는 추가한 사용자 지정 모델인지 확인합니다.
2. 짧은 질문을 하나 보내 응답이 반환되는지 확인한 후, 되돌릴 수 있는 작은 작업을 하나 시도하여 도구 호출과 다중 턴 대화를 별도로 확인합니다.
3. [호출 로그](/ko/docs/usage-logs/)를 열어 요청 시간, 모델, 상태 및 사용량을 확인합니다. 한 번의 텍스트 응답이 성공했다고 해서 모든 Agent 기능이 호환된 것은 아닙니다.
4. 404가 발생하면 이 문서의 주소와 프로토콜이 맞는지 확인하고, 401이 발생하면 키의 출처와 프로세스가 환경 변수를 읽었는지 확인하며, 429가 발생하면 속도 제한 정보를 확인한 후 재시도합니다. 자세한 내용은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
키는 로컬 환경 또는 도구의 자격 증명 저장소에만 저장하고, 코드 저장소, 스크린샷 또는 공개 로그에 커밋하지 마세요. 백그라운드 서비스는 터미널 환경 변수를 상속하지 않을 수 있습니다. 보조 모델, 검색 및 기타 도구에도 별도의 공급자 설정이 있을 수 있으므로 각각 확인해야 합니다.
## 비용 및 기타 연결 방법
[Claude API 실시간 가격](https://1zheai.com/en/pricing/)과 [과금 규칙](/ko/docs/pricing-explained/)을 확인하세요. 다른 클라이언트가 필요하면 [도구 연결 디렉터리](/ko/docs/integrations/)로 돌아가세요. 직접 프로그램을 작성하려면 [SDK 및 개발 가이드](/ko/docs/guides/)를 사용하세요.
---
# Hermes Agent Claude API 연결
Source: https://1zheai.com/ko/docs/quickstart-hermes/
Markdown: https://1zheai.com/ko/docs/quickstart-hermes.md
---
title: "Hermes Agent Claude API 연결"
description: "Hermes Agent에서 1折AI Claude API 중계 주소, 키, 모델 설정 튜토리얼. 프로토콜 선택, 설정 예제, 검증 단계 및 일반적인 오류를 포함합니다."
headingIds: {"연결 검증 및 문제 해결":"section-1","비용 및 기타 연결 방식":"section-2"}
---
Hermes Agent의 사용자 지정 공급자 기능을 사용하여 1折AI에 연결합니다. 먼저 [API 키 생성](/ko/docs/api-keys/)을 하고 [현재 사용 가능한 모델](/ko/docs/models/)을 확인하세요. 아래 모델 ID는 예제이므로 키 권한에 맞게 조정하세요.
공식 설정 확인 날짜: 2026-10-15. 아래 설정은 공식 문서에 따라 정리되었으며, 이 사이트의 엔드투엔드 검증은 아직 완료되지 않았습니다. 짧은 질의응답과 도구 호출 검증을 먼저 완료한 후 장기 작업에 사용하세요. OpenAI / GPT 모델이 출시되었으며, 모델 목록과 가격은 [모델 설명](/ko/docs/models/)을 참조하세요.
[공식 Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)에 따라: 터미널에서 `hermes model` → Custom endpoint를 실행하고, API mode에서 `chat_completions`를 명시적으로 선택하며, Base URL에 `https://1zheai.com/v1`을 입력하고, 키와 모델을 입력합니다. ChatGPT/Codex 로그인을 선택하지 마세요. 이는 다른 연결 방식입니다.
재사용 가능한 named provider 설정, `~/.hermes/config.yaml`에 병합:
```yaml
providers:
onezhe:
api: https://1zheai.com/v1
key_env: ONEZHE_API_KEY
transport: chat_completions
default_model: claude-sonnet-4-6
model:
provider: custom:onezhe
default: claude-sonnet-4-6
```
`~/.hermes/.env`에서 로컬로 제공:
```dotenv
ONEZHE_API_KEY=sk-替换为本站密钥
```
설정 후 대화에서 `/model custom:onezhe:claude-sonnet-4-6`을 전환할 수 있습니다. `/model`는 터미널 `hermes model`로 새 provider를 생성하는 대신 사용할 수 없습니다. 공식적으로 `anthropic_messages` 전송을 지원하지만, 이 튜토리얼은 URL에 따라 프로토콜을 자동 추측하지 않기 위해 Chat Completions를 사용합니다. `OPENAI_BASE_URL`는 모든 사용자 지정 provider의 일반 설정이 아닙니다. 위의 명시적 설정을 사용해야 합니다.
## 연결 검증 및 문제 해결
1. 설정을 저장하고 다시 로드하여 현재 선택된 공급자가 `onezhe` 또는 추가한 사용자 지정 모델인지 확인합니다.
2. 짧은 질문을 보내 응답이 반환되는지 확인한 후, 취소 가능한 작은 작업을 시도하여 도구 호출과 다중 턴 대화를 별도로 확인합니다.
3. [호출 로그](/ko/docs/usage-logs/)를 열어 요청 시간, 모델, 상태 및 사용량을 확인합니다. 한 번의 텍스트 응답 성공이 모든 Agent 기능의 호환성을 의미하지는 않습니다.
4. 404가 발생하면 이 문서의 주소와 프로토콜이 일치하는지 확인하고, 401이 발생하면 키 출처와 프로세스가 환경 변수를 읽었는지 확인하며, 429가 발생하면 속도 제한 정보를 확인한 후 재시도합니다. 자세한 내용은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
키는 로컬 환경 또는 도구의 자격 증명 저장소에만 저장하며, 코드 저장소, 스크린샷 또는 공개 로그에 커밋하지 마세요. 백그라우드 서비스는 터미널 환경 변수를 상속하지 않을 수 있습니다. 보조 모델, 검색 및 기타 도구에도 별도의 공급자 설정이 있을 수 있으므로 각각 확인해야 합니다.
## 비용 및 기타 연결 방식
[Claude API 실시간 가격](https://1zheai.com/en/pricing/)과 [과금 규칙](/ko/docs/pricing-explained/)을 확인하세요. 다른 클라이언트가 필요하면 [도구 연결 카탈로그](/ko/docs/integrations/)로 돌아가세요. 직접 프로그램을 작성하려면 [SDK 및 개발 가이드](/ko/docs/guides/)를 사용하세요.
---
# CC Switch로 연결하기
Source: https://1zheai.com/ko/docs/quickstart-cc-switch/
Markdown: https://1zheai.com/ko/docs/quickstart-cc-switch.md
---
title: "CC Switch로 연결하기"
description: "CC Switch에서 사용자 지정 구성을 추가하여 1折AI를 연결하고, Claude Code에서 공급자를 원클릭으로 전환하세요. settings.json을 직접 수정할 필요가 없습니다."
headingIds: {"설치":"section-1","Claude Code에 1折AI 추가하기":"section-2","모델 목록 가져오기":"section-3","Codex":"section-4","자주 묻는 질문":"section-5"}
---
[CC Switch](https://github.com/farion1231/cc-switch) 은 Claude Code, Codex 등 명령줄 도구의 공급자 구성을 관리하는 데스크톱 도구입니다. 한 번 추가하면 공식 계정, 1折AI 및 다른 공급자 간 전환은 클릭 한 번으로 가능합니다.
## 설치
- macOS: `brew install --cask cc-switch`
- Windows / Linux: [GitHub Releases](https://github.com/farion1231/cc-switch/releases) 에서 설치 패키지를 다운로드합니다.
## Claude Code에 1折AI 추가하기
사이드바에서 **Claude Code**를 선택하고, 페이지 헤더 오른쪽의 **공급자 추가**(+ 버튼)를 클릭합니다.
1折AI는 현재 CC Switch의 사전 설정 목록에 없으므로, 목록 맨 위의 **사용자 지정 구성을** 선택합니다.
이름에 `1折AI`을 입력하고, 구성 편집 상자의 `env`을 다음과 같이 작성합니다:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://1zheai.com",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
}
}
```
모델을 동시에 고정하려면 `ANTHROPIC_MODEL` 등의 변수를 추가하세요. 작성 방법은 [Claude Code 연결](/ko/docs/quickstart-claude-code/)의 모델 매핑 절을 참조하세요.
페이지 하단의 **추가**를 클릭한 다음, 공급자 목록에서 1折AI를 활성화합니다. CC Switch는 구성을 Claude Code의 `~/.claude/settings.json`에 기록하며, Claude Code는 재시작 없이 새 공급자를 사용합니다.
Claude Code에서 `/status`을 실행하면 base URL은 `https://1zheai.com`이어야 합니다. 메시지를 한 번 더 보내고, 콘솔의 [호출 로그](/ko/docs/usage-logs/)에서 기록이 있는지 확인하세요.
CC Switch 공식 예제는 `ANTHROPIC_API_KEY`을 사용하며, 두 변수 모두 동작합니다. 우리는 `ANTHROPIC_AUTH_TOKEN`을 권장하며, 이유는 [Claude Code 연결](/ko/docs/quickstart-claude-code/)을 참조하세요.
## 모델 목록 가져오기
공급자를 편집할 때, 모델 입력 상자 옆의 **모델 목록 가져오기** 버튼은 API 키(API key)를 사용하여 `/v1/models`을 호출하고, 사용 가능한 모델을 나열한 뒤 하나를 선택하여 입력합니다.
## Codex
CC Switch는 Codex의 공급자도 관리할 수 있습니다. 이 사이트의 Base URL, API 키 및 GPT 모델 구성은 [Codex CLI 연결](/ko/docs/quickstart-codex/)을 참조하세요.
## 자주 묻는 질문
먼저 CC Switch에서 1折AI가 활성화 상태인지 확인하세요. 그다음 터미널에서 `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_AUTH_TOKEN`를 export한 적이 있는지 확인하세요. Claude Code는 settings.json을 기준으로 하지만, 수동으로 export한 이전 변수는 오인하기 쉬우므로 모두 정리하고 CC Switch에 통일하여 관리하는 것을 권장합니다.
API 키를 잘못 입력했거나 삭제된 경우입니다. API 키를 다시 복사하되, 공백이 포함되지 않도록 주의하세요.
---
# CC Provider 구성
Source: https://1zheai.com/ko/docs/quickstart-cc-provider/
Markdown: https://1zheai.com/ko/docs/quickstart-cc-provider.md
---
title: "CC Provider 구성"
description: "VS Code의 CC Provider 확장을 사용하여 사용자 지정 Anthropic 공급자를 관리합니다."
headingIds: {"구성 단계":"section-1","범위 및 문제 해결":"section-2"}
---
여기서는 **onetooken/cc-provider** VS Code 확장을 말하며, CC Switch가 아닙니다. 사용자 지정 Anthropic 호환 엔드포인트를 지원합니다.
## 구성 단계
1. 공식 저장소 링크를 출처로 하는 확장을 설치하고 공급자 패널을 엽니다.
2. 사용자 지정 공급자를 새로 만듭니다. 콘솔의 **API 키 → 도구 사용 → CC Provider**에서 해당 필드를 복사할 수 있습니다.
3. 이름은 `1折AI`, Base URL은 `https://1zheai.com`, API Token은 자신의 키를 입력합니다.
4. 현재 사용 가능한 모델에 따라 기본 모델 및 필요한 모델 슬롯을 입력합니다. 다른 공급자의 모델 ID나 `[1m]` 능력 접미사를 그대로 복사하지 마세요.
5. 적용 전에 기존 Claude Code 구성을 백업하고 변경될 필드를 확인합니다. 구성을 읽는 세션을 재시작한 후 짧은 요청으로 테스트합니다.
## 범위 및 문제 해결
이 사이트는 필드 복사를 제공하며, 이 확장의 공급자 원클릭 가져오기 프로토콜은 아직 확인하지 않았습니다. 이 클라이언트가 Claude Code 구성에 쓰는 방식은 내장 공급자 수집과 다릅니다.
401은 토큰을 확인하고, 404는 Anthropic 루트 주소에 `/v1/messages`가 잘못 입력되지 않았는지 확인하며, 모델이 존재하지 않으면 현재 키로 사용 가능한 모델로 변경합니다. 긴 작업을 사용하기 전에 요청이 이 사이트의 호출 로그에 나타나는지 확인합니다.
공식: [CC Provider](https://github.com/onetooken/cc-provider).
프로토콜은 공식 자료와 2026-10-19에 대조 확인했습니다. 이 사이트는 구성 생성 및 프런트엔드 회귀 테스트를 구현했습니다. 모든 클라이언트, 시스템 및 모델에 대한 실제 추론 검증은 완료하지 않았습니다. 클라이언트 업그레이드 후 다시 검증하세요. 사용자 지정 연결은 공식 협업이나 내장 추천을 의미하지 않습니다.
더 보기: [API 키](/ko/docs/api-keys/), [모델 목록](/ko/docs/models/), [호출 로그](/ko/docs/usage-logs/), [주소 설명](/ko/docs/base-url/).
---
# 개발 가이드
Source: https://1zheai.com/ko/docs/guides/
Markdown: https://1zheai.com/ko/docs/guides.md
---
title: "개발 가이드"
description: "SDK 또는 HTTP 접근 방식을 선택하고, 첫 요청부터 스트리밍 출력과 캐싱까지 진행합니다."
headingIds: {"연결 후 계속 다듬기":"section-1","예제에서 애플리케이션까지":"section-2"}
---
이미 코드가 있는 경우 해당 SDK부터 시작하고, 아직 기술 스택을 선택하지 않았다면 curl로 호출을 먼저 검증한 후 애플리케이션에 연결합니다.
Claude 네이티브 프로토콜을 사용하며 Python 및 TypeScript 예제를 확인합니다.OpenAI SDK를 사용하여 GPT 또는 Claude를 호출하고 모델 ID와 엔드포인트 주소를 구성합니다.HTTP 요청을 직접 확인하여 SDK 구성 차이를 배제합니다.엔드포인트, 프로토콜 및 적용 범위를 확인합니다.
## 연결 후 계속 다듬기
- [스트리밍 출력](/ko/docs/streaming/): 증분 응답과 연결 끊김을 처리합니다.
- [Prompt Caching](/ko/docs/prompt-caching/): 사용 조건과 결과 확인 방법을 파악합니다.
- [오류 코드 및 문제 해결](/ko/docs/troubleshooting/): 특정 오류를 기준으로 구성 또는 업스트림 문제를 찾습니다.
- [사용량 로그 및 대사](/ko/docs/usage-logs/): 요청 기록을 대조합니다.
기성 소프트웨어를 사용하는 경우 [도구 연결](/ko/docs/integrations/)로 바로 진행할 수 있습니다.
## 예제에서 애플리케이션까지
Python / Node.js, 환경 변수 설정부터 프로그램 실행까지.구성 오류, 일시적 장애 및 불확실한 결과를 구분합니다.주소, 키, 모델 및 프로토콜을 항목별로 검증합니다.Images 인터페이스를 사용하고 생성 결과를 저장합니다.
---
# Anthropic SDK 연동 (Python / TypeScript)
Source: https://1zheai.com/ko/docs/quickstart-anthropic-sdk/
Markdown: https://1zheai.com/ko/docs/quickstart-anthropic-sdk.md
---
title: "Anthropic SDK 연동 (Python / TypeScript)"
description: "Anthropic 공식 SDK로 1zheai 호출: base_url에 https://1zheai.com 입력, 캐시·스트리밍·도구 호출·thinking을 네이티브 지원."
headingIds: {"설치":"section-1","호출":"section-2","스트리밍 출력":"section-3","캐시를 사용한 호출":"section-4","환경 변수 사용":"section-5","자주 묻는 질문":"section-6","요청 및 응답 구조":"section-7"}
---
Anthropic 공식 SDK는 네이티브 `/v1/messages`을 사용하므로 Claude의 모든 파라미터를 그대로 사용할 수 있습니다. 변경할 부분은 `base_url`과 `api_key`뿐입니다.
## 설치
```bash title="Python"
pip install anthropic
```
```bash title="TypeScript / Node.js"
npm install @anthropic-ai/sdk
```
## 호출
```python title="Python"
import os
import anthropic
client = anthropic.Anthropic(
base_url="https://1zheai.com",
api_key=os.environ["ONEZHE_API_KEY"],
)
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(message.model)
print(message.content[0].text)
print(message.usage)
```
```typescript title="TypeScript"
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
baseURL: "https://1zheai.com",
apiKey: process.env.ONEZHE_API_KEY,
});
const message = await client.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(message.model);
console.log(message.content);
console.log(message.usage);
```
`base_url`에 루트 주소를 입력하며, `/v1`을 붙이지 마세요.
## 스트리밍 출력
```python title="Python"
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "写一首四行的诗"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```
```typescript title="TypeScript"
const stream = client.messages.stream({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "写一首四行的诗" }],
});
stream.on("text", (text) => process.stdout.write(text));
await stream.finalMessage();
```
## 캐시를 사용한 호출
길고 고정된 내용을 `system`에 넣고 `cache_control`을 추가하세요:
```python title="Python"
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": LONG_PROJECT_CONTEXT, # 每次都一样的长文本
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "根据上面的说明回答：..."}],
)
print(message.usage.cache_creation_input_tokens, message.usage.cache_read_input_tokens)
```
두 번째 호출 시 `cache_read_input_tokens`이 0보다 크면 캐시에 적중한 것입니다. 자세한 내용은 [Prompt Caching](/ko/docs/prompt-caching/)을 참조하세요.
## 환경 변수 사용
공식 SDK는 `ANTHROPIC_BASE_URL`과 `ANTHROPIC_API_KEY`을 읽으므로, 클라이언트 생성 시 파라미터를 전달하지 않아도 됩니다:
```bash
export ANTHROPIC_BASE_URL="https://1zheai.com"
export ANTHROPIC_API_KEY="sk-你的Key"
```
그런 다음 클라이언트 생성 시 파라미터를 전달하지 않습니다:
```python
client = anthropic.Anthropic() # 自动读取上面两个变量
```
이 기기에서 Claude Code도 이 두 변수를 읽는다면, 둘 다 1zheai로 전환됩니다. 보통 원하는 결과가 바로 이것입니다.
## 자주 묻는 질문
`base_url`에 `/v1`을 과도하게 입력했습니다. Anthropic SDK가 `/v1/messages`을 자동으로 조합합니다.
API 키(API key)를 확인하세요. 또한, 환경에 `ANTHROPIC_AUTH_TOKEN`(예: 이전에 Claude Code에 설정한 오래된 값)이 동시에 존재하면 SDK가 이것도 읽으므로, 오래된 값을 삭제한 후 다시 시도하세요.
## 요청 및 응답 구조
system, 콘텐츠 블록, 중지 원인을 조회해야 한다면 [Messages 인터페이스 상세](/ko/docs/api-messages/)을 확인하세요. 완전한 프로그램은 콘텐츠 블록 유형에 따라 텍스트를 읽어야 하며, 첫 번째 블록이 항상 text라고 가정하지 마세요.
---
# OpenAI SDK 연동 (Python / Node)
Source: https://1zheai.com/ko/docs/quickstart-openai-sdk/
Markdown: https://1zheai.com/ko/docs/quickstart-openai-sdk.md
---
title: "OpenAI SDK 연동 (Python / Node)"
description: "OpenAI 공식 SDK로 1折AI의 GPT 및 Claude 모델 호출: base_url과 api_key만 변경, 스트리밍 예제와 환경변수 작성법 포함."
headingIds: {"설치":"section-1","호출":"section-2","스트리밍 출력":"section-3","환경변수 사용하여 코드 변경 없이 전환":"section-4","언제 Anthropic SDK로 전환해야 하는가":"section-5","자주 묻는 질문":"section-6","Responses 및 전체 프로그램":"section-7"}
---
이미 OpenAI SDK로 작성된 코드가 있다면, 1折AI로 전환하려면 두 개의 매개변수만 변경하면 됩니다: `base_url` 및 `api_key`. 모델명에는 현재 사용 가능한 GPT 또는 Claude 모델 ID를 입력합니다.
## 설치
```bash title="Python"
pip install openai
```
```bash title="Node.js"
npm install openai
```
## 호출
```python title="Python"
import os
from openai import OpenAI
client = OpenAI(
base_url="https://1zheai.com/v1",
api_key=os.environ["ONEZHE_API_KEY"],
)
resp = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[{"role": "user", "content": "用一句话解释什么是 prompt caching"}],
)
print(resp.model)
print(resp.choices[0].message.content)
print(resp.usage)
```
```javascript title="Node.js"
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://1zheai.com/v1",
apiKey: process.env.ONEZHE_API_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-5.6-sol",
messages: [{ role: "user", content: "用一句话解释什么是 prompt caching" }],
});
console.log(resp.model);
console.log(resp.choices[0].message.content);
console.log(resp.usage);
```
`base_url` 에는 `/v1` 을 포함해야 합니다.
## 스트리밍 출력
```python title="Python"
stream = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[{"role": "user", "content": "写一首四行的诗"}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
```
```javascript title="Node.js"
const stream = await client.chat.completions.create({
model: "gpt-5.6-sol",
messages: [{ role: "user", content: "写一首四行的诗" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```
## 환경변수 사용하여 코드 변경 없이 전환
OpenAI 공식 SDK(Python 및 Node)는 `OPENAI_BASE_URL` 및 `OPENAI_API_KEY` 을 읽습니다. 코드에서 매개변수를 전달하지 않을 때, 이 두 변수를 설정하면 전환할 수 있습니다:
```bash
export OPENAI_BASE_URL="https://1zheai.com/v1"
export OPENAI_API_KEY="sk-你的Key"
```
이것은 같은 환경에서 OpenAI SDK를 사용하는 모든 프로그램에 영향을 미친다는 점에 유의하세요.
## 언제 Anthropic SDK로 전환해야 하는가
OpenAI 호환 인터페이스는 "기존 코드가 있고 모델만 변경하고 싶은" 경우에 적합합니다. Prompt Caching의 `cache_control`, extended thinking, Claude의 도구 호출 형식이 필요하다면 [Anthropic SDK](/ko/docs/quickstart-anthropic-sdk/) 를 사용하여 네이티브 인터페이스로 전환하는 것이 더 적합합니다.
## 자주 묻는 질문
`base_url` 에 `/v1` 이 빠져 있습니다. OpenAI SDK는 뒤에 `/chat/completions` 을 붙입니다.
가능합니다. OpenAI / GPT 모델이 이미 출시되었으므로, [지원되는 모델](/ko/docs/models/) 에서 귀하의 키로 호출할 수 있는 모델 ID를 사용하세요.
## Responses 및 전체 프로그램
Responses 프로토콜이 필요하면 [Responses 인터페이스](/ko/docs/api-responses/) 을 참조하세요. Python 또는 Node.js를 처음 사용한다면 [전체 예제](/ko/docs/code-examples/) 를 바로 실행할 수 있으며, 출시 전에 [타임아웃 및 제한된 재시도](/ko/docs/retries/) 를 구성하세요.
---
# curl 호출
Source: https://1zheai.com/ko/docs/quickstart-curl/
Markdown: https://1zheai.com/ko/docs/quickstart-curl.md
---
title: "curl 호출"
description: "어떤 SDK도 설치하지 않고 curl로 1折AI의 /v1/messages와 /v1/chat/completions를 호출하고, 모델 목록 조회, 캐시 테스트, 스트리밍 출력 확인하기."
headingIds: {"Anthropic 네이티브: /v1/messages":"section-1","OpenAI 호환: /v1/chat/completions":"section-2","모델 목록: /v1/models":"section-3","스트리밍 출력":"section-4","캐시 테스트":"section-5","문제 해결 시 -i 추가":"section-6"}
---
curl은 "API 키(API key)와 주소가 실제로 통하는지" 확인하는 가장 빠른 방법입니다. 아래 각 명령어는 그대로 복사해서 사용할 수 있으며, 먼저 API 키를 환경 변수에 넣으세요:
```bash
export ONEZHE_API_KEY="sk-你的Key"
```
Windows 사용자는 WSL 또는 Git Bash에서 이 명령어들을 실행하는 것을 권장합니다. PowerShell 작성법은[빠른 시작](/ko/docs/quickstart/)을 참조하세요.
## Anthropic 네이티브: /v1/messages
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 128,
"messages": [{"role": "user", "content": "ping"}]
}'
```
## OpenAI 호환: /v1/chat/completions
```bash
curl https://1zheai.com/v1/chat/completions \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"messages": [{"role": "user", "content": "ping"}]
}'
```
## 모델 목록: /v1/models
```bash
curl https://1zheai.com/v1/models \
-H "Authorization: Bearer $ONEZHE_API_KEY"
```
## 스트리밍 출력
`"stream": true`을 추가하고 `-N`으로 curl의 버퍼링을 끄면 청크별로 반환되는 내용을 볼 수 있습니다:
```bash
curl -N https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 128,
"stream": true,
"messages": [{"role": "user", "content": "从一数到五"}]
}'
```
이벤트 형식은[스트리밍 출력](/ko/docs/streaming/)을 참조하세요.
## 캐시 테스트
같은 요청을 두 번 연속으로 보냈을 때 두 번째 응답의 `usage.cache_read_input_tokens`이 0보다 크면 캐시에 적중한 것입니다. `system`의 텍스트는 모델의 최소 캐시 가능 길이에 도달해야 합니다. 전체 스크립트는[모델 및 사용량 확인](/ko/docs/verify-model/), 원리는 [Prompt Caching](/ko/docs/prompt-caching/)을 참조하세요.
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 32,
"system": [{
"type": "text",
"text": "把一段至少 512 token、每次都一样的长文本放在这里",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "ping"}]
}'
```
## 문제 해결 시 -i 추가
```bash
curl -i https://1zheai.com/v1/models -H "Authorization: Bearer $ONEZHE_API_KEY"
```
`-i`은 상태 코드와 응답 헤더를 출력합니다. 상태 코드 의미는[오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
---
# 바로 실행 가능한 코드 예제
Source: https://1zheai.com/ko/docs/code-examples/
Markdown: https://1zheai.com/ko/docs/code-examples.md
---
title: "바로 실행 가능한 코드 예제"
description: "환경 설정, 모델 선택, 오류 처리 및 실행 명령을 포함한 Python 및 Node.js의 완전한 Chat Completions 프로그램입니다."
headingIds: {"1. 환경 변수 준비":"section-1","2. 언어 선택하여 실행":"section-2","Python":"section-3","Node.js":"section-4","3. 결과 확인":"section-5","계속 확장하기":"section-6"}
---
아래 두 프로그램은 동일한 작업을 수행합니다: 환경 변수를 읽고, 비 스트리밍 텍스트 요청을 한 번 발행하며, 답변 또는 위치를 파악할 수 있는 오류를 출력합니다. 예제는 자동 재시도를 비활성화하여 단일 요청 결과를 확인하기 쉽게 합니다.
## 1. 환경 변수 준비
프로그램을 실행하는 동일한 터미널에서 설정합니다. `ONEZHE_MODEL`은 [사용 가능한 모델 목록](/ko/docs/api-models/)의 ID로 교체할 수 있습니다.
```bash title="macOS / Linux"
export ONEZHE_API_KEY="sk-你的Key"
export ONEZHE_MODEL="gpt-5.6-sol"
```
```powershell title="Windows PowerShell"
$env:ONEZHE_API_KEY = "sk-你的Key"
$env:ONEZHE_MODEL = "gpt-5.6-sol"
```
## 2. 언어 선택하여 실행
### Python
`python -m pip install openai`을 설치하고, `chat.py`로 저장한 후, `python chat.py`을 실행합니다.
```python
import os
import sys
import openai
api_key = os.environ.get("ONEZHE_API_KEY")
if not api_key:
sys.exit("请先设置 ONEZHE_API_KEY 环境变量。")
client = openai.OpenAI(
api_key=api_key,
base_url="https://1zheai.com/v1",
timeout=120.0,
max_retries=0,
)
try:
response = client.chat.completions.create(
model=os.environ.get("ONEZHE_MODEL", "gpt-5.6-sol"),
messages=[{"role": "user", "content": "用一句中文解释 DNS。"}],
)
if not response.choices:
sys.exit("响应没有 choices，请检查响应协议。")
choice = response.choices[0]
print(choice.message.content or "本次响应没有普通文本。")
print("finish_reason:", choice.finish_reason)
print("response_id:", response.id)
except openai.APIStatusError as exc:
print("HTTP:", exc.status_code, "request_id:", exc.request_id, file=sys.stderr)
print("请查看控制台日志和错误码文档；不要公开密钥。", file=sys.stderr)
sys.exit(1)
except openai.APIConnectionError:
sys.exit("连接失败或超时：检查网络与代理，再核对调用日志。")
```
### Node.js
`npm install openai`을 설치하고, `chat.mjs`로 저장한 후, `node chat.mjs`을 실행합니다. `.mjs` 확장자를 사용하면 ES Module을 바로 활성화할 수 있습니다.
```javascript
import OpenAI from "openai";
if (!process.env.ONEZHE_API_KEY) {
console.error("请先设置 ONEZHE_API_KEY 环境变量。");
process.exit(1);
}
const client = new OpenAI({
apiKey: process.env.ONEZHE_API_KEY,
baseURL: "https://1zheai.com/v1",
timeout: 120_000,
maxRetries: 0,
});
try {
const response = await client.chat.completions.create({
model: process.env.ONEZHE_MODEL || "gpt-5.6-sol",
messages: [{ role: "user", content: "用一句中文解释 DNS。" }],
});
const choice = response.choices[0];
if (!choice) throw new Error("响应没有 choices，请检查响应协议。");
console.log(choice.message.content || "本次响应没有普通文本。");
console.log("finish_reason:", choice.finish_reason);
console.log("response_id:", response.id);
} catch (error) {
if (error instanceof OpenAI.APIError) {
console.error("HTTP:", error.status, "request_id:", error.request_id);
console.error("请检查网络、控制台日志和错误码文档。");
} else {
console.error(error instanceof Error ? error.message : "未知错误");
}
process.exitCode = 1;
}
```
## 3. 결과 확인
답변과 종료 이유가 표시되어야 합니다. `finish_reason`이 `stop`이 아닌 경우, 도구 호출 또는 잘림 여부를 확인합니다. SDK의 요청 ID는 비어 있을 수 있습니다. 서버가 추적 ID를 오류 본문에 넣을 수도 있으므로, 디버깅 시 마스킹된 원본 응답에서 보완합니다.
[호출 로그](/ko/docs/usage-logs/)에서 호출을 확인합니다. 프로그램의 종료 상태와 일반 텍스트 유무만으로는 모든 비즈니스 성공 조건을 충족할 수 없으므로, 작업에 따라 구조와 내용을 확인합니다.
## 계속 확장하기
- [Chat Completions](/ko/docs/api-chat-completions/): 다중 대화 기록 및 필드 설명.
- [Messages](/ko/docs/api-messages/): Claude 네이티브 콘텐츠 블록.
- [Responses](/ko/docs/api-responses/): GPT Responses 및 스트리밍 이벤트.
- [이미지 생성](/ko/docs/api-images/): 이미지 파일 생성 및 저장.
- [타임아웃 및 재시도](/ko/docs/retries/): 출시 전 실패 처리 구성.
---
# 스트리밍 출력
Source: https://1zheai.com/ko/docs/streaming/
Markdown: https://1zheai.com/ko/docs/streaming.md
---
title: "스트리밍 출력"
description: "1折AI에서 스트리밍 출력 사용하기: Anthropic 네이티브 SSE 이벤트 시퀀스, OpenAI 호환 chunk 형식, 그리고 연결이 끊겼을 때의 처리 방법."
headingIds: {"Anthropic 네이티브":"section-1","OpenAI 호환":"section-2","스트림이 끊겼을 때":"section-3","중간에 끊겼을 때의 과금":"section-4"}
---
긴 답변은 스트리밍 출력(`"stream": true`)을 사용하면 첫 글자가 더 빨리 나오고, 단일 요청 시간이 너무 길어 중간 네트워크에서 끊기는 일도 줄어듭니다. 두 프로토콜 모두 지원되며 형식은 각각 공식과 일치합니다.
## Anthropic 네이티브
요청에 `"stream": true`을 추가하면 Server-Sent Events가 반환됩니다. 정상적인 스트림은 다음 순서로 진행됩니다([Anthropic Streaming 문서](https://platform.claude.com/docs/en/build-with-claude/streaming) 참조):
| 이벤트 | 의미 |
|---|---|
| `message_start` | 메시지 시작, 모델과 초기 `usage` 포함 |
| `content_block_start` | 콘텐츠 블록 시작(텍스트, thinking, tool_use) |
| `content_block_delta` | 콘텐츠 증분, 텍스트는 `delta.text`에 있음 |
| `content_block_stop` | 해당 콘텐츠 블록 종료 |
| `message_delta` | 메시지 수준 업데이트, `stop_reason`과 최종 출력 토큰 수 포함 |
| `message_stop` | 전체 메시지 종료 |
중간에 `ping` 이벤트가 끼어들 수 있으며 무시하면 됩니다. 오류 발생 시 `error` 이벤트를 받게 됩니다.
```bash
curl -N https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":128,"stream":true,
"messages":[{"role":"user","content":"从一数到五"}]}'
```
SDK를 사용하면 이벤트를 직접 파싱할 필요가 없습니다. [Anthropic SDK](/ko/docs/quickstart-anthropic-sdk/)의 스트리밍 예제를 참조하세요.
## OpenAI 호환
`/v1/chat/completions`에 `"stream": true`을 추가하면 `data: {...}` 형식의 chunk가 반환되며, 텍스트는 `choices[0].delta.content`에 있고 마지막은 `data: [DONE]`으로 끝납니다. SDK 예제는 [OpenAI SDK](/ko/docs/quickstart-openai-sdk/)을 참조하세요.
`usage`이 붙은 마지막 chunk는 `[DONE]` 이전에 오며, `choices`는 빈 배열입니다. `stream_options.include_usage`을 전달하지 않아도 반환됩니다. 2026-10-15에 실측한 전체 스트림:
```text
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"ok"},"finish_reason":null}]}
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}]}
data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[],"usage":{"prompt_tokens":370,"completion_tokens":4,"total_tokens":374}}
data: [DONE]
```
chunk를 처리할 때는 먼저 `choices`이 비어 있는지 확인하세요. 위의 OpenAI SDK 페이지 예제는 이미 이렇게 작성되어 있습니다.
## 스트림이 끊겼을 때
- 먼저 프록시 여부를 확인하세요: 프록시를 끄고 직접 연결해 다시 시도합니다.
- 클라이언트의 읽기 타임아웃은 모델 생성 시간보다 길어야 합니다. 긴 출력일 때는 타임아웃 설정을 늘리세요.
- `error` 이벤트의 `overloaded_error`을 받으면 몇 초 후 재시도하세요. [오류 코드와 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
## 중간에 끊겼을 때의 과금
중간에 끊긴 요청이 전액 무료인 것은 아닙니다. 끊기기 전에 이미 생성된 출력 토큰 기준으로 과금되며 호출 로그에 기록됩니다. 과금되는 출력은 클라이언트가 실제로 받은 것보다 약간 더 많을 수 있습니다. 2026-10-15에 실측한 결과, 모델이 1부터 600까지 세도록 하고 클라이언트가 4초에 끊었을 때 188줄(약 380개 출력 토큰)을 받았고, 호출 로그에 기록된 출력은 750 토큰이었습니다. 필요 없는 긴 출력은 중간에 끊는 것보다 처음부터 `max_tokens`을 작게 설정하는 편이 낫습니다.
---
# 프롬프트 캐싱 사용법과 과금
Source: https://1zheai.com/ko/docs/prompt-caching/
Markdown: https://1zheai.com/ko/docs/prompt-caching.md
---
title: "프롬프트 캐싱 사용법과 과금"
description: "1折AI에서 Claude 프롬프트 캐싱 사용법: 활성화 방법, 최소 길이, 히트 확인 방법, 히트 과금 방식, Claude Code의 캐싱 동작."
headingIds: {"결론부터":"section-1","활성화 방법":"section-2","최소 캐시 가능 길이":"section-3","히트 확인 방법":"section-4","과금 방식":"section-5","1시간 캐시":"section-6","Claude Code의 캐싱":"section-7","OpenAI 호환 인터페이스에서도 캐싱을 쓸 수 있나요?":"section-8","FAQ":"section-9"}
---
프롬프트 캐싱을 사용하면 반복해서 보내는 긴 접두사(시스템 프롬프트, 도구 정의, 긴 문서, 대화 기록)를 처음 한 번은 쓰기로, 이후에는 읽기로 과금합니다. 이 사이트에서는 캐시 읽기와 캐시 쓰기가 공식 정가 기준으로 과금되며, 입력/출력 할인이 적용되지 않습니다. 모델별 캐시 단가는 [모델 및 가격](https://1zheai.com/en/pricing/)에서 확인할 수 있습니다.
## 결론부터
- **Claude Code는 기본적으로 캐싱이 활성화되어 있습니다.** 연결하는 즉시 적용됩니다.
- 직접 코드에서 호출할 때는 캐싱할 콘텐츠 블록에 `cache_control`를 추가하고, 네이티브 `/v1/messages`를 사용하세요. OpenAI 호환 인터페이스는 현재 캐싱하지 않습니다.
- 히트 여부를 확인하려면 응답의 `usage.cache_read_input_tokens`가 0보다 큰지만 확인하면 됩니다.
- 캐시는 기본적으로 5분간 유지되며, 히트할 때마다 타이머가 초기화됩니다. `"ttl": "1h"`를 사용하면 더 높은 쓰기 단가로 1시간짜리 캐시를 쓸 수 있습니다.
## 활성화 방법
system, tools, messages의 콘텐츠 블록에 `"cache_control": {"type": "ephemeral"}`를 추가하면 해당 블록과 그 앞의 모든 내용이 캐시됩니다. 한 요청에 최대 4개의 캐시 브레이크포인트를 둘 수 있습니다.
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 256,
"system": [
{
"type": "text",
"text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
}'
```
캐싱할 접두사가 너무 짧으면 요청은 정상적으로 처리되지만 캐시되지 않으며, 오류도 발생하지 않습니다. 최소 길이는 모델마다 다르며 아래 표를 참조하세요.
## 최소 캐시 가능 길이
다음은 [Anthropic 공식 문서](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)(2026-10-14) 기준입니다:
| 최소 토큰 수 | 모델 |
|---|---|
| 512 | Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5 |
| 1,024 | Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5 |
| 2,048 | Opus 4.7 |
| 4,096 | Opus 4.6, Opus 4.5, Haiku 4.5 |
## 히트 확인 방법
같은 요청을 두 번(5분 이내 간격으로) 보내고 두 응답의 `usage`를 비교하세요. 아래는 2026-10-15에 `claude-sonnet-5-5`로 측정한 실제 결과이며, 시스템에 약 18,000 토큰의 고정 텍스트가 들어 있습니다:
```json title="第一次：写入缓存"
{
"input_tokens": 23,
"cache_creation_input_tokens": 17920,
"cache_read_input_tokens": 0,
"cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
"output_tokens": 4
}
```
```json title="第二次：命中缓存"
{
"input_tokens": 23,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 17920,
"cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
"output_tokens": 4
}
```
두 번째 `cache_read_input_tokens`가 0보다 크면 캐시가 읽히고 있는 것입니다. 각 호출의 캐시 쓰기/읽기 토큰은 [호출 로그](/ko/docs/usage-logs/)의 토큰 열에도 표시되며, 읽기는 "cache↓", 쓰기는 "↑"로 기록됩니다.
## 과금 방식
| 유형 | 공식 단가 | 1折AI 단가 |
|---|---|---|
| 캐시 쓰기 (5분) | 입력 가격 × 1.25 | 공식 정가, 할인 없음 |
| 캐시 쓰기 (1시간) | 입력 가격 × 2 | 공식 정가, 할인 없음 |
| 캐시 읽기 | 입력 가격 × 0.1 (Opus 5.5와 Sonnet 5.5는 0.05, Fable 5.1은 0.025) | 공식 정가, 할인 없음 |
5분 캐시 쓰기의 공식 가격은 보통 공식 입력 가격의 1.25배입니다. 이 사이트는 입력에는 할인이 있지만 캐싱에는 할인이 없으므로, 공식 배수만으로 캐시 읽기 한 번이 본전이라는 결론을 내릴 수 없습니다. 모델 할인율, 쓰기 비용, 반복 읽기 횟수를 비교해야 합니다. 전체 계산 예시는 [가격 및 과금](/ko/docs/pricing-explained/)에 있습니다.
### 1시간 캐시
`"ttl": "1h"`에 `cache_control`를 추가하면 캐시가 1시간 유지됩니다. 간격이 5분을 넘지만 계속 반복 사용되는 접두사에 적합합니다:
```json
"cache_control": {"type": "ephemeral", "ttl": "1h"}
```
쓰기는 공식 입력 가격의 2배로 과금되며 할인된 입력 가격이 아니고, 읽기는 5분 캐시와 동일합니다. 쓰여진 토큰은 응답의 `cache_creation.ephemeral_1h_input_tokens`에 표시됩니다. 1시간 캐시를 선택할지는 두 요청 간의 간격, 쓰기 비용, 반복 읽기 횟수를 기준으로 판단하세요.
## Claude Code의 캐싱
Claude Code는 시스템 프롬프트, 도구 정의, 대화 기록에 자동으로 캐시 브레이크포인트를 배치합니다. [공식 설명은 여기](https://code.claude.com/docs/zh-CN/prompt-caching)입니다. 히트율을 높이려면:
- 한 세션 안에서 계속 작업하세요. 중간에 오래 멈추지 마세요. 5분간 사용하지 않으면 캐시가 만료됩니다.
- 같은 세션의 이후 요청은 캐시를 읽습니다. 2026-10-15 측정 기준, 2라운드 Claude Code 작업에서 2라운드는 캐시 31,440 토큰을 읽고 115 토큰을 썼습니다. 새 세션을 시작하면 1라운드에서 접두사를 통째로 다시 써야 할 수 있으며(약 30,000 토큰 측정), 그 호출은 이후 호출보다 비쌉니다.
- 세션 중간에 `CLAUDE.md` 변경, MCP 서버 전환, 모델 변경을 피하세요. 모두 접두사를 바꿉니다.
- `DISABLE_PROMPT_CACHING=1`를 설정하지 마세요. 이 환경 변수는 모든 모델의 캐싱을 끕니다.
## OpenAI 호환 인터페이스에서도 캐싱을 쓸 수 있나요?
현재는 불가능합니다. 2026-10-15 측정 기준, `/v1/chat/completions`의 시스템 메시지에 약 3,100 토큰의 고정 텍스트를 넣고 연속으로 두 번 보냈을 때, 콘텐츠 블록에 `cache_control`를 넣었는지와 관계없이 두 응답의 `usage`는 다음과 같았습니다:
```json
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}
```
`prompt_tokens_details.cached_tokens`가 없고 호출 로그의 캐시 읽기/쓰기도 모두 0이며, 요청 전체가 입력 가격으로 과금됩니다. 캐싱이 필요한 시나리오는 `/v1/messages`(Anthropic SDK 또는 Claude Code)를 사용하세요.
## FAQ
캐시는 썼는데 다음 요청이 읽지 못했습니다. 순서대로 점검하세요: 두 요청 간격이 5분을 넘었는지, 브레이크포인트 앞 내용이 바이트 단위로 완전히 동일한지(시스템의 타임스탬프와 랜덤 ID는 매번 다르게 만듭니다), 모델을 바꿨는지, 접두사가 위의 최소 길이에 도달했는지.
각 호출의 캐시 읽기/쓰기 토큰은 호출 로그에 있으니 직접 계산할 수 있습니다: 캐시 읽기 ÷ (입력 + 캐시 쓰기 + 캐시 읽기).
---
# 타임아웃, 속도 제한 및 재시도
Source: https://1zheai.com/ko/docs/retries/
Markdown: https://1zheai.com/ko/docs/retries.md
---
title: "타임아웃, 속도 제한 및 재시도"
description: "SDK 타임아웃과 제한된 재시도를 구성하고, 재시도 가능한 오류와 구성 오류를 구분하여 중복 제출을 방지합니다."
headingIds: {"재시도해야 하는 상황":"section-1","먼저 SDK 내장 재시도 사용":"section-2","직접 재시도를 구현할 때":"section-3","충분한 디버깅 정보 기록":"section-4"}
---
구성 오류를 먼저 수정한 다음 일시적인 장애를 처리합니다. 재시도 횟수, 동시성 및 총 대기 시간을 함께 제한하여 짧은 시간 내에 동일한 실패 요청을 여러 번 반복해서 보내지 않도록 합니다.
## 재시도해야 하는 상황
| 상황 | 권장 사항 |
| --- | --- |
| 400 / 401 / 403 / 404 | 요청, 권한 또는 모델을 먼저 수정합니다. 원본 요청을 자동으로 반복하지 않습니다. |
| 429 | 응답 메시지를 확인합니다. `Retry-After`이 있는 경우 대기 시간을 따르고 동시성을 낮춥니다. |
| 500 / 502 / 503 / 504 / 529 | 제한된 재시도가 가능합니다. 지속적으로 실패하면 중단하고 요청 ID를 보고합니다. |
| 연결 실패 | DNS, 프록시 및 네트워크를 확인하고 작업이 허용하는 시간 내에서 제한된 재시도를 합니다. |
| 요청 전송 후 타임아웃 또는 연결 끊김 | 결과가 불확실할 수 있으므로 로그를 먼저 확인합니다. 업스트림이 아직 처리하지 않았다고 가정할 수 없습니다. |
클라이언트 라이브러리의 재시도 범위가 위 표와 정확히 같지 않을 수 있습니다. 어느 계층에서 재시도할지 결정하면 해당 계층에서 명시적으로 정책을 설정합니다.
## 먼저 SDK 내장 재시도 사용
Python과 Node.js의 타임아웃 단위가 다릅니다. Python은 초, Node.js는 밀리초를 사용합니다. 다음 예제는 120초 타임아웃과 최대 2회 자동 재시도를 설정합니다. 초기 연결 시 문제를 해결할 때는 0으로 변경할 수 있습니다.
```python title="Python"
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONEZHE_API_KEY"],
base_url="https://1zheai.com/v1",
timeout=120.0,
max_retries=2,
)
```
```javascript title="Node.js"
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ONEZHE_API_KEY,
baseURL: "https://1zheai.com/v1",
timeout: 120_000,
maxRetries: 2,
});
```
타임아웃 구성은 전체 비즈니스 작업의 총 소요 시간 상한이 아닙니다. 재시도와 대기로 총 소요 시간이 증가합니다. 외부에서 작업을 다시 실행하는 경우 별도의 총 마감 시간과 취소 메커니즘을 설정해야 합니다.
## 직접 재시도를 구현할 때
SDK 자동 재시도를 비활성화하여 중첩을 방지합니다. 점진적으로 증가하는 대기 간격과 무작위 지터를 사용합니다. 시도 횟수, 최대 대기 시간 및 동시성 큐를 명시적으로 제한합니다. `Retry-After`을(를) 파싱할 때 초 단위일 수도 있고 HTTP 날짜일 수도 있다는 점에 유의합니다.
부분적인 스트리밍 결과를 이미 사용자에게 표시한 경우 자동으로 처음부터 재생하여 기존 텍스트 뒤에 이어서는 안 됩니다. "미완료" 상태를 유지하고 사용자가 다시 생성하거나 계속할지 결정하게 합니다.
이미지 생성, 도구 실행 및 기타 외부 결과를 생성할 수 있는 작업은 중복 제출에 특히 주의해야 합니다. 임의의 요청 ID를 설정하면 서버가 자동으로 중복을 제거한다고 가정할 수 없습니다.
## 충분한 디버깅 정보 기록
시간, 엔드포인트, 모델, 상태 코드, 소요 시간, 시도 순서 및 서버가 반환한 요청 ID를 기록합니다. 인증 헤더와 전체 개인 프롬프트는 기록하지 않습니다. 이 정보를 [호출 로그](/ko/docs/usage-logs/)과 대조합니다.
SDK 구성은 [OpenAI Python SDK](https://github.com/openai/openai-python#retries) 및 [Node SDK](https://github.com/openai/openai-node#retries)을 참조합니다. 특정 오류는 [오류 코드 및 디버깅](/ko/docs/troubleshooting/)을 참조합니다.
---
# API 참고
Source: https://1zheai.com/ko/docs/api-reference/
Markdown: https://1zheai.com/ko/docs/api-reference.md
---
title: "API 참고"
description: "기록된 인터페이스, 요청 예제 및 프로토콜 차이를 찾아 호환 범위를 명확히 합니다."
headingIds: {"인터페이스 색인":"section-1","호환 범위":"section-2","응답 및 오류":"section-3"}
---
여기에는 현재 사이트의 인터페이스 설명과 요청 예제가 요약되어 있습니다. 사이트는 Claude 및 OpenAI / GPT 모델을 제공합니다. 모델과 도구에 따라 해당 프로토콜을 선택하십시오. 구체적인 모델은 키에서 사용 가능한 목록을 따릅니다.
## 인터페이스 색인
| 인터페이스 | 용도 | 설명 및 예제 |
| --- | --- | --- |
| `POST /v1/messages` | Anthropic 네이티브 대화 | [요청 및 응답](/ko/docs/api-messages/)、[Anthropic SDK](/ko/docs/quickstart-anthropic-sdk/)、[curl](/ko/docs/quickstart-curl/) |
| `POST /v1/chat/completions` | OpenAI 호환 대화 | [요청 및 응답](/ko/docs/api-chat-completions/)、[OpenAI SDK](/ko/docs/quickstart-openai-sdk/)、[curl](/ko/docs/quickstart-curl/) |
| `POST /v1/responses` | OpenAI Responses | [요청 및 응답](/ko/docs/api-responses/)、[Codex CLI](/ko/docs/quickstart-codex/) |
| `GET /v1/models` | 키에서 사용 가능한 모델 조회 | [목록 형식 및 조회](/ko/docs/api-models/)、[모델 선택](/ko/docs/models/) |
| `POST /v1/messages/count_tokens` | 입력 토큰 수 계산 | [인터페이스 설명](/ko/docs/base-url/) |
| `POST /v1/images/generations` | 텍스트로 이미지 생성 | [이미지 생성 연동](/ko/docs/api-images/) |
## 호환 범위
Claude 네이티브 기능은 Anthropic 연동 튜토리얼을 우선 참조하십시오. 프로토콜을 전환하기 전에 필요한 기능이 해당 튜토리얼에 설명되어 있는지 확인하십시오. 요청이 성공했다는 이유만으로 도구 호출, 캐싱 또는 장시간 작업이 지원된다고 추론하지 마십시오.
Codex는 `/v1/responses`을 사용하며, [Codex CLI 연동](/ko/docs/quickstart-codex/)을 참조하십시오. 현재 사용 가능한 모델은 [모델 설명](/ko/docs/models/) 및 키에서 실제로 반환된 목록을 따릅니다.
## 응답 및 오류
두 프로토콜의 이벤트 형식 및 스트림 중단 처리. 상태 코드와 오류 메시지로 문제를 식별.
인터페이스 상세 정보는 최소 요청, 자주 사용되는 필드, 결과 읽기 및 호환 경계를 제공합니다. 전체 매개변수는 여전히 선택한 모델의 프로토콜 문서와 결합하여 참조해야 합니다. 사이트는 아직 다운로드 가능한 전체 OpenAPI 명세를 제공하지 않습니다.
공개 카탈로그에서 확인되지 않은 Embeddings, Batch, 파일 호스팅 및 타사 전용 모델은 이 페이지의 약속 범위에 포함되지 않습니다. 이러한 기능이 필요하면 먼저 지원팀에 확인하십시오.
---
# Base URL, 인터페이스 및 인증
Source: https://1zheai.com/ko/docs/base-url/
Markdown: https://1zheai.com/ko/docs/base-url.md
---
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`을 허용해야 합니다.
---
# 사용 가능한 모델 API 조회
Source: https://1zheai.com/ko/docs/api-models/
Markdown: https://1zheai.com/ko/docs/api-models.md
---
title: "사용 가능한 모델 API 조회"
description: "GET /v1/models의 두 가지 응답 형식, 모델 ID 읽기, 그리고 모델 가시성과 실제 호출 가능성이 다른 점."
headingIds: {"OpenAI 형식":"section-1","Anthropic 형식":"section-2","조회 결과 사용 방법":"section-3","목록이 비어 있거나 모델이 없는 경우":"section-4"}
---
먼저 모델을 조회한 후 요청을 작성합니다. `GET https://1zheai.com/v1/models`은 현재 키, 그룹 및 모델 제한 하에서 볼 수 있는 모델을 반환하며, 추론 요청을 보낼 필요가 없습니다.
## OpenAI 형식
```bash
curl --fail-with-body --connect-timeout 10 --max-time 30 \
https://1zheai.com/v1/models \
-H "Authorization: Bearer $ONEZHE_API_KEY"
```
아래는 간소화된 구조 예시이며, 목록은 실제 반환값을 따릅니다:
```json
{
"object": "list",
"data": [{"id": "gpt-5.6-sol", "object": "model"}]
}
```
`jq`이 설치된 경우 요청 뒤에 `| jq -r '.data[].id'`을 추가할 수 있으며, 한 줄에 모델 ID 하나씩 표시됩니다. 공개 가격 인터페이스의 `model_name`과 여기의 `id`을 혼동하지 마세요.
## Anthropic 형식
다음 두 요청 헤더를 사용하면 동일한 경로가 Anthropic 스타일의 데이터를 반환합니다:
```bash
curl --fail-with-body https://1zheai.com/v1/models \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01"
```
`data[].id`, `data[].display_name`, `has_more`에 주목하세요. 인증 방식을 전환한 후에도 다른 응답 구조로 계속 파싱하지 마세요.
## 조회 결과 사용 방법
1. `data[].id`에서 전체 ID를 복사하고 대소문자, 하이픈 및 날짜 접미사를 그대로 유지합니다.
2. [콘솔 모델 카탈로그](https://1zheai.com/model-catalog?lng=ko)에서 해당 모델의 인터페이스 유형을 확인합니다.
3. 최소 텍스트 요청으로 검증한 후 이미지, 도구 또는 기타 매개변수를 점진적으로 추가합니다.
모델 목록은 실시간 상태 점검이 아니며 모든 매개변수 제한을 포함하지 않습니다. 모델이 보이지만 일시적으로 사용 가능한 업스트림이 없으면 요청이 실패할 수 있습니다. 공식 웹사이트의 HTTP 가용성 모니터링도 각 모델이 성공적으로 추론할 수 있음을 의미하지 않습니다.
## 목록이 비어 있거나 모델이 없는 경우
키의 모델 제한과 그룹을 확인하세요. 공개 가격 페이지에 표시된 모델이 모든 키에 열려 있는 것은 아닙니다. 401은 키 상태를 먼저 확인하고, 403은 접근 조건을 확인하세요. 자세한 단계는 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/)을 참조하세요.
모델 계열 및 선택 권장 사항은 [지원되는 모델](/ko/docs/models/)을 참조하세요.
---
# Chat Completions 대화 인터페이스
Source: https://1zheai.com/ko/docs/api-chat-completions/
Markdown: https://1zheai.com/ko/docs/api-chat-completions.md
---
title: "Chat Completions 대화 인터페이스"
description: "POST /v1/chat/completions의 최소 요청, 자주 사용하는 필드, 응답 읽기 및 다중 턴 대화 작성 방법."
headingIds: {"최소 요청":"section-1","자주 사용하는 필드":"section-2","응답 읽기":"section-3","다중 턴 대화":"section-4","스트리밍 및 다음 단계":"section-5"}
---
OpenAI 호환 클라이언트를 사용하거나 이미 `chat.completions.create` 코드가 있는 경우, 이 인터페이스부터 시작하세요. 전체 주소는 `https://1zheai.com/v1/chat/completions`이며, SDK의 Base URL은 `/v1`까지만 입력합니다.
## 최소 요청
먼저 터미널에서 `ONEZHE_API_KEY`을 사이트 키로 설정하세요. 아래 모델은 [사용 가능한 모델 목록](/ko/docs/api-models/)에 존재해야 합니다.
```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
https://1zheai.com/v1/chat/completions \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"messages": [{"role": "user", "content": "请用一句中文解释 DNS 的作用。"}]
}'
```
`--fail-with-body`은 HTTP 오류에 대해 0이 아닌 종료 코드를 반환하면서 오류 본문을 유지합니다. curl 7.76 이상이 필요합니다. 이전 버전에서는 먼저 `-i`로 상태 코드를 확인할 수 있습니다.
## 자주 사용하는 필드
| 필드 | 유형 | 사용 방법 |
| --- | --- | --- |
| `model` | string | 필수, 사이트 모델 ID를 복사하여 다른 플랫폼의 공급자 접두사를 추가하지 않습니다 |
| `messages` | array | 필수, 이번 턴의 질문과 보존할 필요가 있는 히스토리 메시지를 순서대로 전송합니다 |
| `messages[].role` | string | 일반 대화에는 `user` / `assistant`를 사용합니다. 시스템 지시 역할의 지원 여부는 모델에 따라 다릅니다 |
| `messages[].content` | string 또는 내용 블록 배열 | 순수 텍스트는 먼저 문자열을 사용합니다. 이미지 입력은 모델이 해당 내용 블록을 지원해야 합니다 |
| `stream` | boolean | `true`로 설정하면 SSE를 읽으며, 응답 전체를 하나의 JSON으로 취급하지 않습니다 |
| `temperature` | number | 선택 사항, 일부 추론 모델은 수정을 지원하지 않습니다. 먼저 생략한 뒤 항목별로 검증하세요 |
| `tools` / `tool_choice` | array / string 또는 object | 선택 사항, 모델과 업스트림 모두 지원해야 합니다. 도구의 실제 실행은 프로그램에서 수행합니다 |
출력 상한 매개변수는 모델에 따라 다릅니다. Claude의 `max_tokens`, Responses의 `max_output_tokens`, Chat Completions의 매개변수를 기계적으로 서로 교환하지 마세요. 선택한 모델의 요구 사항을 참고하고, 400 오류가 발생하면 먼저 오류 본문을 확인하세요.
## 응답 읽기
일반 텍스트 결과는 `choices[0].message.content`에 있습니다. 종료 원인은 `choices[0].finish_reason`에 있으며, 도구 호출이 반환되면 텍스트가 비어 있을 수 있으므로 `message.tool_calls`을 읽어야 합니다. 응답의 `id`, `model`, `usage`는 이번 호출을 확인하는 데 사용할 수 있습니다.
아래는 주의해야 할 구조만 표시하며, 생략된 필드와 숫자는 실제 요청 결과를 나타내지 않습니다:
```json
{
"id": "example-completion",
"object": "chat.completion",
"model": "gpt-5.6-sol",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "DNS 将域名解析为网络地址。"},
"finish_reason": "stop"
}]
}
```
## 다중 턴 대화
인터페이스는 동일한 키를 반복 사용한다고 해서 이전 턴을 자동으로 기억하지 않습니다. 보존할 히스토리를 함께 전송하세요:
```json
{
"model": "gpt-5.6-sol",
"messages": [
{"role": "user", "content": "我正在学习 DNS。"},
{"role": "assistant", "content": "我们可以从域名解析开始。"},
{"role": "user", "content": "它和 HTTP 有什么区别？"}
]
}
```
히스토리가 길수록 요청이 커집니다. 애플리케이션은 컨텍스트 제한에 따라 잘라내거나 요약하고, 도구 호출과 결과의 완전한 쌍을 유지해야 합니다.
## 스트리밍 및 다음 단계
`"stream": true`를 추가하면 텍스트 증분은 `choices[].delta.content`에서 옵니다. 일부 이벤트에는 텍스트가 없거나 `choices`이 비어 있을 수 있으므로 읽을 때 판단이 필요합니다. 자세한 내용은 [스트리밍 출력](/ko/docs/streaming/)을 참조하세요.
[Python / Node.js 전체 예제](/ko/docs/code-examples/)을 직접 실행하거나, [Responses](/ko/docs/api-responses/)로 전환할 수 있습니다. Claude 네이티브 매개변수는 [Messages](/ko/docs/api-messages/)을 참조하세요.
---
# Messages 네이티브 대화 인터페이스
Source: https://1zheai.com/ko/docs/api-messages/
Markdown: https://1zheai.com/ko/docs/api-messages.md
---
title: "Messages 네이티브 대화 인터페이스"
description: "Claude Messages의 요청 헤더, system과 messages의 차이, 콘텐츠 블록 및 종료 원인."
headingIds: {"최소 요청":"section-1","요청 구조":"section-2","콘텐츠 블록 읽기":"section-3","다중 라운드 및 스트리밍":"section-4"}
---
Claude Code, Anthropic SDK, 그리고 Claude 네이티브 콘텐츠 블록을 유지하려는 애플리케이션은 `POST https://1zheai.com/v1/messages`을 사용합니다. SDK Base URL에는 `https://1zheai.com`을 입력합니다.
## 최소 요청
먼저 사이트 키 환경 변수 `ONEZHE_API_KEY`를 설정한 다음 실행합니다:
```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 256,
"system": "请用简短的中文回答。",
"messages": [{"role": "user", "content": "什么是域名解析？"}]
}'
```
## 요청 구조
| 필드 | 타입 | 사용 방식 |
| --- | --- | --- |
| `model` | string | 필수, 키에서 사용 가능한 Claude 모델 선택 |
| `max_tokens` | integer | 필수, 출력 상한; 선택한 모델의 제한 설정과 함께 사용 |
| `messages` | array | 필수, 시간순으로 `user` 및 `assistant` 메시지 전송 |
| `system` | string 또는 콘텐츠 블록 배열 | 선택, 시스템 지시는 최상위에 두고 `role: system` 메시지는 사용하지 않음 |
| `stream` | boolean | 선택, 콘텐츠 블록 증분을 스트리밍으로 읽기 |
| `tools` | array | 선택, 도구 이름, 용도 및 입력 스키마 선언 |
`thinking`, 캐시 제어 및 beta 파라미터는 특정 모델과 업스트림 지원에 따라 다릅니다. 먼저 일반 텍스트를 검증한 다음 필요에 따라 추가하세요. 모든 모델을 동일한 파라미터 세트로 취급하지 마세요.
## 콘텐츠 블록 읽기
반환되는 `content`은 배열이며, 텍스트, 도구 요청 또는 기타 콘텐츠 블록을 동시에 포함할 수 있습니다. 조건 없이 `content[0].text`을 읽지 마세요. 예를 들어 Anthropic Python SDK 사용 시:
```python
for block in message.content:
if block.type == "text":
print(block.text)
```
여기서 `message`은 [Anthropic SDK 튜토리얼](/ko/docs/quickstart-anthropic-sdk/)의 `client.messages.create(...)`에서 가져왔습니다.
| `stop_reason` | 애플리케이션 처리 방식 |
| --- | --- |
| `end_turn` | 이번 라운드 답변 종료 |
| `max_tokens` | 출력이 상한으로 잘려 완전한 답변으로 볼 수 없음 |
| `tool_use` | 도구 요청을 확인하고 허용된 도구를 실행한 뒤 결과 반환 |
| 기타 값 | 응답을 보존하고 선택한 모델의 프로토콜에 따라 처리하며 반드시 텍스트 완료라고 가정하지 않음 |
도구 호출 루프에서는 먼저 완전한 assistant 콘텐츠 블록을 히스토리에 추가한 다음 user 콘텐츠의 `tool_result`로 반환하며, `tool_use_id`는 원래 요청에 대응해야 합니다. 도구 요청을 일반 텍스트 한 덩어리로 직접 변환하지 마세요.
## 다중 라운드 및 스트리밍
매번 보존할 히스토리를 함께 전송하세요. 인터페이스 자체는 애플리케이션을 대신해 대화를 저장하지 않습니다. 스트리밍은 `message_stop`으로 메시지 종료를 나타내며, 부분 텍스트를 받았다고 해서 요청이 이미 완료된 것은 아닙니다. 자세한 내용은 [스트리밍 출력](/ko/docs/streaming/)을 참조하세요.
프로토콜 세부 사항은 [Anthropic Messages 사용 안내](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)을 참고하세요. 사이트 확장 파라미터의 사용 가능 여부는 모델 카탈로그와 실제 응답을 따릅니다.
---
# Responses 인터페이스
Source: https://1zheai.com/ko/docs/api-responses/
Markdown: https://1zheai.com/ko/docs/api-responses.md
---
title: "Responses 인터페이스"
description: "OpenAI Responses를 통해 1折AI에 접속하여 input, output, 스트리밍 이벤트 및 호환 범위를 알아봅니다."
headingIds: {"최소 요청":"section-1","Chat Completions과의 차이":"section-2","Python SDK":"section-3","스트리밍 읽기":"section-4","호환 범위":"section-5"}
---
Codex CLI는 Responses 프로토콜을 사용합니다. 직접 애플리케이션을 작성할 때도 `POST https://1zheai.com/v1/responses`을 통해 해당 인터페이스를 지원하는 GPT 모델에 요청할 수 있습니다. OpenAI SDK Base URL에는 `https://1zheai.com/v1`을 입력합니다.
## 최소 요청
```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
https://1zheai.com/v1/responses \
-H "Authorization: Bearer $ONEZHE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"input": "用三句话解释 API 网关。",
"store": false
}'
```
실행 전에 `ONEZHE_API_KEY`을 설정하고, 모델이 [사용 가능한 목록](/ko/docs/api-models/)에 있는지 확인하세요. `store: false`은 프로토콜의 저장 옵션이며, 모든 서비스 계층에 로그나 데이터 보존이 없다는 의미가 아닙니다. 이를 근거로 개인정보 보호 약속을 추론하지 마세요.
## Chat Completions과의 차이
| 항목 | Chat Completions | Responses |
| --- | --- | --- |
| 입력 | `messages` | `input`, 문자열 또는 구조화된 입력 항목 가능 |
| 텍스트 결과 | `choices[].message.content` | `output`의 message 콘텐츠 블록 |
| SDK 텍스트 보조 속성 | choice를 직접 추출 | `response.output_text` |
| 스트리밍 텍스트 | `choices[].delta.content` | `response.output_text.delta` 이벤트 |
| 종료 판단 | `finish_reason` 및 스트림 종료 | 응답 상태 및 종료 이벤트 확인 |
`output_text`은 SDK가 제공하는 편의 속성이므로, 원시 HTTP JSON 최상위에 이 필드가 존재한다고 가정하지 마세요. HTTP를 직접 호출할 때는 `output`을 순회하여 `type: message`을 선택한 후, 해당 `content`에서 `type: output_text`의 `text`을 읽으세요.
## Python SDK
`python -m pip install openai` 설치 후:
```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONEZHE_API_KEY"],
base_url="https://1zheai.com/v1",
timeout=120.0,
max_retries=0,
)
response = client.responses.create(
model=os.environ.get("ONEZHE_MODEL", "gpt-6-astra"),
input="用三句话解释 API 网关。",
store=False,
)
print(response.output_text)
print("status:", response.status)
```
여기서 자동 재시도를 비활성화하여, 최초 접속 시 단일 요청을 추적하기 쉽게 했습니다. 출시 전에 [타임아웃 및 재시도](/ko/docs/retries/)에 따라 정책을 설정하세요.
## 스트리밍 읽기
위에서 초기화한 `client` 뒤에 사용합니다:
```python
with client.responses.create(
model=os.environ.get("ONEZHE_MODEL", "gpt-6-astra"),
input="用三句话解释 API 网关。",
store=False,
stream=True,
) as stream:
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
print("\n完成")
elif event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(f"响应未完成：{event.type}")
```
완료 이벤트를 받지 못하고 연결이 끊긴 경우, 결과를 미완료로 표시해야 하며, 이미 출력된 텍스트만으로 성공을 판단할 수 없습니다.
## 호환 범위
이 페이지는 응답 생성 및 텍스트 읽기를 다룹니다. 이를 근거로 백그라운드 작업, 과거 응답 검색, `previous_response_id`, 관리형 도구, 파일 저장소 등의 기능이 모두 사용 가능하다고 추론하지 마세요. 세션 이어가기가 필요하면 명시적 과거 입력으로 먼저 검증하고, 특정 도구가 필요하면 모델과 클라이언트별로 항목별로 검증하세요.
기성 도구 구성은 [Codex CLI](/ko/docs/quickstart-codex/)을 참조하세요. SDK 사용법은 [OpenAI Python SDK](https://github.com/openai/openai-python)을 참조하세요.
---
# 이미지 생성 연동
Source: https://1zheai.com/ko/docs/api-images/
Markdown: https://1zheai.com/ko/docs/api-images.md
---
title: "이미지 생성 연동"
description: "OpenAI Images 인터페이스를 사용해 이미지를 생성하고, Base64 결과를 저장하며, 모델 권한과 타임아웃을 문제 해결합니다."
headingIds: {"인터페이스와 준비":"section-1","이미지 하나 생성 후 저장":"section-2","파라미터 추가 전에 모델 지원 여부 확인":"section-3","자주 발생하는 문제":"section-4"}
---
본 사이트의 공개 모델 카탈로그에는 현재 `gpt-image-1.5` 및 `chatgpt-image-latest`이 나열되어 있습니다(2026-10-16 확인). 사용 전에 먼저 [키 사용 가능 모델](/ko/docs/api-models/)을 조회하고, [콘솔 모델 카탈로그](https://1zheai.com/model-catalog?lng=ko)에서 이미지 인터페이스와 파라미터를 확인하세요.
이 페이지는 OpenAI Images 프로토콜에 따라 연동 예제를 제공합니다. 이번 문서 업데이트에서는 유료 이미지 생성을 실행하지 않았으므로, 아래 예제를 모든 모델, 크기, 품질 조합이 실제로 테스트된 것으로 간주하지 마세요.
## 인터페이스와 준비
- 전체 주소: `POST https://1zheai.com/v1/images/generations`
- OpenAI SDK Base URL: `https://1zheai.com/v1`
- 본 사이트의 `ONEZHE_API_KEY` 환경 변수를 사용합니다.
- Python SDK 설치: `python -m pip install openai`.
## 이미지 하나 생성 후 저장
`generate-image.py`로 저장하고, 터미널에서 `python generate-image.py`를 실행합니다:
```python
import base64
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ONEZHE_API_KEY"],
base_url="https://1zheai.com/v1",
timeout=300.0,
max_retries=0,
)
result = client.images.generate(
model=os.environ.get("ONEZHE_IMAGE_MODEL", "gpt-image-1.5"),
prompt="一只白色陶瓷茶杯放在浅灰色桌面上，柔和自然光，无文字。",
)
if not result.data:
raise RuntimeError("响应没有图片数据，请检查错误信息与调用日志。")
item = result.data[0]
if item.b64_json:
target = Path("generated-image.png")
target.write_bytes(base64.b64decode(item.b64_json, validate=True))
print(f"图片已保存到 {target.resolve()}")
elif item.url:
print("返回的是图片地址，请及时下载：", item.url)
else:
raise RuntimeError("响应没有 b64_json 或 url。")
```
예제는 기본 출력 형식을 사용합니다. JPEG / WebP 등을 별도로 지정하는 경우 저장 시에도 해당 파일 확장자로 변경하세요. Base64 문자열을 텍스트 파일로 직접 저장한 뒤 PNG로 이름을 바꾸지 마세요.
## 파라미터 추가 전에 모델 지원 여부 확인
먼저 `model`과 `prompt`만 포함된 요청으로 검증하세요. 크기, 품질, 투명 배경, 출력 형식 등의 파라미터는 모든 이미지 모델에 공통이 아닙니다. 다른 제공업체의 모델 이름이나 고유 파라미터를 그대로 복사하지 마세요.
`data[].b64_json`이 반환되면 Base64를 디코딩하고, `data[].url`이 반환되면 즉시 다운로드하여 임시 URL을 영구 저장소로 사용하지 마세요. 애플리케이션은 결과 저장을 직접 구성해야 합니다.
## 자주 발생하는 문제
| 상황 | 문제 해결 방법 |
| --- | --- |
| 400 파라미터 미지원 | 사용자 지정 크기, 품질 등 선택적 파라미터를 제거한 뒤 항목별로 검증 |
| 403 / 404 | 이미지 모델 ID, 키 권한, 전체 인터페이스 경로 확인 |
| 대기 시간이 김 | 생성에 적절한 타임아웃을 설정하고 진행 상태를 표시하여 반복 클릭으로 중복 제출 방지 |
| 타임아웃 후 이미지 없음 | 호출 로그를 먼저 확인; 결과를 받지 못했다고 상류에서 요청을 처리하지 않았다는 의미는 아님 |
| 기존 이미지 편집 원함 | 이미지 편집은 별도의 인터페이스와 입력 방식이며, 이 페이지의 텍스트 기반 이미지 생성 예제로 대체할 수 없음 |
프로토콜 파라미터 참고: [OpenAI 이미지 생성 참조](https://developers.openai.com/api/reference/resources/images/methods/generate). 비용은 본 사이트의 실시간 모델 카탈로그 기준입니다. 재시도 전략은 [타임아웃과 재시도](/ko/docs/retries/)을 참조하세요.
---
# 계정 및 지원
Source: https://1zheai.com/ko/docs/support/
Markdown: https://1zheai.com/ko/docs/support.md
---
title: "계정 및 지원"
description: "요금과 호출 기록을 관리하고, 접속 문제를 찾으며, 필요한 디버깅 정보를 제공합니다."
headingIds: {"스토어 주문":"section-1","요금 및 계정":"section-2","호출 문제 발생 시":"section-3","셀프 서비스 조회":"section-4"}
---
## 스토어 주문
[구매 가이드](/ko/docs/store-guide/) · [주문 문제 해결](/ko/docs/store-orders/) · [거래 및 사후 규칙](/ko/docs/store-rules/)
바로 사용할 수 있는 계정, 대리 충전 및 기프트카드 관련 문제는 먼저 [내 주문](https://1zheai.com/store-orders?lng=ko)에서 상태를 확인하세요. 지원팀에 문의할 때는 주문 번호와 마스킹된 오류 정보를 제공하고, 비밀번호, 인증 코드 또는 전체 세션 정보는 보내지 마세요.
## 요금 및 계정
요금 구성과 계산 설명을 확인하세요.결제 및 사후 규칙을 조회하세요.각 호출을 찾아 요금을 대조하세요.생성, 보관 및 교체 설명을 확인하세요.
## 호출 문제 발생 시
먼저 [오류 코드 및 디버깅](/ko/docs/troubleshooting/)을 확인한 다음, [주소 및 프로토콜](/ko/docs/base-url/) 및 [도구 제한](/ko/docs/integrations/)을 대조하세요. 모델과 사용량을 확인하는 방법은 [모델 및 사용량 확인](/ko/docs/verify-model/)을 참조하세요.
여전히 도움이 필요하면 콘솔 또는 공식 웹사이트에 공개된 지원 채널을 통해 다음 정보를 제공하세요: 발생 시각 및 시간대, 도구 및 버전, 모델 ID, HTTP 상태 코드, 요청 ID(있는 경우), 마스킹된 오류 정보, 그리고 최소 요청으로 재현 가능한지 여부.
전체 API 키, 인증 헤더 또는 개인 내용이 포함된 전체 대화는 보내지 마세요.
## 셀프 서비스 조회
- [접속 FAQ](/ko/docs/faq/): 주소, 모델, 응답 읽기 및 모니터링 의미.
- [타임아웃 및 재시도](/ko/docs/retries/): 클라이언트 대기 시간 및 실패 처리 설정.
- [마이그레이션 가이드](/ko/docs/migration/): 기존 공급자에서 항목별로 전환.
---
# 가격 및 과금
Source: https://1zheai.com/ko/docs/pricing-explained/
Markdown: https://1zheai.com/ko/docs/pricing-explained.md
---
title: "가격 및 과금"
description: "Claude 입력과 출력은 모델 할인율로 과금되며, 캐시 읽기와 캐시 쓰기는 공식 원가로 과금됩니다. 분류별 과금 계산 예시로 호출 비용을 검증하세요."
headingIds: {"한 번의 호출로 얼마가 청구되나요":"section-1","계산 예시":"section-2","시스템 프롬프트 과금":"section-3","잔액 및 통화":"section-4","할인율과 비용을 검증하는 방법":"section-5","자주 묻는 질문":"section-6"}
---
**Claude 입력과 출력은 해당 모델의 할인율로 과금되며, 캐시 읽기와 캐시 쓰기는 공식 원가로 과금되어 할인이 적용되지 않습니다.** 각 모델의 단가와 할인율은[모델 및 가격](https://1zheai.com/en/pricing/)을 참조하세요. GPT, MiMo 및 이미지 생성 모델은 각각의 과금 단위와 견적을 확인하세요. 이 페이지의 토큰 계산 예시는 Claude를 대상으로 합니다.
## 한 번의 호출로 얼마가 청구되나요
각 호출은 응답 `usage`의 네 가지 토큰 유형별로 각각 과금됩니다:
```text
费用 = ( 输入 token × 输入单价
+ 缓存写入 token × 缓存写单价
+ 缓存读取 token × 缓存读单价
+ 输出 token × 输出单价 ) ÷ 1,000,000
输入单价、输出单价 = 对应官方单价 × 该模型折扣
缓存读取单价、缓存写入单价 = 对应官方原价
```
네 가지 토큰 유형은 응답의 다음과 같은 필드에 대응합니다:
| 과금 항목 | `usage` 필드 (Anthropic 네이티브) | 공식 단가 대비 입력 가격 |
|---|---|---|
| 입력 | `input_tokens` | 1× |
| 캐시 쓰기 | `cache_creation_input_tokens` | 1.25× (5분 캐시), 2× (1시간 캐시, `"ttl": "1h"`) |
| 캐시 읽기 | `cache_read_input_tokens` | 0.1× (Opus 5.5, Sonnet 5.5은 0.05×, Fable 5.1은 0.025×) |
| 출력 | `output_tokens` | 모델에 따라 다름, 가격 페이지 참조 |
캐시의 공식 배수는 [Anthropic Prompt Caching 문서](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)에서 가져왔습니다. 이 사이트의 캐시는 해당 공식 원가로 과금되며, 입력 출력 할인율을 다시 곱하지 않습니다.
1시간 캐시의 쓰기 토큰은 `cache_creation.ephemeral_1h_input_tokens`에 별도로 기록되며, 공식 입력 가격의 2배로 과금되고 입력 출력 할인율이 적용되지 않습니다. 가격 페이지에 나열된 캐시 쓰기 단가는 5분 캐시 기준입니다.
## 계산 예시
아래의 단가는 시연을 위해 임의로 가져온 정수이며 특정 모델에 해당하지 않습니다. 실제 단가는 가격 페이지를 참조하세요.
어떤 모델의 공식 단가 (백만 토큰당)가 다음과 같다고 가정합니다: 입력 $3, 출력 $15, 캐시 쓰기 $3.75, 캐시 읽기 $0.30. 한 번의 Claude Code 요청의 `usage`은 다음과 같습니다:
```json
{
"input_tokens": 2000,
"cache_creation_input_tokens": 1500,
"cache_read_input_tokens": 30000,
"output_tokens": 800
}
```
공식 가격 기준:
| 항목 | 토큰 | 공식 단가 | 공식 비용 |
|---|---|---|---|
| 입력 | 2,000 | $3 | $0.006 |
| 캐시 쓰기 | 1,500 | $3.75 | $0.005625 |
| 캐시 읽기 | 30,000 | $0.30 | $0.009 |
| 출력 | 800 | $15 | $0.012 |
| 합계 | | | $0.032625 |
이 예시 모델의 입력 출력이 공식 가격의 20% (계산 예시용일 뿐 현재 모델 가격을 나타내지 않음)라고 가정하면:
```text
输入费用 = $0.006 × 0.2 = $0.0012
输出费用 = $0.012 × 0.2 = $0.0024
缓存费用 = $0.005625 + $0.009 = $0.014625
合计 = $0.018225
```
캐시 부분은 할인이 적용되지 않으므로 공식 총 비용에 직접 입력 출력 할인율을 곱할 수 없습니다.
같은 요청에서 캐시가 적중하지 않으면 30,000 토큰은 해당 모델의 할인된 입력 가격으로 계산됩니다. 비용이 절약되는지는 모델 할인율, 캐시 쓰기 비용, 반복 읽기 횟수를 종합적으로 비교해야 하며 공식 가격만 비교해서는 안 됩니다. 구성 및 확인 방법은 [Prompt Caching](/ko/docs/prompt-caching/)을 참조하세요.
## 시스템 프롬프트 과금
Claude API는 공식 구독 계정 풀에서 제공됩니다. Claude Code를 통한 호출에는 추가 내용이 포함되지 않습니다. 다른 클라이언트 (SDK, curl 및 타사 도구)의 모든 요청에는 입력 토큰으로 과금되는 시스템 프롬프트가 포함됩니다: Sonnet 4.6은 약 350 토큰, 5.x 시리즈는 약 500 토큰. 이 부분은 직접 전송한 내용과 함께 응답 `usage`의 `input_tokens`에 포함됩니다.
2026-10-15 curl로 「Reply with just: ok」 한 문장을 보낸 실측 결과:
| 모델 | `count_tokens` 카운트 | 실제 `input_tokens` | 포함된 시스템 프롬프트 (약) |
|---|---|---|---|
| Sonnet 4.6 | 19 | 370 | 350 토큰 |
| 5.x 시리즈 | 18–19 | 510–530 | 약 500 토큰 |
- `count_tokens`는 직접 전송한 내용만 세며 이 시스템 프롬프트는 포함하지 않습니다. SDK, curl 또는 타사 도구로 비용을 추정할 때는 위 표의 수를 더하세요. Claude Code는 필요하지 않습니다.
- 호출 로그에 기록된 입력 토큰에는 이미 이 부분이 포함되어 있으므로 위의 공식으로 재계산하면 로그의 청구액과 일치합니다.
- 요청이 짧을수록 이 부분의 비중이 커지고, 긴 컨텍스트 요청에서는 비중이 매우 작습니다.
## 잔액 및 통화
- 청구는 위의 달러 계산 방식으로 계산되며 계정 잔액에서 차감됩니다. 잔액은 달러로 표시됩니다.
- 충전 원금은 달러로 입금되며 결제 처리 수수료는 별도로 청구되고 환불되지 않습니다. 사용 가능한 결제 수단과 금액 제한은 지갑 주문 페이지 기준입니다.
## 할인율과 비용을 검증하는 방법
해당 모델의 입력 출력 할인율을 먼저 확인한 다음 입력, 출력, 캐시 읽기, 캐시 쓰기를 각각 계산하세요. 각 청구 건은[호출 로그](/ko/docs/usage-logs/)에서 해당 단가로 재계산할 수 있습니다.
## 자주 묻는 질문
가장 흔한 원인은 캐시 미적중입니다: 두 요청 사이의 간격이 너무 깁니다 (기본 캐시 5분), 컨텍스트 앞부분이 변경되었거나 모델이 바뀌었습니다. 호출 로그를 열어 두 건의 캐시 읽기 토큰을 비교하면 확인할 수 있습니다.
할인이 적용되지 않습니다. 캐시 읽기와 캐시 쓰기는 공식 원가로 과금되며, 입력과 출력은 각 모델의 할인율로 과금됩니다.
Claude Code를 통한 호출에는 추가 내용이 포함되지 않습니다. 다른 클라이언트 (SDK, curl 및 타사 도구)의 모든 요청에는 입력 토큰으로 과금되는 시스템 프롬프트가 포함됩니다: Sonnet 4.6은 약 350 토큰, 5.x 시리즈는 약 500 토큰. 실측 데이터는[시스템 프롬프트 과금](#section-3)을 참조하세요.
호출 로그에서 해당 건을 찾아 네 가지 토큰 수와 가격 페이지의 단가를 위의 공식에 대입하세요. 결과는 로그의 청구액과 일치해야 합니다. 일치하지 않으면 해당 로그의 시각과 모델을 알려주세요.
---
# 사용량 로그와 대사
Source: https://1zheai.com/ko/docs/usage-logs/
Markdown: https://1zheai.com/ko/docs/usage-logs.md
---
title: "사용량 로그와 대사"
description: "1折AI 콘솔의 호출 로그에서 각 호출의 모델, 네 가지 토큰, 차감 금액을 확인하고 공식으로 한 건의 계산을 재검산합니다."
headingIds: {"어디서 확인하나":"section-1","각 로그에 포함된 내용":"section-2","한 건의 계산 대사하기":"section-3","로그로 캐시 효과 확인하기":"section-4","자체 집계와 불일치 시":"section-5"}
---
모든 호출은 호출 로그에 상세 내역 하나를 남깁니다. 이 페이지는 확인 방법과 대사 방법을 설명합니다.
## 어디서 확인하나
[콘솔](https://1zheai.com/console?lng=ko) 왼쪽 메뉴 → 「호출 로그」(주소 `https://1zheai.com/usage-logs`), 페이지 제목은 「일반 로그」입니다.
상단에서 시간 범위로 필터링할 수 있으며, 「펼치기」를 클릭하면 모델 이름, API 키 이름(「토큰 이름」), 요청 ID, 로그 유형으로도 필터링할 수 있습니다. 필터를 설정한 뒤 「검색」을 클릭합니다. 「내보내기」는 현재 필터 결과를 다운로드하여 스프레드시트에서 대사하기 쉽게 해 줍니다.
## 각 로그에 포함된 내용
| 열 | 내용 |
|---|---|
| 시간 | 요청이 발생한 시각 |
| 토큰 | 이번 호출에 사용된 API 키 이름 |
| 모델 | 실제로 호출된 모델 ID |
| 스트림 | 「스트림」 또는 「비스트림」, 그리고 출력 속도(t/s) |
| Token | 첫 번째 줄은 「입력 / 출력」 토큰입니다. 캐시가 있으면 아래에 한 줄이 더 생기며, 「캐시↓」 뒤는 캐시 읽기 토큰, 「↑」 뒤는 캐시 쓰기 토큰입니다 |
| 비용 | 이번 호출에서 차감된 USD 금액 |
| 소요 시간 | 총 소요 시간. 스트림 요청은 첫 글자 시간도 표시합니다 |
| 상세 | 이번 호출의 단가 등 상세 내역 |
게이트웨이에서 거부된 요청(API 키 무효, 잔액 부족, 모델명 오기 등)은 차감되지 않습니다. 업스트림이 오류를 반환한 요청의 비용은 0입니다. 스트림 요청이 중간에 끊긴 경우 전액 무료는 아니며, [스트림 출력](/ko/docs/streaming/)를 참조하세요.
## 한 건의 계산 대사하기
시간과 모델로 대사할 항목을 찾고, Token 열의 입력, 출력, 캐시 읽기(캐시↓), 캐시 쓰기(↑) 네 가지 수치를 기록합니다.
[가격 페이지](https://1zheai.com/en/pricing/)에서 해당 모델의 입력, 출력, 캐시 읽기, 캐시 쓰기 단가를 찾습니다(입력·출력은 모델 할인이 적용된 가격, 캐시는 공식 원가 기준).
```text
扣费 = ( 输入 × 输入单价
+ 缓存写入 × 缓存写单价
+ 缓存读取 × 缓存读单价
+ 输出 × 输出单价 ) ÷ 1,000,000
```
결과는 로그의 차감 금액과 일치해야 합니다. 반올림으로 마지막 자리에 차이가 날 수 있습니다.
일치하지 않으면 해당 로그의 시간, 모델, 스크린샷을 보내 주세요.
## 로그로 캐시 효과 확인하기
Claude Code 같은 도구에서는 대부분의 입력이 "캐시 읽기" 열에 해당해야 합니다. 연속된 여러 건이 모두 대량의 "캐시 쓰기"이고 "캐시 읽기"는 적다면 캐시가 재사용되지 않는다는 뜻입니다. 원인과 해결 방법은 [Prompt Caching](/ko/docs/prompt-caching/)을 참조하세요.
대략적인 적중률: 캐시 읽기 ÷ (입력 + 캐시 쓰기 + 캐시 읽기).
## 자체 집계와 불일치 시
- Claude Code는 Haiku급 모델로 일부 백그라운드 소규모 작업을 수행하므로, 직접 선택하지 않은 모델이 로그에 나타날 수 있습니다. [Claude Code 연동](/ko/docs/quickstart-claude-code/)의 모델 매핑을 참조하세요.
- 로그의 입력 토큰이 보낸 내용보다 수백 개 더 많은 경우: SDK, curl 또는 서드파티 도구로 호출할 때마다 요청에 시스템 프롬프트가 첨부되며 입력으로 과금됩니다(Claude Code는 첨부하지 않음). [시스템 프롬프트 과금](/ko/docs/pricing-explained/#section-3)를 참조하세요.
- 한 번의 도구 내 "대화"에 여러 번의 API 호출(도구 호출당 한 라운드)이 대응될 수 있으며, 로그는 API 호출 단위로 기록됩니다.
---
# 충전, 환불 및 세금계산서
Source: https://1zheai.com/ko/docs/billing/
Markdown: https://1zheai.com/ko/docs/billing.md
---
title: "충전, 환불 및 세금계산서"
description: "1折AI 충전 방법, 최소 금액, 지원하는 결제 수단, 7일 미사용 잔액 환불 규칙, 그리고 각 결제 수단으로 발행 가능한 세금계산서에 대해 안내합니다."
headingIds: {"충전":"section-1","API 잔액 환불":"section-2","세금계산서":"section-3","자주 묻는 질문":"section-4"}
---
이 페이지는 API 계정 잔액에 대해 설명합니다. 먼저 충전하고, 호출 시 사용량에 따라 차감됩니다. AI 계정 상품은 상품 사양에 따라 구매하며, A/S는 [계정 쇼핑몰](https://1zheai.com/en/store/)을 참고하세요. 본 페이지의 API 잔액 환불 규칙은 적용되지 않습니다.
본 문서의 잔액 환불 규칙은 모델 API 충전에 적용됩니다. 바로 사용할 수 있는 계정, 대리 충전 및 기프트카드 주문은 [쇼핑몰 거래 및 A/S 규칙](/ko/docs/store-rules/)을 확인하세요. API의 7일 규칙이 직접 적용되지 않습니다.
## 충전
| 항목 | 설명 |
|---|---|
| 금액 제한 | 지갑 주문 페이지 기준 |
| 결제 수단 | WeChat Pay, Alipay, Stripe(카드), USDT |
| 진입 경로 | [콘솔](https://1zheai.com/console?lng=ko) 왼쪽 메뉴 「지갑」→「자금 추가」 |
| 차감 방식 | Claude 입력/출력은 모델 할인율, 캐시는 공식 정가 기준; 기타 모델은 해당 견적에 따라, [가격 및 과금](/ko/docs/pricing-explained/) 참고 |
충전 원금은 USD로 입금되며, 결제 처리 서비스 수수료는 별도 청구되고 환불되지 않습니다.
## API 잔액 환불
**충전 후 7일 이내에 미사용 원금을 원래 결제 수단으로 환불 신청할 수 있습니다. 이미 사용한 부분과 결제 처리 서비스 수수료는 환불되지 않습니다.**
호출 로그에서 해당 충전 이후의 소비를 확인하고, 지갑의 환불 가능 미사용 원금을 기준으로 합니다. 결제 처리 서비스 수수료는 환불 가능 원금에 포함되지 않습니다.
support@1zheai.com으로 이메일을 보내 계정, 충전 시각 및 결제 수단을 명시하세요.
처음 사용하는 경우, 지갑에서 허용하는 금액으로 먼저 충전한 뒤 [모델 및 사용량 확인](/ko/docs/verify-model/)에 따라 점검을 실행하고, 실제 작업에서 며칠 사용해 보세요. 7일 이내에 미사용 원금을 원래 결제 수단으로 환불 신청할 수 있으며, 결제 처리 서비스 수수료는 환불되지 않습니다.
## 세금계산서
| 결제 수단 | 발행 가능 항목 |
|---|---|
| WeChat Pay / Alipay | 세금계산서 발행 가능, 결제 금액의 6% 추가 청구 |
| Stripe(카드) | Stripe invoice(영문) |
| USDT | 세금계산서 미제공 |
세금계산서 발행, 기업 구매 및 법인 계좌 이체는 support@1zheai.com으로 이메일을 보내 문의하세요.
## 자주 묻는 질문
금액 제한은 지갑 주문 페이지 기준입니다. 결제 전에 충전 원금, 결제 처리 서비스 수수료 및 입금 금액을 확인하세요.
잔액이 모두 소진되면 요청이 HTTP 403으로 반환되며, 응답 본문에는 `Insufficient user quota`이 포함됩니다(`/v1/messages`에서 `error.type`은 `billing_error`, `/v1/chat/completions`에서는 `insufficient_quota`). 거부된 요청은 과금되지 않으며, 충전 입금 후 계속 사용할 수 있습니다.
Claude Code를 통한 호출에는 추가 내용이 첨부되지 않습니다. 기타 클라이언트(SDK, curl 및 서드파티 도구)의 모든 요청에는 시스템 프롬프트가 첨부되며, 입력 토큰 기준으로 과금됩니다: Sonnet 4.6은 약 350 토큰, 5.x 시리즈는 약 500 토큰. 설명 및 실측 데이터는 [시스템 프롬프트 과금](/ko/docs/pricing-explained/#section-3)을 참고하세요.
API 잔액 환불 규칙은 충전 후 7일 이내의 미사용 원금이며, 이미 사용한 부분과 결제 처리 서비스 수수료는 환불되지 않습니다. 7일이 초과된 경우 별도로 연락하여 설명해 주세요.
---
# 모델 및 사용량 검증
Source: https://1zheai.com/ko/docs/verify-model/
Markdown: https://1zheai.com/ko/docs/verify-model.md
---
title: "모델 및 사용량 검증"
description: "호출 로그와 다섯 가지 검사를 사용하여 각 호출의 모델, 토큰 사용량, 비용을 검증합니다."
headingIds: {"호출 로그":"section-1","다섯 가지 검사":"section-2","스크립트로 처음 네 가지 검사 완료하기":"section-3","thinking 블록":"section-4","불일치가 발견될 때":"section-5","자주 묻는 질문":"section-6"}
---
## 호출 로그
모든 호출은 콘솔의 [호출 로그](/ko/docs/usage-logs/)에 기록되며, 모델, 입력, 출력, 캐시 읽기, 캐시 쓰기 토큰 사용량과 비용이 나열됩니다.
## 다섯 가지 검사
다음 검사는 Anthropic API의 공개 형식과 비교하여 반환된 필드와 형식의 차이를 감지합니다.
| 검사 | 예상 결과 | 주의할 점 |
|---|---|---|
| 1. 반환된 `model` 필드 | 요청한 모델 ID와 일치 | 다른 모델 이름이 반환되거나 필드가 없음 |
| 2. 캐시 읽기 | 캐시 조건을 충족하는 동일한 요청을 캐시 유효 기간 내에 두 번 전송; 두 번째 `cache_read_input_tokens`이 0보다 큼 | 항상 0이거나 `usage`에 캐시 필드가 없음 |
| 3. 도구 호출 ID | `tool_use` 블록의 `id`이 `toolu_`으로 시작 | 다른 형식이거나 모델이 요구대로 도구를 호출하지 않음 |
| 4. 스트리밍 이벤트 순서 | `message_start`, `content_block_start`, `content_block_delta`, `message_delta`, `message_stop`이 순서대로 나타남 | OpenAI 형식의 `data:` 블록만 있거나 이벤트가 누락되거나 순서가 다름 |
| 5. 실제 작업 비교 | 고정된 작업을 사용하여 결과를 공식 API 또는 기타 신뢰할 수 있는 출처와 비교 | 결과가 눈에 띄게 나쁘거나, 비정상적인 거부, 자주 잘림 |
이 검사들은 필드와 형식의 차이만 감지할 수 있으며, 실제 사용 중인 모델을 단독으로 확인할 수는 없습니다. `model` 필드는 재작성될 수 있고, 형식은 모방될 수 있습니다.
## 스크립트로 처음 네 가지 검사 완료하기
`bash`, `curl`, `jq`이 필요합니다. 스크립트는 다섯 번의 작은 호출을 수행하며, 그중 하나는 약 18,000 토큰을 캐시에 기록하고 정상 가격으로 과금됩니다.
```bash title="verify.sh"
#!/usr/bin/env bash
# 用法：ONEZHE_API_KEY=sk-你的API密钥 bash verify.sh [模型ID]
set -euo pipefail
BASE="https://1zheai.com"
MODEL="${1:-claude-sonnet-5-5}"
H=(-H "x-api-key: $ONEZHE_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json")
echo "== 1. model 字段"
curl -s "$BASE/v1/messages" "${H[@]}" \
-d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:16,messages:[{role:"user",content:"ping"}]}')" \
| jq 'if .error then .error else {id, model, usage} end'
echo "== 2. 缓存：同一请求发两次，看第二次的 cache_read_input_tokens"
LONG=$(printf '这是一段用来测试缓存的固定文本，内容不重要，长度够就行。%.0s' {1..600})
BODY=$(jq -n --arg m "$MODEL" --arg t "$LONG" '{model:$m,max_tokens:16,
system:[{type:"text",text:$t,cache_control:{type:"ephemeral"}}],
messages:[{role:"user",content:"ping"}]}')
for i in 1 2; do
curl -s "$BASE/v1/messages" "${H[@]}" -d "$BODY" | jq -c 'if .error then .error else .usage end'
done
echo "== 3. 工具调用 ID"
curl -s "$BASE/v1/messages" "${H[@]}" \
-d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:256,
tools:[{name:"get_weather",description:"查询城市天气",
input_schema:{type:"object",properties:{city:{type:"string"}},required:["city"]}}],
tool_choice:{type:"auto"},
messages:[{role:"user",content:"北京今天天气怎么样"}]}')" \
| jq -r 'if .error then .error.message else (.content[]? | select(.type=="tool_use") | .id) end'
echo "== 4. 流式事件序列"
curl -sN "$BASE/v1/messages" "${H[@]}" \
-d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:32,stream:true,messages:[{role:"user",content:"数到三"}]}')" \
| grep '^event:' | uniq
```
검사 3은 `tool_choice: auto`을 사용합니다. Sonnet 5.5와 같은 5.x 모델은 도구 사양 강제(`{"type":"tool"}` 또는 `{"type":"any"}`)를 지원하지 않으며 400 `does not support forced tool_choice`을 반환합니다.
2026-10-15에 `claude-sonnet-5-5`으로 테스트한 결과는 다음과 같습니다(검사 1은 핵심 필드만 유지):
```text
== 1. model 字段
{
"id": "msg_011Cg3Esh8zeEdLeXAPVALKe",
"model": "claude-sonnet-5-5",
"usage": {
"input_tokens": 518,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 12,
...
}
}
== 2. 缓存：同一请求发两次，看第二次的 cache_read_input_tokens
{"input_tokens":23,"cache_creation_input_tokens":17920,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":17920,"ephemeral_1h_input_tokens":0},"output_tokens":4,"output_tokens_details":{"thinking_tokens":0},"service_tier":"standard","inference_geo":"global"}
{"input_tokens":23,"cache_creation_input_tokens":0,"cache_read_input_tokens":17920,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":4,"output_tokens_details":{"thinking_tokens":0},"service_tier":"standard","inference_geo":"global"}
== 3. 工具调用 ID
toolu_01UPsdyKX8M9fJTTkDoSKHXA
== 4. 流式事件序列
event: message_start
event: content_block_start
event: ping
event: content_block_delta
event: content_block_stop
event: message_delta
event: message_stop
```
`ping` 이벤트가 나타나는지, 어디에 나타나는지는 고정되어 있지 않으며 판단에 영향을 주지 않습니다.
## thinking 블록
thinking이 활성화되면 반환되는 `thinking` 블록에는 `signature` 필드가 포함되며, 이는 형식 검사로도 사용할 수 있습니다. 5.x 모델의 구문은 4.x와 다르며, 2026-10-15에 테스트했습니다:
| 모델 | `thinking` 매개변수 | 결과 |
|---|---|---|
| `claude-sonnet-4-6` | `{"type":"enabled","budget_tokens":1024}` | thinking 텍스트와 `signature`이 포함된 `thinking` 블록 반환 |
| `claude-sonnet-5` | `{"type":"enabled","budget_tokens":1024}` 또는 `{"type":"adaptive"}` | 둘 다 작동 |
| `claude-sonnet-5-5` | `{"type":"adaptive"}` | 작동; `enabled`을 전달하면 400 반환, adaptive만 지원함을 의미 |
5.x 모델의 `thinking` 블록은 기본적으로 `signature`만 포함하며 thinking 텍스트는 빈 문자열입니다. thinking 요약을 보려면 `"display": "summarized"`을 추가하세요:
```json
"thinking": {"type": "adaptive", "display": "summarized"}
```
제3자 감지 웹사이트를 사용할 때는 전용 API 키를 생성하고 테스트 후 삭제하는 것이 좋습니다.
## 불일치가 발견될 때
support@1zheai.com으로 요청 시각, 모델 ID, 전체 응답 내용(API 키 제거), 해당 검사 항목을 포함하여 이메일을 보내세요. 응답 내용이나 오류 메시지의 request id는 이 호출을 찾는 데 도움이 됩니다.
## 자주 묻는 질문
신뢰할 수 없습니다. 모델의 자기소개는 시스템 프롬프트의 영향을 받으며, 특정 프롬프트에서는 자신의 버전을 잘못 답할 수 있습니다. 반환된 필드와 이벤트 형식을 확인하는 것이 더 유용합니다.
Claude Code는 일부 백그라운드 작업에 Haiku 모델을 사용하며, 해당 기록이 호출 로그에 나타납니다. 이러한 작업에 사용할 모델을 지정하려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 환경 변수를 사용할 수 있습니다. [Claude Code 연동](/ko/docs/quickstart-claude-code/)을 참조하세요. Claude Code를 사용하지 않을 때 이러한 현상이 발생하면 요청 시각을 support@1zheai.com으로 보내주세요.
---
# 오류 코드와 문제 해결
Source: https://1zheai.com/ko/docs/troubleshooting/
Markdown: https://1zheai.com/ko/docs/troubleshooting.md
---
title: "오류 코드와 문제 해결"
description: "1折AI를 호출할 때 401, 404, 429, 529, 5xx, 타임아웃 및 Claude Code 오류가 발생할 때의 원인과 해결 방법."
headingIds: {"문제 해결 순서":"section-1","오류 코드 빠른 참조":"section-2","실제 측정 응답":"section-3","증상별 문제 해결":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 너무 많은 요청":"section-8","529 / overloaded_error":"section-9","타임아웃, 스트리밍 중간에 끊김":"section-10","Claude Code: 로그인 화면으로 바로 진입":"section-11","Claude Code: Extra inputs are not permitted / context_management가 400 오류":"section-12","잔액은 충분한데 호출 실패":"section-13","제한된 재시도와 피드백 템플릿":"section-14","그래도 해결되지 않으면":"section-15"}
---
아래 체크리스트를 순서대로 확인해 보세요. 대부분의 문제는 앞의 세 단계에서 찾을 수 있습니다.
## 문제 해결 순서
1. **주소**: Anthropic 계열 도구에는 `https://1zheai.com`을, OpenAI 계열에는 `https://1zheai.com/v1`을 입력합니다. [Base URL 및 인증](/ko/docs/base-url/)을 참조하세요.
2. **API 키(API key)**: 완전한지(불필요한 공백, 줄바꿈 없음), 삭제되지 않았는지, 올바른 필드에 입력했는지 확인합니다.
3. **잔액**: 콘솔에서 잔액이 충분한지 확인합니다.
4. **모델 ID**: [지원 모델](/ko/docs/models/) 목록과 완전히 일치하는지 확인합니다.
5. **네트워크**: 프록시를 끄고 직접 연결로 다시 시도합니다.
6. **그래도 안 되면**: 최소한의 curl 재현 요청(아래 참조)을 만들어 응답과 시간을 보내주세요.
```bash title="最小复现"
curl -i https://1zheai.com/v1/messages \
-H "x-api-key: sk-你的Key" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
```
`-i`은(는) 상태 코드와 응답 헤더를 함께 출력하므로 문제 해결에 유용합니다.
## 오류 코드 빠른 참조
| 상태 코드 | 흔한 원인 | 조치 |
|---|---|---|
| 400 | 요청 본문 문제: 매개변수명 오류, 필드 타입 오류, `max_tokens`이(가) 모델 상한 초과, 상위에서 인식하지 못하는 beta 필드 포함 | `message`에서 지적된 필드를 확인; Claude Code의 경우 아래 "Extra inputs are not permitted" 참조 |
| 401 | API 키가 유효하지 않음, 삭제됨, 비활성화됨, 만료됨, 자체 한도 소진, 또는 누락되거나 잘못된 헤더에 배치됨 | 응답은 모두 `Invalid token`이므로 항목별로 확인; Anthropic 네이티브는 `x-api-key` 또는 `Authorization: Bearer` 사용 |
| 403 | 계정 잔액 부족(`billing_error` / `insufficient_quota`); 이 API 키로 해당 모델이 활성화되지 않음; 요청 IP가 이 API 키의 화이트리스트에 없음(모두 `permission_error`) | 충전하거나, 「API 키」 페이지에서 이 API 키의 모델 제한 및 IP 화이트리스트를 편집 |
| 404 | 경로가 잘못되었거나, 모델이 존재하지 않음 / 현재 사용 불가 | `Invalid URL`에서 주소 확인; `not_found_error` / `model_not_found`에서 모델 ID 및 사용 가능 목록 확인 |
| 413 | 요청 본문이 너무 큼 | 한 번에 전송하는 내용을 줄이고, 큰 파일은 분할 |
| 429 | 상위에서 일시적 속도 제한. 현재 API 키에 속도 제한을 두지 않음 | 잠시 후 재시도, 배치 작업은 지수 백오프 추가 |
| 503 | 모델은 존재하지만 일시적으로 건강한 상위 서비스가 없거나, 서비스 일시 장애 | 잠시 후 재시도; 지속 실패 시 요청 ID를 제공하여 지원팀에 문의 |
| 500 / 502 | 게이트웨이 또는 상위 일시 장애 | 잠시 후 재시도; 지속 발생 시 support@1zheai.com으로 이메일 발송 |
| 504 | 요청 타임아웃 | 긴 출력은 스트리밍 사용; 클라이언트 타임아웃 증가 |
| 529 | 상위 Anthropic 과부하(`overloaded_error`) | 몇 초 기다렸다가 재시도하거나, 일시적으로 다른 모델로 전환 |
Anthropic 공식 오류 유형(`invalid_request_error`, `authentication_error`, `rate_limit_error`, `overloaded_error` 등)의 전체 의미는[공식 Errors 문서](https://platform.claude.com/docs/en/api/errors)을 참조하세요.
상위에서 반환된 오류는 상태 코드와 `message`을(를) 그대로 전달하며, `message` 끝에 이번 요청의 request id를 추가합니다. `/v1/messages`을(를) 사용하면 외부는 공식의 `{"type":"error","error":{...}}` 구조이고, `error.type`은(는) 상태 코드에 따라 공식 유형을 채웁니다. `/v1/chat/completions`을(를) 사용하면 OpenAI의 `{"error":{...}}` 구조입니다.
## 실제 측정 응답
아래는 2026-10-15에 `/v1/messages`에 대해 실제 측정한 응답입니다. `/v1/chat/completions`을(를) 사용하면 내용은 동일하되, 외부에 `"type":"error"`이(가) 없고, `error`에 `code` 필드가 하나 더 있습니다.
```json title="401 API 密钥无效、禁用、过期或额度用完"
{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}
```
```json title="403 账户余额不足"
{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}
```
```json title="403 API 密钥没开通该模型"
{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}
```
```json title="403 IP 不在白名单"
{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}
```
```json title="400 上游参数错误"
{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}
```
```json title="404 路径不存在"
{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}
```
모델이 존재하지 않거나 사용 불가할 때의 404 설명은[지원 모델](/ko/docs/models/)을 참조하세요. 응답의 request id는 이번 요청에 해당하며, 문제 제보 시 함께 첨부해 주세요.
## 증상별 문제 해결
### 401 / Invalid token
- API 키 복사 시 공백이나 줄바꿈이 추가됨, 다시 복사합니다.
- API 키가 콘솔에서 삭제되었거나 비활성화되었거나, 만료되었거나, 자체 한도가 소진됨. 이 경우들의 응답은 모두 동일한 `Invalid token`입니다.
- Claude Code에서 `ANTHROPIC_API_KEY`과(와) `ANTHROPIC_AUTH_TOKEN`을(를) 동시에 설정했고 그중 하나가 이전 값인 경우: 둘 중 하나만 남기고, `ANTHROPIC_AUTH_TOKEN`을(를) 권장합니다.
- `settings.json`의 `env`은(는) 터미널에서 export한 동일한 이름의 변수를 덮어쓰므로, 터미널 변수를 변경해도 반영되지 않을 때는 `~/.claude/settings.json`을(를) 확인합니다.
### 404 / Invalid URL
먼저 오류 유형을 확인합니다: `not_found_error` 또는 `model_not_found`이면 [모델 ID 및 사용 가능 목록](/ko/docs/models/)을(를) 확인합니다. `Invalid URL`이면 `/v1`을(를) 확인합니다: OpenAI SDK, Cursor, Cline(OpenAI Compatible)은 `https://1zheai.com/v1`에 입력해야 하고, Claude Code와 Anthropic SDK는 `https://1zheai.com`만 입력하며, `/v1`을(를) 입력하면 `/v1/v1/messages`이(가) 됩니다.
### 403 / error code: 1010
응답에 `error code: 1010` 이 한 줄만 있고 JSON이 없으면, 요청이 게이트웨이 도달 전에 차단된 것입니다. 현재 Python 표준 라이브러리 `urllib`로 직접 요청을 보낼 때 발생하는 것으로 알려져 있습니다(기본 User-Agent는 `Python-urllib/3.x`). 요청 헤더에 자체 `User-Agent`을(를) 추가하거나, 공식 SDK, `requests`, `httpx`로 전환합니다.
### 429 너무 많은 요청
현재 API 키에 속도 제한을 두지 않습니다. 429를 받으면 보통 상위 부하가 높은 것이므로 잠시 후 재시도하면 됩니다. 배치 작업은 지수 백오프를 권장합니다: 실패 후 일정 시간 기다렸다가 재시도하고, 매번 대기 시간을 두 배로 늘리며, 자체적으로 큐로 동시성을 제어합니다.
### 529 / overloaded_error
상위 Anthropic이 일시적으로 과부하 상태이며, API 키나 잔액과는 무관합니다. 몇 초 기다렸다가 재시도하거나, 급할 경우 동일 계열의 다른 모델로 일시 전환합니다.
### 타임아웃, 스트리밍 중간에 끊김
- 긴 답변은 가능하면 스트리밍(`"stream": true`)을 사용하며, 중간 네트워크 장비에 의해 끊기지 않습니다.
- Claude Code는 `API_TIMEOUT_MS`로 타임아웃을 늘릴 수 있으며, 기본값은 600000(10분)입니다.
- 프록시를 켜둔 경우 먼저 프록시를 끄고 시도해 보세요. 많은 끊김은 프록시 노드에서 발생합니다.
### Claude Code: 로그인 화면으로 바로 진입
Claude Code가 API 키를 읽지 못한 것입니다. Claude Code에서 `/status`을(를) 실행하여 base URL과 자격 증명 출처 두 줄을 확인합니다. 비어 있으면 [Claude Code 연결](/ko/docs/quickstart-claude-code/)에서 환경 변수나 `settings.json`을(를) 확인합니다.
### Claude Code: Extra inputs are not permitted / context_management가 400 오류
Claude Code는 요청에 실험적인 beta 필드를 포함하며, 엄격한 상위가 인식하지 못하면 400 오류가 발생합니다. 아래 환경 변수를 설정하여 이를 끕니다(Claude Code 공식 LLM gateway 문서 출처):
```bash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```
### 잔액은 충분한데 호출 실패
- 특정 모델만 실패하는 경우, 해당 모델이 일시적으로 사용 불가이거나, ID를 잘못 입력했거나, 이 API 키에 모델 제한이 설정된 경우일 수 있습니다(403 `This token has no access to model …`).
- 모두 실패하고 401인 경우, 이 API 키에 한도 상한이 설정되어 이미 소진되었거나 만료되었는지 확인합니다. 「API 키」 페이지의 「한도 ($)」 및 「만료」 열에서 볼 수 있습니다.
- 그 외의 경우는 위의 오류 코드 표를 참조합니다.
## 제한된 재시도와 피드백 템플릿
무한 루프로 구성 오류를 감추지 마세요. SDK 타임아웃, 자동 재시도 횟수 및 백오프 처리는[타임아웃 및 재시도](/ko/docs/retries/)을(를) 참조하세요.
지원팀에 문의할 때 아래 템플릿을 복사하여, 키, 인증 헤더 및 개인 정보를 삭제한 후 발송하세요:
```text
发生时间与时区：
客户端及版本：
请求方法与完整路径：
模型 ID：
HTTP 状态码：
request id（如有）：
脱敏后的错误正文：
最小请求能否复现：
是否使用代理 / 是否仅某个模型失败：
```
## 그래도 해결되지 않으면
support@1zheai.com으로 이메일을 보내주세요. 시간, 모델 ID, 사용한 도구와 버전, `curl -i`의 전체 출력(API 키 삭제)을 첨부해 주세요.
---
# AI 및 자동화
Source: https://1zheai.com/ko/docs/ai/
Markdown: https://1zheai.com/ko/docs/ai.md
---
title: "AI 및 자동화"
description: "AI 어시스턴트가 필요할 때 문서를 읽도록 하고, 기계 판독 진입점과 문서 MCP의 상태를 파악합니다."
headingIds: {"사용 가능한 기계 판독 진입점":"section-1","AI에게 전달할 연결 작업":"section-2","문서 MCP 상태":"section-3"}
---
AI 어시스턴트에게 먼저 이 사이트의 문서를 읽게 한 후 도구 구성이나 호출 코드 작성을 도울 수 있습니다. 일반적인 문서 읽기와 모델 API 호출은 별개의 일입니다: 공개 문서를 읽는 데는 API 키를 제공할 필요가 없습니다.
## 사용 가능한 기계 판독 진입점
| 진입점 | 용도 |
| --- | --- |
| [llms.txt](/ko/docs/llms.txt) | 섹션별로 문서를 발견하고 읽을 페이지를 선택 |
| [문서 목록](/ko/docs/docs-manifest.json) | 페이지 제목, 소속 섹션, 웹 및 Markdown 주소를 가져오기 |
| [전체 문서 텍스트](/ko/docs/llms-full.txt) | 모든 페이지를 한 번에 읽기; 내용이 길므로 페이지 단위 읽기를 우선 |
| [홈 Markdown](/ko/docs/index.md) | 사이트 탐색이 없는 원본 문서 내용 읽기 |
모든 글에는 해당하는 Markdown 주소가 있습니다. 예를 들어 `/ko/docs/quickstart-claude-code/`은 `/ko/docs/quickstart-claude-code.md`에 대응합니다. 페이지 상단의 "이 페이지 복사"를 사용할 수도 있습니다. Markdown에는 카드 등 문서 컴포넌트 마커가 남아 있을 수 있습니다.
## AI에게 전달할 연결 작업
작업 설명을 복사하여 어시스턴트가 먼저 지원 범위를 확인한 후 구성하고 검증하게 합니다.도구에 따라 프로토콜, 주소, 모델 구성을 선택합니다.
## 문서 MCP 상태
현재 이 사이트는 연결 가능한 문서 MCP 서버를 제공하지 않습니다. 위의 문서 주소를 먼저 사용하거나 페이지 내용을 어시스턴트에게 복사해 주세요. 모델 API의 Base URL을 MCP 주소로 사용하지 마세요.
문서 MCP의 용도는 공개 자료를 검색하고 읽는 것입니다. 계정 조회, 키 관리 등의 작업은 별도의 기능 유형이며 공개 문서 진입점으로는 얻을 수 없습니다.
---
# AI에게 설정을 맡기세요
Source: https://1zheai.com/ko/docs/agent-workflow/
Markdown: https://1zheai.com/ko/docs/agent-workflow.md
---
title: "AI에게 설정을 맡기세요"
description: "AI가 먼저 문서를 읽고, 제한 사항을 확인한 뒤, 설정과 검증을 완료할 수 있도록 돕는 복사 가능한 작업 브리프입니다."
headingIds: {"작업 브리프 복사하기":"section-1","완료 여부 판단 방법":"section-2"}
---
## 작업 브리프 복사하기
웹 페이지를 읽을 수 있는 AI 어시스턴트에게 아래 지시를 전달하고, 도구 이름과 운영 체제를 추가하세요. 어시스턴트가 네트워크에 접근할 수 없다면, 먼저 [머신 판독 가능한 진입점](/ko/docs/ai/)을 통해 관련 문서 내용을 확보하세요.
```text
请帮助我将现有工具或应用接入 1折AI。
目标工具与版本：[填写]
操作系统或编程语言：[填写]
先读取 https://1zheai.com/ko/docs/llms.txt，找到目标工具或 SDK 的文档。
再读取该页 Markdown，以及 API 参考和模型说明。
要求：
1. 先说明当前支持范围和工具配置要求。
2. 根据目标工具确定 Base URL，不要统一添加或删除 /v1。
3. 模型 ID 以当前文档和密钥可用模型列表为准，不要猜测。
4. 查看现有配置，只修改必要字段，保留其他供应商配置。
5. 使用环境变量或工具提供的凭据存储方式；不要把密钥写入源码、
对话、日志或提交记录。需要密钥时，让我在本地安全配置。
6. 执行会产生费用的测试前，说明测试内容并取得我的同意。
7. 用一次最小请求验证，再提示我在调用日志里核对记录。
8. 如果验证失败，保留脱敏的状态码与请求 ID，按排错文档处理；
不要用反复重试掩盖配置问题。
9. 最后说明修改位置、验证结果、剩余限制及恢复原配置的方法。
```
## 완료 여부 판단 방법
설정을 마쳤다고 해서 준비가 끝난 것은 아닙니다. 동시에 도구가 정상적으로 결과를 반환하는지, 실제로 사용 중인 모델이 기대와 일치하는지, 그리고 [호출 로그](/ko/docs/usage-logs/)에 해당 기록이 남아 있는지 확인해야 합니다.
이 페이지는 복사 가능한 작업 브리프이며, 설치된 Agent Skill이나 MCP 서비스가 아닙니다. 어떤 어시스턴트든 문서를 읽고 로컬 설정을 조작할 수 있는 해당 능력을 갖추어야 합니다.
---