Claude Opus 5 · API

빠른 시작

두 단계면 됩니다: 요청 보내기 → 스트리밍으로 답변 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다. 엔드포인트가 OpenAI Chat Completions와 같으므로 기존 OpenAI 코드는 base_url과 model만 바꾸면 됩니다.

1단계 · 요청 보내기

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-opus-5", "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'

응답(HTTP 200)

{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "claude-opus-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "광합성은 식물이 햇빛을 이용해 이산화탄소와 물을 당으로 바꾸고 산소를 내보내는 과정입니다."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  }
}

message.content는 답변이고 usage는 이 요청에 과금되는 토큰 수입니다. 프롬프트 캐싱의 과금 방식은 아래 「프롬프트 캐싱」을 보세요.

2단계 · 스트리밍으로 받기(권장)

curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-opus-5", "stream": true, "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'

스트림은 표준 SSE입니다. 각 청크의 본문은 choices[0].delta.content에 담기고, 마지막 청크에는 usage가 담기며, 스트림은 data: [DONE]으로 끝납니다. 답변이 길거나 모델이 먼저 생각해야 할 때는 스트리밍을 쓰세요. 비스트리밍 요청은 약 10분이 지나면 연결이 끊깁니다.

Python(OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")

# 1. 질문 하나에 답변 하나
resp = client.chat.completions.create(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
)
print(resp.choices[0].message.content)

# 2. 스트리밍
stream = client.chat.completions.create(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Anthropic SDK로 호출할 수도 있습니다(네이티브 API)

import anthropic

client = anthropic.Anthropic(base_url="https://nezhagate.com/anthropic", api_key="YOUR_API_KEY")
msg = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
)
print(next(b.text for b in msg.content if b.type == "text"))

Anthropic SDK의 base_url은 /anthropic까지만 적으면 됩니다. /v1/messages는 SDK가 알아서 붙입니다. 키는 위와 같은 키를 씁니다.

인증

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

콘솔에서 API 키를 만들면 시작할 수 있습니다.

사양 한눈에 보기

요청 파라미터

POST /v1/chat/completions의 요청 본문(JSON)이며, OpenAI Chat Completions와 같습니다. 자주 쓰는 파라미터와 이 모델에서의 실제 동작은 다음과 같습니다:

그 밖의 OpenAI 파라미터(stop, seed, user 등)는 보낸 그대로 모델에 전달되며, 적용 여부는 모델에 따라 다릅니다.

가격

토큰 단위로 과금하며, 아래 요금(100만 토큰당)은 실시간으로 반영됩니다. 프롬프트 캐시에 쓴 토큰은 캐시 쓰기 요금으로, 캐시에 적중한 토큰은 캐시 적중 요금으로 과금됩니다. 성공한 요청의 실제 사용량만 과금합니다. 1크레딧 = $0.005.

예를 들어 입력 2,000 토큰, 출력 1,000 토큰(사고 포함)인 요청 한 건은 약 $0.028입니다.

사고(Thinking)

적응형 사고가 기본으로 켜져 있어, 질문마다 얼마나 생각할지 모델이 정합니다. reasoning_effort에는 low / medium / high / xhigh / max를 쓸 수 있으며 게이트웨이가 Claude의 output_config.effort로 변환합니다. claude-opus-5-high처럼 단계를 모델 ID에 넣어도 되며, 과금은 claude-opus-5 기준입니다.

사고 요약을 받으려면 네이티브 API /anthropic을 쓰고 요청에 "thinking": {"type": "adaptive", "display": "summarized"}를 넣으세요. 사고 강도는 "output_config": {"effort": "high"}처럼 지정합니다.

이 모델은 사고를 끌 수 있습니다. "thinking": {"type": "disabled"}를 보내세요.

사고 토큰은 출력 토큰으로 계산되어 출력 요금으로 과금됩니다.

프롬프트 캐싱

긴 프롬프트는 따로 표시하지 않아도 자동으로 캐시에 쓰일 수 있으며(캐시 쓰기 요금으로 과금), 이후 반복되는 접두어는 캐시 적중 요금으로 과금됩니다. 네이티브 API /anthropic에서는 시스템 프롬프트나 메시지 블록에 "cache_control": {"type": "ephemeral"}을 붙여 캐시 위치를 직접 지정할 수 있으며, Claude Code는 이를 자동으로 처리합니다.

네이티브 API는 캐시 토큰 수를 usage.cache_creation_input_tokens(쓰기)와 usage.cache_read_input_tokens(적중)로 돌려주며, 과금은 이 숫자를 기준으로 계산됩니다.

이미지 입력

content 배열에 image_url 파트를 넣으세요. base64 data URI(data:image/png;base64,...)를 권장하며, 이 방식은 모든 회선에서 읽을 수 있습니다. 공개 이미지 링크는 회선이 직접 내려받아야 해서 일부 회선에서는 가져오지 못하거나 시간이 초과될 수 있습니다. 이미지는 모델 제공사의 규칙에 따라 입력 토큰으로 환산됩니다.

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-opus-5", "messages": [{"role": "user", "content": [{"type": "text", "text": "이 이미지에 무엇이 있는지 알려 줘"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'

도구 호출(Function Calling)

tools에 JSON Schema로 함수를 정의하세요. 모델이 함수를 호출하기로 하면 finish_reason: "tool_calls"를 돌려주며, message.tool_calls에 함수 이름과 인자(JSON 문자열)가 담깁니다.

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-opus-5", "messages": [{"role": "user", "content": "지금 상하이 날씨를 알려 줘"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'

함수를 실행한 뒤 그 결과를 role: "tool" 메시지로(해당 tool_call_id와 함께) 대화에 덧붙여 다시 요청하면, 모델이 이를 바탕으로 최종 답변을 줍니다. tool_choice에는 auto, none, required 또는 특정 함수를 지정할 수 있습니다.

웹 검색

요청에 "web_search": true를 넣으세요(또는 tools에 {"type": "web_search"} 항목을 넣어도 됩니다). 게이트웨이가 먼저 대화 내용을 바탕으로 실시간 웹 검색을 하고 최대 5개의 결과를 링크와 함께 참고 자료로 모델에 넘기면, 모델이 이를 바탕으로 답하면서 출처를 표시합니다. 검색 자체는 무료이며, 참고 자료는 입력 토큰으로 과금됩니다.

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-opus-5", "web_search": true, "messages": [{"role": "user", "content": "오늘 주요 기술 뉴스를 알려 줘"}]}'

Anthropic 네이티브 API(/anthropic)

• 주소는 https://nezhagate.com/anthropic/v1/messages입니다. 요청과 응답 모두 Anthropic Messages 형식이며, 스트리밍 이벤트, 도구 호출(tool_use / tool_result), 이미지 블록이 모두 Anthropic과 같으므로 Anthropic SDK와 Claude Code를 그대로 쓸 수 있습니다.
• 인증은 x-api-key: YOUR_API_KEY로 합니다(Authorization: Bearer도 됩니다). 키는 /v1과 같은 키입니다. anthropic-version, anthropic-beta 헤더는 보낸 그대로 전달되며, max_tokens는 필수입니다.
• 이 엔드포인트는 Claude 모델만 받으며, 다른 모델을 지정하면 404 not_found_error가 돌아옵니다. 이 밖에 POST /anthropic/v1/messages/count_tokens(토큰 수 계산, 무료)와 GET /anthropic/v1/models도 쓸 수 있습니다.
• 사고 요약: "thinking": {"type": "adaptive", "display": "summarized"}. 사고 강도: "output_config": {"effort": "high"}(low부터 max까지). temperature, top_p, top_k는 제거됩니다.
• 오류는 Anthropic 형식으로 돌아옵니다: {"type": "error", "error": {"type": ..., "message": ...}}. 잔액이 부족하면 402 billing_error가 돌아옵니다.
• 이 엔드포인트에서는 웹 검색이 기본으로 꺼져 있습니다(Claude Code가 매 턴 똑같이 보내는 접두어가 바뀌어 캐시가 깨지지 않도록). 켜려면 x-web-search: 1 헤더를 추가하세요.

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": "광합성을 한 문장으로 설명해 줘"}]}'

Claude Code에서 사용하기 →

회선과 안정성

• 모든 모델은 여러 회선으로 제공됩니다. 한 회선에서 오류나 시간 초과가 나거나 회선이 가득 차면, 게이트웨이는 응답을 돌려주기 시작하기 전에 자동으로 다음 회선으로 넘어갑니다. 따로 재시도할 필요가 없고, 두 번 과금되지도 않습니다.
• 스트리밍은 출력을 시작한 뒤에는 회선을 바꾸지 않습니다. 중간에 끊기면 끊기기 전까지 생성된 사용량만큼 과금됩니다(과금과 환불 참고).
• 모든 회선이 가득 차면 게이트웨이가 Retry-After와 함께 429를 돌려줍니다. 그 초만큼 기다린 뒤 다시 시도하세요. 실패한 요청은 과금되지 않습니다. 모델별 상태는 서비스 상태에서 볼 수 있습니다.

오류와 환불

오류는 error 객체(message, type, code, param)로 돌아옵니다. HTTP 상태 코드와 code로 판단하고, message 문구로는 판단하지 마세요. 실패한 요청은 과금되지 않으며, 전체 목록은 오류 코드에 있습니다.

스트리밍이 출력을 시작한 뒤 실패하면 상태 코드는 바뀌지 않습니다. 오류는 error가 담긴 데이터 줄로 오거나, 스트림이 그냥 끝납니다(data: [DONE] 없이). 이런 경우 중단된 것으로 처리하세요.