# API 레퍼런스

모든 엔드포인트가 같은 API 키와 같은 잔액을 씁니다. 채팅은 OpenAI와 Anthropic 형식을 모두 지원하고, 이미지와 영상은 비동기 작업으로 처리됩니다.

> https://nezhagate.com/ko/docs/api

## 기본 URL

사용하는 SDK에 맞춰 고르세요. 두 주소 모두 같은 키, 같은 잔액을 씁니다.

| 프로토콜 | 기본 URL | 용도 |
| --- | --- | --- |
| **OpenAI 호환** | `https://nezhagate.com/v1` | 채팅, Responses, 이미지, 영상, 모델 목록, 잔액 |
| **Anthropic 네이티브** | `https://nezhagate.com/anthropic` | Claude 모델의 Messages API (Claude Code, Anthropic SDK) |

### 인증

모든 요청의 헤더에 API 키를 넣어 보냅니다. 키는 콘솔의 「API Keys」 페이지에서 만들며, 만들 때 한 번만 표시됩니다.

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Anthropic 엔드포인트는 `x-api-key` 헤더를 쓰며 `Authorization: Bearer`도 받습니다.

## 엔드포인트 목록

모든 경로는 `https://nezhagate.com` 아래에 있습니다. 동기 엔드포인트는 결과를 바로 돌려주고, 이미지·영상 엔드포인트는 작업 ID를 돌려줍니다.

| 메서드 | 경로 | 설명 |
| --- | --- | --- |
| POST | `/v1/chat/completions` | 채팅. 모든 채팅 모델에서 쓸 수 있고 `stream: true`면 스트리밍합니다. |
| POST | `/v1/responses` | OpenAI Responses 형식의 채팅(일부 모델). |
| POST | `/anthropic/v1/messages` | Claude 네이티브 Messages API. 스트리밍, 도구 사용, 프롬프트 캐싱을 지원합니다. |
| POST | `/anthropic/v1/messages/count_tokens` | Messages 요청의 토큰 수를 셉니다. |
| GET | `/anthropic/v1/models` | Claude 모델 목록(Anthropic 형식). |
| POST | `/v1/images/generations` | 텍스트-투-이미지. 작업 ID를 바로 돌려줍니다(HTTP 202). |
| POST | `/v1/images/edits` | 이미지-투-이미지. 위 엔드포인트에 `image`를 넣어도 같습니다. |
| GET | `/v1/images/jobs/{id}` | 이미지 작업의 상태와 결과를 조회합니다. |
| POST | `/v1/videos/generations` | 영상 생성. 작업 ID를 바로 돌려줍니다(HTTP 202). |
| GET | `/v1/videos/jobs/{id}` | 영상 작업의 상태와 결과를 조회합니다. |
| GET | `/v1/models` | 판매 중인 모델 목록(OpenAI 형식). |
| GET | `/v1/usage` | 잔액, 누적·오늘 사용액, 모델별 사용량. |
| GET | `/v1/dashboard/billing/credit_grants` | OpenAI 방식의 잔액 조회. 잔액은 `total_available`에 있습니다. |

## 비동기 작업(이미지와 영상)

이미지와 영상 호출은 즉시 HTTP 202와 작업 ID를 돌려주고, 생성은 백그라운드에서 진행됩니다. ID로 폴링하거나 웹훅으로 결과를 받으세요.

| 상태 | 의미 |
| --- | --- |
| `queued` | 대기 중. `queue_position`(앞에 있는 작업 수)과 `eta_seconds`(예상 대기 시간)가 함께 옵니다. |
| `processing` | 생성 중. |
| `succeeded` | 완료. 결과는 `data[0].url`, 과금 내역은 `usage`에 있습니다. |
| `failed` | 실패. 사유는 `error`에 있고, 예약된 크레딧은 전액 환불됩니다. |

```
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2", "prompt": "a lighthouse at dawn, watercolor", "size": "16:9"}'

# HTTP 202
{"id": "img_3f9a...c2", "object": "image.generation.job", "status": "queued", "model": "nano-banana-2"}
```

```
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H "Authorization: Bearer YOUR_API_KEY"
```

```
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791199400,
  "model": "nano-banana-2",
  "data": [{"url": "https://img.nezhagate.com/i/9f86d081a8....png"}],
  "usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2"}
}
```

- 이미지는 2~3초, 영상은 5~10초 간격으로 조회하세요. 조회 자체는 무료입니다.

- `data[0].url`은 당사 미디어 호스트의 링크로, 60일 동안 보관한 뒤 삭제됩니다. 보관할 파일은 다운로드해 두세요.

- 제출할 때 `callback_url`을 넣으면, 작업이 끝날 때 조회 결과와 같은 내용이 그 URL로 전송됩니다. [웹훅 문서 →](https://nezhagate.com/ko/docs/webhooks)

## 모델 목록

판매 중인 모든 모델 ID를 OpenAI와 같은 형식으로 돌려줍니다. 판매가 끝난 모델은 빠지고, 출시 예정 모델은 목록에 있지만 열리기 전까지 400 `model_coming_soon`을 돌려줍니다.

```
curl https://nezhagate.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
```

```
{"object": "list", "data": [{"id": "gpt-5.5", "object": "model", "owned_by": "..."}, {"id": "claude-sonnet-5", "object": "model", "owned_by": "..."}]}
```

## 잔액과 사용량

아무 API 키로나 계정의 잔액과 사용액을 조회할 수 있습니다. 콘솔에 로그인할 필요가 없습니다.

```
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```

```
{
  "object": "usage",
  "balance": {"usd": 12.5, "credits": 2500},
  "total": {"cost_usd": 37.5, "requests": 1840, "billed_requests": 1822, "failed_requests": 18},
  "today": {"cost_usd": 1.2, "requests": 64, "billed_requests": 63, "failed_requests": 1},
  "by_model": [
    {"model": "gpt-5.5", "cost_usd": 20.1, "requests": 900, "billed_requests": 896, "failed_requests": 4,
     "prompt_tokens": 1520000, "completion_tokens": 410000, "image_count": 0}
  ]
}
```

`balance.usd`는 달러 잔액이고 `balance.credits`는 같은 잔액을 크레딧으로 환산한 값입니다(1달러 = 200크레딧).

기존 잔액 조회 도구와 맞추려면 OpenAI 방식 엔드포인트를 쓰세요. 잔액은 `total_available`입니다.

```
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## 오류 형식

모든 오류는 같은 구조입니다. `code`는 바뀌지 않는 기계 판독용 식별자이니 `message` 문구가 아니라 `code`로 판단하세요.

```
{
  "error": {
    "message": "Model not enabled: gpt-9",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}
```

| HTTP | 언제 나오나요 |
| --- | --- |
| **400** | 잘못된 파라미터 또는 없는 모델(`model_not_found` 등). `error.param`이 해당 필드를 알려 줍니다. |
| **401** | 키가 없거나, 유효하지 않거나, 정지된 키(`missing_api_key`, `invalid_api_key`). |
| **402** | 잔액이 부족하거나 키가 예산 한도에 도달했습니다(`insufficient_quota`). |
| **403** | 이 키의 모델 허용 목록에 해당 모델이 없습니다. |
| **404** | 작업이 없거나 다른 키의 작업입니다(`job_not_found`). |
| **429** | 요청 제한에 걸렸거나 이 모델의 모든 회선이 가득 찼습니다. `Retry-After` 헤더의 초만큼 기다린 뒤 다시 시도하세요. |
| **502** | 업스트림 오류 또는 시간 초과(`upstream_error`). 과금되지 않으니 다시 시도해도 됩니다. |
| **503** | 모델 점검 중(`model_maintenance`). 점검이 끝날 때까지 요청을 받지 않습니다. |

[전체 오류 코드 목록 →](https://nezhagate.com/ko/docs-guide#errors)

## 요청 제한과 재시도

- 계정에는 기본 요청 빈도 제한이 없습니다. 콘솔에서 키마다 분당 요청 수, 일일 예산, 총 사용 한도, 모델 허용 목록, IP 허용 목록을 따로 정할 수 있습니다.

- 429를 받으면 `Retry-After` 헤더만큼 기다린 뒤 다시 시도하세요. 502, 503, 시간 초과는 지수 백오프(예: 1초, 2초, 4초)로 재시도하면 됩니다.

- 실패한 요청은 과금되지 않습니다. 스트리밍이 중간에 끊기면 받은 만큼만 정산합니다.

- 높은 동시 요청을 꾸준히 쓸 계획이라면 미리 알려 주세요. 사용량에 맞춰 용량을 늘려 드립니다.

## SDK와 예제

전용 SDK가 필요 없습니다. OpenAI와 Anthropic 공식 SDK에서 `base_url`만 바꾸면 됩니다.

```
from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="")
```

```
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://nezhagate.com/v1", apiKey: "YOUR_API_KEY" });
const resp = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);
```

```
import anthropic

client = anthropic.Anthropic(base_url="https://nezhagate.com/anthropic", api_key="YOUR_API_KEY")
msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(msg.content[0].text)
```

바로 실행되는 예제 더 보기(Python, Node.js, curl, 이미지·영상 비동기 흐름 포함): [github.com/gaoorange/nezhagate-api-examples](https://github.com/gaoorange/nezhagate-api-examples)

## 모델별 문서

모델마다 전용 문서가 있습니다. 파라미터 값, 예제 코드, 응답 형식, 과금 방식을 정리해 두었습니다.

### 채팅 모델

- [GPT-5.6 Sol](https://nezhagate.com/ko/docs/gpt-5.6-sol)

- [GPT-5.6 Terra](https://nezhagate.com/ko/docs/gpt-5.6-terra)

- [GPT-5.6 Luna](https://nezhagate.com/ko/docs/gpt-5.6-luna)

- [GPT-5.5](https://nezhagate.com/ko/docs/gpt-5.5)

- [GPT-6 Astra](https://nezhagate.com/ko/docs/gpt-6-astra)

- [GPT-6.1 Sol](https://nezhagate.com/ko/docs/gpt-6.1-sol)

- [GPT-6 Sol](https://nezhagate.com/ko/docs/gpt-6-sol)

- [GPT-6 Luna](https://nezhagate.com/ko/docs/gpt-6-luna)

- [Claude Sonnet 4.6](https://nezhagate.com/ko/docs/claude-sonnet-4-6)

- [Claude Opus 5](https://nezhagate.com/ko/docs/claude-opus-5)

- [Claude Fable 5](https://nezhagate.com/ko/docs/claude-fable-5)

- [Claude Sonnet 5](https://nezhagate.com/ko/docs/claude-sonnet-5)

- [Claude Opus 5.5](https://nezhagate.com/ko/docs/claude-opus-5-5)

- [Claude Sonnet 5.5](https://nezhagate.com/ko/docs/claude-sonnet-5-5)

- [Gemini 3.1 Pro](https://nezhagate.com/ko/docs/gemini-3.1-pro)

- [Gemini 3.8 Flash](https://nezhagate.com/ko/docs/gemini-3.8-flash)

- [Gemini 3.7 Flash](https://nezhagate.com/ko/docs/gemini-3.7-flash)

- [Gemini 3.6 Flash](https://nezhagate.com/ko/docs/gemini-3.6-flash)

- [Gemini 3.6 Flash High](https://nezhagate.com/ko/docs/gemini-3.6-flash-high)

- [Gemini 3.6 Flash Low](https://nezhagate.com/ko/docs/gemini-3.6-flash-low)

- [Gemini 3.6 Flash Tiered](https://nezhagate.com/ko/docs/gemini-3.6-flash-tiered)

- [Gemini 3 Flash](https://nezhagate.com/ko/docs/gemini-3-flash-preview)

- [Gemini 2.5 Flash](https://nezhagate.com/ko/docs/gemini-2.5-flash)

- [DeepSeek V4.1 Flash](https://nezhagate.com/ko/docs/deepseek-v4.1-flash)

- [DeepSeek V4 Flash 0731](https://nezhagate.com/ko/docs/deepseek-v4-flash-0731)

- [GLM-5.3](https://nezhagate.com/ko/docs/glm-5.3)

- [GLM-5.3 Flash](https://nezhagate.com/ko/docs/glm-5.3-flash)

- [Kimi K3](https://nezhagate.com/ko/docs/kimi-k3)

- [Qwen3.7 Max](https://nezhagate.com/ko/docs/qwen3.7-max)

- [Qwen3.8 Max](https://nezhagate.com/ko/docs/qwen3.8-max)

- [Qwen3.8 Max 0902](https://nezhagate.com/ko/docs/qwen3.8-max-0902)

- [Qwen3.8 Flash](https://nezhagate.com/ko/docs/qwen3.8-flash)

- [Doubao Seed 2.1 Pro](https://nezhagate.com/ko/docs/doubao-seed-2-1-pro)

- [Doubao Seed 2.1 Turbo](https://nezhagate.com/ko/docs/doubao-seed-2-1-turbo)

- [Grok 4.7](https://nezhagate.com/ko/docs/grok-4.7)

### 이미지 모델

- [GPT Image 2](https://nezhagate.com/ko/docs/gpt-image-2)

- [GPT Image 2.5 Flare](https://nezhagate.com/ko/docs/gpt-image-2.5-flare)

- [GPT Image 2.5 Sunburst](https://nezhagate.com/ko/docs/gpt-image-2.5-sunburst)

- [Nano Banana 2](https://nezhagate.com/ko/docs/nano-banana-2)

- [Nano Banana Pro](https://nezhagate.com/ko/docs/nano-banana-pro)

- [Grok Imagine Image](https://nezhagate.com/ko/docs/grok-imagine-image)

- [Grok Imagine Image Quality](https://nezhagate.com/ko/docs/grok-imagine-image-quality)

### 영상 모델

- [Veo 3.1](https://nezhagate.com/ko/docs/veo-3.1)

- [Gemini Omni Flash](https://nezhagate.com/ko/docs/gemini-omni-flash)

- [Seedance 2.5](https://nezhagate.com/ko/docs/seedance-2.5)

- [Seedance 2.0](https://nezhagate.com/ko/docs/seedance-2.0)

- [Seedance 2.0 Fast](https://nezhagate.com/ko/docs/seedance-2.0-fast)

- [Seedance 2.0 · Clip](https://nezhagate.com/ko/docs/seedance-2.0-clip)

- [Seedance 2.5 · 30s](https://nezhagate.com/ko/docs/seedance-2.5-30s)

- [Wan 3.0](https://nezhagate.com/ko/docs/wan3.0-video)

- [Wan 3.0 Prime](https://nezhagate.com/ko/docs/wan3.0-video-prime)

- [MiniMax H3](https://nezhagate.com/ko/docs/minimax-h3)

- [Grok Imagine Video 1.5](https://nezhagate.com/ko/docs/grok-imagine-video-1.5)