diff --git a/API_USAGE.md b/API_USAGE.md new file mode 100644 index 00000000..354692ad --- /dev/null +++ b/API_USAGE.md @@ -0,0 +1,343 @@ +# CLIProxyAPI 호출 가이드 + +## 접속 정보 + +| 항목 | 값 | +|------|-----| +| 외부 URL | `https://cliproxy.gru.farm` | +| 내부 URL | `http://192.168.0.17:8317` | +| API 키 | `Jinie4eva!` | +| 인증 방식 | `Authorization: Bearer ` | + +## 엔드포인트 + +| 용도 | 경로 | +|------|------| +| Claude 네이티브 (권장) | `/api/provider/claude/v1/messages` | +| OpenAI 호환 | `/v1/chat/completions` | +| 모델 목록 | `/v1/models` | + +## 사용 가능한 모델 + +| 모델 ID | 설명 | +|---------|------| +| `claude-sonnet-4-6` | Claude Sonnet 4.6 (최신, 권장) | +| `claude-opus-4-6` | Claude Opus 4.6 (최고 성능) | +| `claude-sonnet-4-5-20250929` | Claude Sonnet 4.5 | +| `claude-opus-4-5-20251101` | Claude Opus 4.5 | +| `claude-haiku-4-5-20251001` | Claude Haiku 4.5 (경량/빠름) | +| `claude-sonnet-4-20250514` | Claude Sonnet 4 | +| `claude-opus-4-20250514` | Claude Opus 4 | +| `claude-3-7-sonnet-20250219` | Claude 3.7 Sonnet | +| `claude-3-5-haiku-20241022` | Claude 3.5 Haiku | + +--- + +## 1. curl + +### 기본 호출 + +```bash +curl -X POST https://cliproxy.gru.farm/api/provider/claude/v1/messages \ + -H "Authorization: Bearer Jinie4eva!" \ + -H "anthropic-version: 2023-06-01" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "claude-sonnet-4-6", + "max_tokens": 1024, + "messages": [ + {"role": "user", "content": "안녕! 간단히 소개해줘"} + ] + }' +``` + +### 스트리밍 + +```bash +curl -X POST https://cliproxy.gru.farm/api/provider/claude/v1/messages \ + -H "Authorization: Bearer Jinie4eva!" \ + -H "anthropic-version: 2023-06-01" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "claude-sonnet-4-6", + "max_tokens": 1024, + "stream": true, + "messages": [ + {"role": "user", "content": "안녕!"} + ] + }' +``` + +### 모델 목록 조회 + +```bash +curl https://cliproxy.gru.farm/v1/models \ + -H "Authorization: Bearer Jinie4eva!" +``` + +--- + +## 2. Python — Anthropic SDK + +### 설치 + +```bash +pip install anthropic +``` + +### 기본 호출 + +```python +from anthropic import Anthropic + +client = Anthropic( + base_url="https://cliproxy.gru.farm/api/provider/claude", + api_key="Jinie4eva!" +) + +response = client.messages.create( + model="claude-sonnet-4-6", + max_tokens=1024, + messages=[ + {"role": "user", "content": "안녕! 간단히 소개해줘"} + ] +) + +print(response.content[0].text) +``` + +### 스트리밍 + +```python +from anthropic import Anthropic + +client = Anthropic( + base_url="https://cliproxy.gru.farm/api/provider/claude", + api_key="Jinie4eva!" +) + +with client.messages.stream( + model="claude-sonnet-4-6", + max_tokens=1024, + messages=[ + {"role": "user", "content": "안녕! 간단히 소개해줘"} + ] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +### 시스템 프롬프트 + 멀티턴 + +```python +from anthropic import Anthropic + +client = Anthropic( + base_url="https://cliproxy.gru.farm/api/provider/claude", + api_key="Jinie4eva!" +) + +response = client.messages.create( + model="claude-sonnet-4-6", + max_tokens=1024, + system="당신은 친절한 한국어 AI 어시스턴트입니다.", + messages=[ + {"role": "user", "content": "파이썬이 뭐야?"}, + {"role": "assistant", "content": "파이썬은 프로그래밍 언어입니다."}, + {"role": "user", "content": "그럼 자바스크립트는?"} + ] +) + +print(response.content[0].text) +``` + +--- + +## 3. Python — OpenAI SDK (호환 모드) + +### 설치 + +```bash +pip install openai +``` + +### 기본 호출 + +```python +from openai import OpenAI + +client = OpenAI( + base_url="https://cliproxy.gru.farm/v1", + api_key="Jinie4eva!" +) + +response = client.chat.completions.create( + model="claude-sonnet-4-6", + messages=[ + {"role": "user", "content": "안녕!"} + ] +) + +print(response.choices[0].message.content) +``` + +### 스트리밍 + +```python +from openai import OpenAI + +client = OpenAI( + base_url="https://cliproxy.gru.farm/v1", + api_key="Jinie4eva!" +) + +stream = client.chat.completions.create( + model="claude-sonnet-4-6", + messages=[{"role": "user", "content": "안녕!"}], + stream=True +) + +for chunk in stream: + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="", flush=True) +``` + +--- + +## 4. Node.js — Anthropic SDK + +### 설치 + +```bash +npm install @anthropic-ai/sdk +``` + +### 기본 호출 + +```javascript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic({ + baseURL: "https://cliproxy.gru.farm/api/provider/claude", + apiKey: "Jinie4eva!", +}); + +const response = await client.messages.create({ + model: "claude-sonnet-4-6", + max_tokens: 1024, + messages: [{ role: "user", content: "안녕!" }], +}); + +console.log(response.content[0].text); +``` + +### 스트리밍 + +```javascript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic({ + baseURL: "https://cliproxy.gru.farm/api/provider/claude", + apiKey: "Jinie4eva!", +}); + +const stream = client.messages.stream({ + model: "claude-sonnet-4-6", + max_tokens: 1024, + messages: [{ role: "user", content: "안녕!" }], +}); + +for await (const chunk of stream) { + if ( + chunk.type === "content_block_delta" && + chunk.delta.type === "text_delta" + ) { + process.stdout.write(chunk.delta.text); + } +} +``` + +--- + +## 5. Node.js — OpenAI SDK (호환 모드) + +### 설치 + +```bash +npm install openai +``` + +### 기본 호출 + +```javascript +import OpenAI from "openai"; + +const client = new OpenAI({ + baseURL: "https://cliproxy.gru.farm/v1", + apiKey: "Jinie4eva!", +}); + +const response = await client.chat.completions.create({ + model: "claude-sonnet-4-6", + messages: [{ role: "user", content: "안녕!" }], +}); + +console.log(response.choices[0].message.content); +``` + +--- + +## 6. Claude Code CLI + +```bash +export ANTHROPIC_BASE_URL=https://cliproxy.gru.farm/api/provider/claude +export ANTHROPIC_API_KEY=Jinie4eva! + +claude +``` + +영구 적용 (`~/.zshrc` 또는 `~/.bashrc`): + +```bash +echo 'export ANTHROPIC_BASE_URL=https://cliproxy.gru.farm/api/provider/claude' >> ~/.zshrc +echo 'export ANTHROPIC_API_KEY=Jinie4eva!' >> ~/.zshrc +source ~/.zshrc +``` + +--- + +## 7. 환경변수로 관리 + +`.env` 파일: + +```env +ANTHROPIC_BASE_URL=https://cliproxy.gru.farm/api/provider/claude +ANTHROPIC_API_KEY=Jinie4eva! +``` + +Python에서 `.env` 사용: + +```python +from dotenv import load_dotenv +from anthropic import Anthropic + +load_dotenv() + +# base_url, api_key 자동으로 환경변수에서 읽음 +client = Anthropic() + +response = client.messages.create( + model="claude-sonnet-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "안녕!"}] +) +print(response.content[0].text) +``` + +--- + +## 주의사항 + +- **내부망 접근 시** URL을 `http://192.168.0.17:8317`로 변경 +- **OpenAI 호환 모드**는 `/v1/chat/completions`를 사용하지만, Claude 네이티브 기능(extended thinking 등)은 `/api/provider/claude/v1/messages` 사용 권장 +- **타임아웃** 설정: 긴 응답의 경우 클라이언트 타임아웃을 600초 이상으로 설정