OpenAI 호환 API: 엔드포인트 하나와 Key 하나로 GPT, Claude, Gemini, DeepSeek 등 채팅 모델과 이미지·영상 생성을 호출합니다. 아래 예제는 모두 그대로 실행됩니다.
빠른 시작
Base URL과 API 키만 바꿔 끼우면 기존 OpenAI SDK가 그대로 동작합니다.
https://nezhagate.com/v1
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": "AI API 제품 소개를 짧게 써 줘"}], "stream": false}'
모델별 전체 요청 파라미터, 예제, 비동기 사용법은 각 모델의 전용 문서에 있습니다 — 아래 「모델 및 요금」 표에서 열어 보세요.
바로 실행할 수 있는 예제 더 보기 (Python / Node / curl, 비동기 이미지·영상 흐름 포함): github.com/gaoorange/nezhagate-api-examples
인증
모든 API 호출에는 Bearer 토큰이 필요합니다.
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
모델 및 요금
모델별 전체 요청 파라미터, 예제, 비동기 사용법은 각 모델의 전용 문서에 있습니다 — 아래 「모델 및 요금」 표에서 열어 보세요.
| 모델 | 기능 | 엔드포인트 | 요금 | |
|---|---|---|---|---|
| gpt-5.6-sol | 프런티어 추론, 에이전트 코딩, 장기 과제, 구조화 출력 | /chat/completions | 입력 $1.2/1M · 출력 $6.0/1M | API 문서 → |
| gpt-5.6-luna | 고속 채팅, 에이전트 코딩, 대량 · 저지연 처리, 구조화 출력 | /chat/completions | 입력 $0.07/1M · 출력 $0.4/1M | API 문서 → |
| gpt-6-astra | 심층 추론, 에이전트 코딩, 초장문 컨텍스트, 이미지 입력, 구조화 출력 | /chat/completions | 입력 $3.0/1M · 출력 $15.0/1M | API 문서 → |
| gpt-6.1-sol | 에이전트 코딩, 복잡한 코딩, 전문 문서·분석 업무, 추론, 초장문 컨텍스트, 이미지 입력, 구조화 출력 | /chat/completions | 입력 $0.6/1M · 출력 $3.0/1M | API 문서 → |
| gpt-6-sol | 복잡한 코딩, 에이전트 워크플로, 추론, 초장문 컨텍스트, 이미지 입력, 구조화 출력 | /chat/completions | 입력 $0.6/1M · 출력 $3.0/1M | API 문서 → |
| gpt-6-luna | 대량 채팅, 저지연 에이전트 단계, 분류와 추출, 초장문 컨텍스트, 구조화 출력 | /chat/completions | 입력 $0.07/1M · 출력 $0.4/1M | API 문서 → |
| gpt-image-2 | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트 | /images/generations | 1K $0.005 · 2K $0.025 · 4K $0.04 | API 문서 → |
| gpt-image-2.5-flare | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트, 타이포그래피 | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 | API 문서 → |
| gpt-image-2.5-sunburst | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트, 타이포그래피 | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 | API 문서 → |
| nano-banana-2 | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트 | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 | API 문서 → |
| nano-banana-pro | 텍스트-투-이미지, 이미지-투-이미지, 표지, 포스터, 일러스트, 인포그래픽 | /images/generations | 1K $0.02 · 2K $0.03 · 4K $0.05 | API 문서 → |
| nano-banana-2.1 | 텍스트 기반 이미지 생성, 이미지 편집, 여러 이미지 합성, 포스터와 인포그래픽, 제품 이미지, 가로형 배너 | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 | API 문서 → |
| grok-imagine-image | 텍스트 기반 이미지 생성, 이미지 편집, 포스터, 제품 이미지, 소셜 비주얼, 중국어·영어 글자 | /images/generations | 1K $0.005 · 2K $0.005 · 4K $0.0 | API 문서 → |
| grok-imagine-image-quality | 커버, 포스터, 제품 이미지, 일러스트, 텍스트 기반 생성과 이미지 편집 | /images/generations | 1K $0.01 · 2K $0.01 · 4K $0.0 | API 문서 → |
| claude-sonnet-4-6 | 채팅, 코드, 추론, 긴 컨텍스트 | /chat/completions | 입력 $1.5/1M · 출력 $7.5/1M | API 문서 → |
| claude-opus-5 | 심층 추론, 코드, 에이전트, 긴 컨텍스트, 이미지 이해 | /chat/completions | 입력 $4.0/1M · 출력 $20.0/1M | API 문서 → |
| claude-fable-5 | 중국어 글쓰기, 서사 창작, 장문 생성, 채팅, 코드, 이미지 이해 | /chat/completions | 입력 $8.0/1M · 출력 $40.0/1M | API 문서 → |
| claude-opus-5-5 | 복잡한 추론, 장시간 에이전트 코딩, 코드 엔지니어링, 도구 호출, 이미지와 PDF 이해 | /chat/completions | 입력 $2.5/1M · 출력 $12.5/1M | API 문서 → |
| claude-sonnet-5-5 | 일상 코딩과 에이전트, 긴 컨텍스트, 도구 호출, 이미지와 PDF 이해, 대규모 프로덕션 트래픽 | /chat/completions | 입력 $1.5/1M · 출력 $7.5/1M | API 문서 → |
| gemini-4-argon | Beta · 추론 · 긴 컨텍스트 | /chat/completions | 입력 $0.5/1M · 출력 $3.0/1M | API 문서 → |
| gemini-3.1-pro | 채팅, 추론, 초장문 컨텍스트, 멀티모달 | /chat/completions | 입력 $0.5/1M · 출력 $3.0/1M | API 문서 → |
| gemini-3.8-flash | 채팅, 추론, 적응형 사고, 이미지 입력, 초장문 컨텍스트 | /chat/completions | 입력 $0.6/1M · 출력 $3.6/1M | API 문서 → |
| deepseek-v4.1-flash | 채팅, 추론, 코딩, 도구 호출, 사고 모드 전환 | /chat/completions | 입력 $0.075/1M · 출력 $0.3/1M | API 문서 → |
| deepseek-v4-flash-0731 | 채팅, 추론, 코딩, 도구 호출, 사고 모드 전환, 버전 고정 | /chat/completions | 입력 $0.13/1M · 출력 $0.51/1M | API 문서 → |
| glm-5.3 | 채팅, 코딩, 에이전트 워크플로, 추론, 중국어 · 영어 글쓰기, 도구 호출 | /chat/completions | 입력 $1.12/1M · 출력 $3.52/1M | API 문서 → |
| qwen3.8-max | 추론, 코딩, 에이전트와 도구 호출, 중국어 · 영어 글쓰기, 이미지 이해 | /chat/completions | 입력 $1.4/1M · 출력 $4.2/1M | API 문서 → |
| qwen3.8-flash | 대량 채팅, 분류와 추출, 요약과 재작성, 이미지 이해와 OCR, 도구 호출 | /chat/completions | 입력 $0.1/1M · 출력 $0.33/1M | API 문서 → |
| grok-4.7 | 복잡한 추론, 코딩, 긴 문서 분석, 도구 호출, 구조화 출력, 이미지 이해 | /chat/completions | 입력 $0.3/1M · 출력 $0.9/1M | API 문서 → |
| veo-3.1 | 짧은 영상, 제품 모션, 프레임 간 전환, 상업용 영상 | /videos/generations | $0.2 /건부터 | API 문서 → |
| gemini-omni-flash | 여러 컷의 짧은 영상, 콘티 기반 스토리, 프레임 간 전환 | /videos/generations | $0.05 /초 | API 문서 → |
| kling-4.0 | 인물 액션, 제품 숏폼, 참조 영상의 동작 재현 | /videos/generations | $0.09 /초 | API 문서 → |
| seedance-2.5-token | 텍스트, 이미지, 동영상 및 오디오 참조 | /videos/generations | $7.50–13.75 /1M video tokens | API 문서 → |
| seedance-2.5-token-draft | 텍스트, 이미지, 동영상 및 오디오 참조 | /videos/generations | $7.50–12.50 /1M video tokens | API 문서 → |
| seedance-2.5 | 롱테이크 단편, 다중 참조 입력, 상업용 영상 | /videos/generations | $0.158 /초 | API 문서 → |
| seedance-2.0 | 숏 클립, 상업용 소재 | /videos/generations | $0.15 /초 | API 문서 → |
| seedance-2.0-fast | 대량 소재 제작, 빠른 콘셉트 확인 | /videos/generations | $0.075 /초 | API 문서 → |
| seedance-2.0-clip | 실제 인물이 나오는 숏폼, 상품 영상, 대량 제작 | /videos/generations | $1.0 /건부터 | API 문서 → |
| seedance-2.5-30s | 롱테이크 스토리텔링, 장편 제품 영상 | /videos/generations | $2.0 /건부터 | API 문서 → |
| wan3.0-video | 롱테이크 스토리텔링, 다중 소재 합성, 영상 리라이팅 | /videos/generations | $0.065 /초 | API 문서 → |
| wan3.0-video-prime | 마감이 급한 영상, 대량 테스트 촬영 | /videos/generations | $0.112 /초 | API 문서 → |
| minimax-h3 | HD 영상, 소리가 있는 숏 클립 | /videos/generations | $0.036 /초 | API 문서 → |
| grok-imagine-video-1.5 | 대량 숏폼, 빠른 콘셉트 확인 | /videos/generations | $0.3 /건부터 | API 문서 → |
앱에서 사용하기 (코드 없이)
OpenAI API를 지원하는 앱이라면 아래 세 가지만 입력하면 됩니다 — 코딩이 필요 없습니다:
| API base URL | https://nezhagate.com/v1 |
| API 키 | 콘솔에서 만든 키 (콘솔 → API 키 → 복사) |
| 모델 이름 | gpt-5.6-sol gpt-5.6-luna gpt-6-astra gpt-6.1-sol gpt-6-sol gpt-6-luna gpt-image-2 gpt-image-2.5-flare gpt-image-2.5-sunburst nano-banana-2 nano-banana-pro nano-banana-2.1 grok-imagine-image grok-imagine-image-quality claude-sonnet-4-6 claude-opus-5 claude-fable-5 claude-opus-5-5 claude-sonnet-5-5 gemini-4-argon gemini-3.1-pro gemini-3.8-flash deepseek-v4.1-flash deepseek-v4-flash-0731 glm-5.3 qwen3.8-max qwen3.8-flash grok-4.7 veo-3.1 gemini-omni-flash kling-4.0 seedance-2.5-token seedance-2.5-token-draft seedance-2.5 seedance-2.0 seedance-2.0-fast seedance-2.0-clip seedance-2.5-30s wan3.0-video wan3.0-video-prime minimax-h3 grok-imagine-video-1.5 |
ChatBox, Cherry Studio, NextChat, LobeChat, Immersive Translate, Open WebUI 등에서 동작을 확인했습니다.
클라이언트별 단계 가이드: SillyTavern · Cherry Studio · Cline
네이티브 Anthropic API (Claude Code)
OpenAI 호환 경로 외에, Claude 모델은 네이티브 Anthropic Messages API로도 제공됩니다. Claude Code(또는 모든 Anthropic SDK)의 base URL을 아래 주소로 지정하고 게이트웨이 키를 x-api-key로 쓰면 됩니다 — thinking, 도구 사용, 프롬프트 캐싱이 모두 네이티브로 유지됩니다.
export ANTHROPIC_BASE_URL=https://nezhagate.com/anthropic export ANTHROPIC_API_KEY=YOUR_API_KEY # claude-sonnet-4-6 / claude-opus-5 / claude-fable-5 / claude-opus-5-5 / claude-sonnet-5-5
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-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
모델: claude-opus-5-5, claude-sonnet-5-5, claude-opus-5, claude-sonnet-5, claude-fable-5, claude-sonnet-4-6. 과금은 /v1과 완전히 동일한 토큰 단위입니다.
프롬프트 캐시 과금: 캐시 적중(캐시 읽기)은 입력 단가의 1/10(0.1×), 캐시 쓰기는 1.25×로 과금합니다(모델별 단가는 요금 페이지). 캐시에 적중하려면 충분히 길고 안정적인 접두부(Claude Opus 4096 토큰 이상, Sonnet 2048 이상)를 짧은 시간 안에 반복해서 보내야 합니다 — 큰 CLAUDE.md / 시스템 프롬프트를 들고 실제 코드베이스를 도는 Claude Code는 매 턴 적중해 입력 비용이 약 1/10로 떨어집니다. 플레이그라운드의 짧은 대화는 접두부가 너무 짧아 캐시에 걸리지 않습니다.
영상 생성 (비동기)
텍스트-투-비디오 / 이미지-투-비디오는 비동기 작업입니다. 호출하면 즉시 HTTP 202와 작업 ID가 돌아옵니다({"id":"img_...","object":"video.generation.job","status":"queued"}). GET /v1/videos/jobs/{id}를 status=succeeded가 될 때까지 폴링하면 결과가 data[0].url에 담깁니다(재호스팅된 mp4). 한 편에 1~12분 걸립니다. 과금 방식은 두 가지입니다: Veo 3.1은 건당, Seedance 2.x와 MiniMax H3는 초당(초당 단가 × 길이)입니다. 둘 다 예치 금액과 정산 금액이 정확히 일치하며 실패 시 전액 환불합니다. 화면 비율은 size로 지정하고(기본값은 16:9 가로), 이미지-투-비디오는 image에 첫 프레임 참조를 넣으세요.
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "veo-3.1", "prompt": "노을 속에서 서핑하는 고양이", "tier": "fast", "resolution": "1080p", "size": "16:9"}'curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
영상 모델: veo-3.1 gemini-omni-flash kling-4.0 seedance-2.5-token seedance-2.5-token-draft seedance-2.5 seedance-2.0 seedance-2.0-fast seedance-2.0-clip seedance-2.5-30s wan3.0-video wan3.0-video-prime minimax-h3 grok-imagine-video-1.5
웹훅: 작업이 끝나면 자동으로 알림 받기
영상과 이미지 생성은 비동기 방식입니다. 요청을 제출하면 작업 ID를 받고, 결과는 잠시 뒤에 나옵니다. 계속 폴링하는 대신 작업이 끝날 때 결과를 서버로 보내 드리고, 잔액이 부족해지면 알려 드릴 수도 있습니다.
폴링하고 싶지 않다면 작업을 제출할 때 callback_url을 추가하세요. 작업이 끝나면 결과를 서버로 보내 드립니다. 콘솔에서 기본 수신 주소를 설정할 수도 있습니다. 웹훅 문서 →
Agent Skills: AI 코딩 어시스턴트에게 한 문장으로 영상 만들기
Claude Code, Codex, Cursor 등 스킬을 지원하는 어시스턴트에 NezhaGate 스킬을 설치하면 "이 이미지를 seedance-2.5로 8초 영상으로 만들어 ./out에 저장해 줘"라고 말하기만 하면 됩니다. 모델 선택, 소재 업로드, 렌더링 대기, 저장까지 어시스턴트가 알아서 처리합니다. 현재 Seedance 2.5 / 2.0 영상 스킬을 제공합니다.
npx skills add https://nezhagate.com
export NEZHAGATE_API_KEY=YOUR_API_KEY
github.com/gaoorange/nezhagate-skills · 데모 영상 (8초, 요청 한 번으로 생성)
AI에 붙여 넣을 연동 노트
아래 블록 전체를 Codex / Claude Code / Cursor에 그대로 붙여 넣으면 연동 방법을 알아서 파악합니다. 오른쪽 위의 「페이지 복사」로 문서 전체를 복사할 수도 있습니다.
Integrate NezhaGate through its OpenAI-compatible API.
Base URL: https://nezhagate.com/v1
API Key: read it from the environment variable NEZHAGATE_API_KEY.
Claude models can also use the native Anthropic protocol (for Claude Code / the Anthropic SDK): ANTHROPIC_BASE_URL=https://nezhagate.com/anthropic, headers x-api-key=API Key and anthropic-version: 2023-06-01, POST /anthropic/v1/messages (max_tokens is required), models claude-sonnet-4-6 / claude-opus-5 / claude-fable-5 / claude-opus-5-5 / claude-sonnet-5-5.
Chat models (/chat/completions): gpt-5.6-sol / gpt-5.6-luna / gpt-6-astra / gpt-6.1-sol / gpt-6-sol / gpt-6-luna / claude-sonnet-4-6 / claude-opus-5 / claude-fable-5 / claude-opus-5-5 / claude-sonnet-5-5 / gemini-4-argon / gemini-3.1-pro / gemini-3.8-flash / deepseek-v4.1-flash / deepseek-v4-flash-0731 / glm-5.3 / qwen3.8-max / qwen3.8-flash / grok-4.7
Image models (text-to-image /images/generations; image-to-image /images/edits or add an image parameter): gpt-image-2 / gpt-image-2.5-flare / gpt-image-2.5-sunburst / nano-banana-2 / nano-banana-pro / nano-banana-2.1 / grok-imagine-image / grok-imagine-image-quality
Video models (/videos/generations, async jobs; add reference images for image-to-video; how each model uses them is in its own doc): veo-3.1 / gemini-omni-flash / kling-4.0 / seedance-2.5-token / seedance-2.5-token-draft / seedance-2.5 / seedance-2.0 / seedance-2.0-fast / seedance-2.0-clip / seedance-2.5-30s / wan3.0-video / wan3.0-video-prime / minimax-h3 / grok-imagine-video-1.5
Auth: Authorization: Bearer YOUR_API_KEY
Requirements (chat): return choices[0].message.content; on 401 check the key, 402 means insufficient balance, 429/5xx can be retried.
Requirements (images, async): POST /images/generations or /images/edits returns HTTP 202 with a job id right away ({"id":"img_...","object":"image.generation.job","status":"queued"}); then poll GET /v1/images/jobs/{id} until status=succeeded and read data[0].url (an img.nezhagate.com link kept for 15 days; download it or copy it to your own storage). Do not read data right after submitting.
Requirements (video, async): POST /videos/generations returns HTTP 202 with a job id (object=video.generation.job); then poll GET /v1/videos/jobs/{id} until status=succeeded and read data[0].url (a re-hosted mp4 link kept for 15 days). Render time varies by model (from a minute or two to over an hour); failed jobs are refunded in full.
잔액 및 사용량 조회
아무 API 키로나 계정의 남은 잔액과 사용액을 조회할 수 있습니다 — 대시보드 로그인이 필요 없습니다. 가장 간단한 방법은 GET /v1/usage입니다. OpenAI 호환 경로도 있습니다: /v1/dashboard/billing/credit_grants (잔액 = total_available).
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
오류 코드
/v1 엔드포인트의 오류는 아래 구조입니다(/anthropic 엔드포인트는 Anthropic 형식). code는 바뀌지 않는 기계 판독용 식별자이니 message 문구가 아니라 code로 판단하세요.
{
"error": {
"message": "human readable",
"type": "invalid_request_error | authentication_error | permission_error | insufficient_quota | rate_limit_error | server_error",
"code": "stable_snake_case",
"param": "field_name_or_null"
}
}
| HTTP | 의미 |
|---|---|
| 400 | 잘못된 파라미터 또는 없는 모델(model_not_found 등). error.param이 해당 필드를 알려 줍니다. |
| 401 | 키가 없거나, 유효하지 않거나, 정지된 키(missing_api_key, invalid_api_key). |
| 402 | 잔액이 부족하거나 키가 예산 한도에 도달했습니다(insufficient_quota). |
| 403 | 이 키의 모델 허용 목록에 해당 모델이 없거나, 키의 IP 허용 목록 밖에서 온 요청입니다(permission_denied). |
| 404 | 경로가 없거나, 작업 ID가 없거나 3일 기록 보관 기간이 지났거나 다른 계정이 제출한 작업입니다(job_not_found). |
| 429 | 이 키에 설정한 분당 요청 수나 무료 모델의 하루 한도를 넘었거나, 이 모델의 모든 회선이 가득 찼습니다(rate_limit_exceeded). Retry-After가 있으면 그 초만큼, 없으면 몇 초 기다린 뒤 다시 시도하세요. |
| 502 | 업스트림 오류 또는 시간 초과로, 회선을 바꿔도 실패했습니다. 이유는 code(upstream_timeout, upstream_unavailable 등)에 있습니다. 과금되지 않으니 다시 시도해도 됩니다. |
| 503 | 모델 점검 중(model_maintenance)이거나 당사 측의 일시적인 오류(service_unavailable)입니다. 과금되지 않으니 잠시 후 다시 시도하세요. |
사고 모델의 max_tokens — Gemini 3.x Flash(3-flash-preview / 3.6 / 3.7 / 3.8 전 티어)는 보이는 답변을 쓰기 전에 숨겨진 추론에 예산을 쓰므로, 예산이 작으면 답변이 시작되기도 전에 소진됩니다. 실측 결과 max_tokens=16은 바로 실패했고, 32 / 64는 finish_reason=length와 함께 그럴듯하지만 틀린 값을 반환했습니다. 게이트웨이는 이 모델들의 출력 예산을 최소 512로 올리지만(실제로 사용한 토큰만 과금), 직접 512 이상을 지정하세요. finish_reason=length는 잘렸을 수 있다고 보고 max_tokens를 늘려 다시 시도하세요.
연동, 과금, 모델, 보안에 대해 자주 묻는 질문. NezhaGate 자주 묻는 질문 →