# NezhaGate API 개발자 문서

OpenAI 호환 AI API 게이트웨이. Base URL: `https://nezhagate.com/v1`

## 인증
모든 요청에는 Bearer 토큰이 필요합니다:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 모델과 요금
| 모델 | 기능 | 엔드포인트 | 요금 |
| --- | --- | --- | --- |
| gpt-5.6-sol | 프런티어 추론, 에이전트 코딩, 장기 과제, 구조화 출력 | /chat/completions | 입력 $2.0/1M · 출력 $12.0/1M |
| gpt-5.6-terra | 일상 채팅, 에이전트 코딩, 추론, 구조화 출력 | /chat/completions | 입력 $1.2/1M · 출력 $7.0/1M |
| gpt-5.6-luna | 고속 채팅, 에이전트 코딩, 대량 · 저지연 처리, 구조화 출력 | /chat/completions | 입력 $0.8/1M · 출력 $4.8/1M |
| gpt-5.5 | 채팅, 추론, 에이전트, 구조화 출력 | /chat/completions | 입력 $0.7/1M · 출력 $4.2/1M |
| gpt-6-astra | 심층 추론, 에이전트 코딩, 초장문 컨텍스트, 이미지 입력, 구조화 출력 | /chat/completions | 입력 $2.8/1M · 출력 $14.0/1M |
| gpt-image-2 | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트 | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-flare | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트, 타이포그래피 | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-sunburst | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트, 타이포그래피 | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-2 | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트 | /images/generations | 1K $0.025 · 2K $0.0375 · 4K $0.0625 |
| nano-banana-pro | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트, 인포그래픽 | /images/generations | 1K $0.04 · 2K $0.06 · 4K $0.1 |
| claude-sonnet-4-6 | 채팅, 코드, 추론, 긴 컨텍스트 | /chat/completions | 입력 $1.5/1M · 출력 $7.5/1M |
| claude-opus-5 | 심층 추론, 코드, 에이전트, 긴 컨텍스트, 이미지 이해 | /chat/completions | 입력 $4.0/1M · 출력 $20.0/1M |
| claude-fable-5 | 중국어 글쓰기, 서사 창작, 장문 생성, 채팅, 코드, 이미지 이해 | /chat/completions | 입력 $8.0/1M · 출력 $40.0/1M |
| gemini-3.1-pro | 채팅, 추론, 초장문 컨텍스트, 멀티모달 | /chat/completions | 입력 $0.5/1M · 출력 $3.0/1M |
| gemini-3.8-flash | 채팅, 추론, 적응형 사고, 이미지 입력, 초장문 컨텍스트 | /chat/completions | 입력 $0.6/1M · 출력 $3.6/1M |
| gemini-3.7-flash | 채팅, 추론, 적응형 사고, 이미지 입력, 초장문 컨텍스트 | /chat/completions | 입력 $0.6/1M · 출력 $3.6/1M |
| gemini-3.6-flash | 채팅, 추론, 사고, 이미지 입력, 초장문 컨텍스트 | /chat/completions | 입력 $0.6/1M · 출력 $3.6/1M |
| gemini-3.6-flash-high | 심층 추론, 복잡한 과제, 사고, 이미지 입력, 초장문 컨텍스트 | /chat/completions | 입력 $0.6/1M · 출력 $3.6/1M |
| gemini-3.6-flash-low | 고속 채팅, 대량 처리, 낮은 지연, 이미지 입력 | /chat/completions | 입력 $0.6/1M · 출력 $3.6/1M |
| gemini-3.6-flash-tiered | 적응형 사고, 채팅, 추론, 이미지 입력 | /chat/completions | 입력 $0.6/1M · 출력 $3.6/1M |
| gemini-3-flash-preview | 채팅, 추론, 높은 동시성, 낮은 지연 | /chat/completions | 입력 $0.3/1M · 출력 $1.2/1M |
| gemini-2.5-flash | 채팅, 높은 동시성, 낮은 지연, 멀티모달 | /chat/completions | 입력 $0.3/1M · 출력 $1.2/1M |
| veo-3.1 | 텍스트-투-비디오, 이미지-투-비디오, 숏 클립, 상업용 영상 | /videos/generations | $0.075 / 건 · 출시 예정, 아직 호출 불가 |
| seedance-2.5 | 롱테이크 단편, 다중 참조 입력, 상업용 영상 | /videos/generations | $0.632 / 건 |
| seedance-2.0 | 숏 클립, 상업용 소재 | /videos/generations | $0.6 / 건 |
| seedance-2.0-fast | 대량 소재 제작, 빠른 콘셉트 확인 | /videos/generations | $0.4 / 건 |
| seedance-2.0-mini | 대량 초안, 저비용 반복 작업 | /videos/generations | $0.33 / 건 |
| wan3.0-video | 롱테이크 스토리텔링, 다중 소재 합성, 영상 리라이팅 | /videos/generations | $0.18 / 건 |
| wan3.0-video-prime | 마감이 급한 영상, 대량 테스트 촬영 | /videos/generations | $0.24 / 건 |
| minimax-h3 | HD 영상, 소리가 있는 숏 클립 | /videos/generations | $0.18 / 건 |
| grok-imagine-video-1.5 | 대량 숏폼, 빠른 콘셉트 확인 | /videos/generations | $0.3 / 건 |

## 채팅 (Chat Completions)
`POST /v1/chat/completions`. `stream: true`로 스트리밍 출력을 지원합니다.
```bash
curl https://nezhagate.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'
```
이미지 입력(비전): `messages`의 `content` 배열에 `image_url`을 넣으면 됩니다. 공개 이미지 링크나 base64 data URL 모두 가능합니다:
```bash
curl https://nezhagate.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":[{"type":"text","text":"이 사진에는 무엇이 있나요?"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}]}'
```

## 이미지 생성 (Images) — 비동기 작업(제출하면 작업 ID를 돌려줍니다)
이미지 엔드포인트는 **작업(job) 방식만** 씁니다. 제출하면 즉시 `HTTP 202`와 작업 `id`가 돌아오고(`{"id":"img_...","object":"image.generation.job","status":"queued"}`), `GET /v1/images/jobs/{id}`를 `status`가 `succeeded`가 될 때까지 폴링한 뒤 `data[0].url`을 읽으면 됩니다(만료되지 않는 `img.nezhagate.com` 링크). 제출 응답에 `data`가 올 것이라고 기대하지 **마세요**.
**텍스트-투-이미지**는 `POST /v1/images/generations`입니다. **이미지-투-이미지**는 `POST /v1/images/edits`를 쓰거나 generations에 `image`를 추가하면 되며 둘은 동일합니다. `image`에는 공개 URL, `data:` URI, base64를 넣을 수 있습니다.
```bash
# 1) 제출 -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"gpt-image-2","prompt":"a poster","size":"2:3"}'
# 2) status=succeeded가 될 때까지 2~3초 간격으로 폴링, 결과는 data[0].url
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
`size`에는 화면 비율을 넣는 것을 권장합니다. `1:1` / `3:4` / `2:3` / `9:16` / `4:3` / `3:2` / `16:9` 중 하나를 주면 모델이 그 비율로 **네이티브 렌더링**해 피사체가 잘리지 않습니다. `1024x1024` / `1024x1536` / `1536x1024` 같은 픽셀 크기도 받습니다. 텍스트-투-이미지와 이미지-투-이미지 모두 지원하며, `async` 필드는 더 이상 필요 없고 보내도 무시됩니다.


## 영상 생성 (Videos) — 비동기 작업(제출하면 작업 ID를 돌려줍니다)
영상도 비동기 작업입니다. `POST /v1/videos/generations`를 호출하면 즉시 `HTTP 202`와 작업 ID가 돌아오고(`{"id":"img_...","object":"video.generation.job","status":"queued"}`), `GET /v1/videos/jobs/{id}`를 `status`가 `succeeded`가 될 때까지 폴링한 뒤 `data[0].url`을 읽으면 됩니다(재호스팅된 만료 없는 mp4 링크). 한 편에 약 1~2분 걸리고 건당 과금하며 실패 시 전액 환불합니다. 방향은 `size`로 정하며 `16:9`가 가로(기본), `9:16`이 세로입니다. 이미지-투-비디오는 `image`에 첫 프레임 참조를 넣으세요.
```bash
# 1) 제출 -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"seedance-2.5","prompt":"노을 속에서 서핑하는 고양이","size":"16:9","duration":"8s"}'
# 2) status=succeeded가 될 때까지 5초 간격으로 폴링, 결과는 data[0].url
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
사용 가능한 영상 모델: `seedance-2.5`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `wan3.0-video`, `wan3.0-video-prime`, `minimax-h3`, `grok-imagine-video-1.5`.
공통 파라미터: 방향은 `size`(또는 `aspect_ratio`), 길이는 `duration`, 화질은 `resolution`(지원하는 모델에 한함)으로 정하고, `image` / `images[]`에 참조 이미지를 넣으면 그 이미지를 첫 프레임으로 쓰는 이미지-투-비디오가 됩니다. 지원하는 길이와 해상도는 모델마다 다르며 모델별 표는 `/docs/<모델 id>`에 있습니다. 예: [/docs/seedance-2.5](/docs/seedance-2.5).

## 네이티브 Anthropic API (Claude Code 직접 연결)
OpenAI 호환 경로 외에, Claude 모델은 **네이티브 Anthropic Messages API**로도 제공됩니다. Claude Code(또는 모든 Anthropic SDK)의 `ANTHROPIC_BASE_URL`을 `https://nezhagate.com/anthropic`으로 두고 게이트웨이 키를 `x-api-key`로 쓰면 됩니다(`Authorization: Bearer`도 동작합니다). thinking, 도구 사용, 프롬프트 캐싱이 모두 그대로 통과합니다. 모델: claude-opus-5, claude-fable-5, claude-sonnet-4-6. 과금은 /v1과 완전히 같은 토큰 단위이며 캐시 읽기와 쓰기도 포함됩니다.
```bash
export ANTHROPIC_BASE_URL=https://nezhagate.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
curl https://nezhagate.com/anthropic/v1/messages -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" -d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
```
`"stream": true`도 표준 Anthropic SSE(message_start / content_block_delta / message_delta / message_stop)로 지원하며, `/anthropic/v1/messages/count_tokens`와 `GET /anthropic/v1/models`도 쓸 수 있습니다.
**프롬프트 캐시 과금**: 캐시 적중(캐시 읽기)은 입력 단가의 **1/10**(0.1×), 캐시 쓰기는 **1.25×**로 과금합니다(모델별 단가는 [요금 페이지](/pricing) 참고). 적중하려면 세 가지가 필요합니다. 바이트 단위로 동일한 접두부, 충분히 긴 접두부(Claude Opus 4096 토큰 이상, Sonnet 2048 이상), 그리고 짧은 시간 안의 반복 호출입니다. 큰 `CLAUDE.md`나 시스템 프롬프트를 들고 실제 코드베이스를 도는 Claude Code는 매 턴 적중해 입력 비용이 약 1/10로 줄고, 플레이그라운드의 짧은 대화는 접두부가 너무 짧아 캐시에 걸리지 않는 것이 정상입니다.

## 잔액 조회 (Balance)
아무 API 키로나 계정의 남은 잔액과 사용액을 조회할 수 있습니다. 대시보드 로그인이 필요 없습니다:
```bash
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```
OpenAI 호환(잔액 = `total_available`이므로 일반적인 잔액 조회 도구가 자동으로 인식합니다):
```bash
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## 오류 코드
| 상태 코드 | 의미 |
| --- | --- |
| 401 | API 키가 없거나 유효하지 않음 |
| 402 | 잔액 부족 또는 키 한도 초과 |
| 400 | 지원하지 않는 모델 또는 파라미터 |
| 429 | 업스트림 요청 한도 초과 |
| 502 | 모든 업스트림 경로 실패 |