NezhaGateNezhaGate
공지사항전체 공지 →
공지Seedance 2.5 · 30초 성공률 일시 저하, 초 단위 Seedance 2.5 10% 할인 일시 중단Seedance 2.0 일시 사용 불가: Seedance 2.5를 이용해 주세요 신규Seedance 2.5 1080P 오픈: 초당 $0.33
简体中文EnglishEspañol한국어 ✓日本語Русский
로그인 API 키 받기
문서
/

API 레퍼런스

⧉Markdown으로 복사 📄Markdown으로 보기AI에게 읽히기 좋은 텍스트 버전 ✦ChatGPT에서 열기 ✶Claude에서 열기

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

기본 URL

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

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

인증

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

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

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

API 키 관리 →

엔드포인트 목록

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

메서드경로설명
POST/v1/chat/completions채팅. 모든 채팅 모델에서 쓸 수 있고 stream: true면 스트리밍합니다.
POST/v1/responsesOpenAI Responses 형식의 채팅(일부 모델).
POST/anthropic/v1/messagesClaude 네이티브 Messages API. 스트리밍, 도구 사용, 프롬프트 캐싱을 지원합니다.
POST/anthropic/v1/messages/count_tokensMessages 요청의 토큰 수를 셉니다.
GET/anthropic/v1/modelsClaude 모델 목록(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_grantsOpenAI 방식의 잔액 조회. 잔액은 total_available에 있습니다.

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

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

상태의미
queued대기 중. queue_position(앞에 있는 작업 수)과 eta_seconds(예상 대기 시간)가 함께 옵니다.
processing생성 중.
succeeded완료. 결과는 data[0].url, 과금 내역은 usage에 있습니다.
failed실패. 사유는 error에 있고, 예약된 크레딧은 전액 환불됩니다.
curl · 작업 제출
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 · 작업 조회
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로 전송됩니다. 웹훅 문서 →

모델 목록

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

curl · GET /v1/models
curl https://nezhagate.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
200 · JSON
{"object": "list", "data": [{"id": "gpt-5.5", "object": "model", "owned_by": "..."}, {"id": "claude-sonnet-5", "object": "model", "owned_by": "..."}]}

잔액과 사용량

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

curl · GET /v1/usage
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
200 · JSON
{
  "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 · GET /v1/dashboard/billing/credit_grants
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"

오류 형식

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

400 · JSON
{
  "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). 점검이 끝날 때까지 요청을 받지 않습니다.

전체 오류 코드 목록 →

요청 제한과 재시도

  • 계정에는 기본 요청 빈도 제한이 없습니다. 콘솔에서 키마다 분당 요청 수, 일일 예산, 총 사용 한도, 모델 허용 목록, IP 허용 목록을 따로 정할 수 있습니다.
  • 429를 받으면 Retry-After 헤더만큼 기다린 뒤 다시 시도하세요. 502, 503, 시간 초과는 지수 백오프(예: 1초, 2초, 4초)로 재시도하면 됩니다.
  • 실패한 요청은 과금되지 않습니다. 스트리밍이 중간에 끊기면 받은 만큼만 정산합니다.
  • 높은 동시 요청을 꾸준히 쓸 계획이라면 미리 알려 주세요. 사용량에 맞춰 용량을 늘려 드립니다.

SDK와 예제

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

Python · openai
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="")

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

모델별 문서

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

채팅 모델

이미지 모델

영상 모델