Messages API

엔드포인트: POST /v1/messages. 요청과 응답은 Anthropic Messages API와 정확히 일치하므로 Anthropic SDK 또는 이 형식을 지원하는 도구는 기본 URL과 키만 바꾸면 Kunavo에서 사용할 수 있습니다.

어떤 엔드포인트를 사용해야 하나요?

Kunavo는 Claude 계열 모델을 두 가지 방식으로 제공합니다. 두 방식의 요금은 동일하므로 코드가 이미 사용하는 요청 형식에 맞춰 선택하세요.

인증

기본 URL을 https://api.kunavo.com로 설정하세요. Anthropic SDK가 /v1/messages를 자동으로 추가합니다. Kunavo 키(sk-kn-...)를 API 키로 전달하세요. 엔드포인트는 x-api-key 헤더(Anthropic SDK 기본값) 또는 Authorization: Bearer를 통해 키를 받습니다.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-kn-...",                  # your Kunavo key
    base_url="https://api.kunavo.com",    # SDK appends /v1/messages
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a senior staff engineer.",
    messages=[
        {"role": "user", "content": "Pros and cons of event sourcing?"},
    ],
)
print(msg.content[0].text)

프롬프트 캐싱

이것이 기본 엔드포인트를 사용하는 주된 이유입니다. 모든 시스템 블록, 메시지 콘텐츠 블록 또는 도구 정의에 cache_control 중단점을 지정하세요. 표시된 접두사는 한 번 캐시에 기록되고, 이후 동일한 접두사를 공유하는 호출에서 다시 사용됩니다.

캐싱 자체에는 이 엔드포인트가 필요하지 않습니다. /v1/chat/completions 및 /v1/responses에서는 프롬프트가 길면 Kunavo가 Claude 모델의 중단점을 직접 설정합니다. 이 엔드포인트가 다른 점은 중단점을 전혀 추가하지 않는다는 것입니다. 본문은 보낸 그대로 전달되므로, 본문에 있는 중단점은 모두 사용자가 직접 넣은 것입니다.

# Mark a large, stable prefix with cache_control. The first call writes that
# span to cache at 1.25× the input token price; later calls that reuse it read
# it back at ~10%.
msg = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_STYLE_GUIDE,            # tens of thousands of tokens
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "Review this PR against the guide."}],
)
u = msg.usage
print(u.cache_creation_input_tokens, u.cache_read_input_tokens)

Kunavo의 Claude 계열 모델 요금:

• cache_read_input_tokens — 캐시에서 제공되며 입력 요금의 0.10×로 청구됩니다(할인율 90%).; Claude Fable 5.1에서는 0.025×, Claude Opus 5.5에서는 0.05×
• cache_creation_input_tokens — 캐시에 기록되며 입력 요금의 1.25배로 청구됩니다. Kunavo는 1시간 TTL 쓰기도 Anthropic의 2배보다 낮은 1.25배 요금으로 청구합니다.

스트리밍

stream: true를 설정하거나 SDK의 stream() 헬퍼를 사용하세요. Kunavo는 Anthropic 기본 이벤트 스트림인 message_start, content_block_delta, message_delta, message_stop를 그대로 전달합니다.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain CRDTs in one paragraph."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

이미지

이미지는 base64 소스 또는 url 소스로 전송하세요. url 소스는 Kunavo가 재작성하는 본문의 유일한 부분입니다. Kunavo가 https 이미지를 직접 다운로드하거나 data: URI를 압축 해제한 다음 base64로 전달합니다. 업스트림은 url 소스를 무시하고 이미지가 전송되지 않은 것처럼 응답하기 때문입니다. tool_result 안에 있는 이미지도 같은 방식으로 처리합니다. 제한: 요청당 이미지 16개, 이미지당 5 MB, 총 20 MB. 가져올 수 없는 이미지는 건너뛰지 않고 오류를 반환합니다.

사용량 객체

모든 응답과 스트리밍 message_delta / message_start 이벤트에는 Anthropic 기본 usage 객체가 포함됩니다.

서버 도구

Anthropic의 서버 도구(web_search, web_fetch, code_execution)는 일반 도구 정의로 전달됩니다. 대화에 추가된 내용(검색 결과, 가져온 페이지, 프로그램 출력)은 usage에서 토큰으로 반환되며 위 요금이 적용됩니다.

웹 검색은 해당 토큰 요금에 더해 검색당 요금도 청구됩니다. Anthropic은 검색 1,000건당 $10로 책정하며 Kunavo는 각 모델에 적용되는 할인율로 이를 청구합니다. 검색 횟수는 응답의 usage.server_tool_use.web_search_requests 또는 스트림의 마지막 message_delta에 표시됩니다. max_uses_exceeded와 같이 오류를 반환한 검색은 집계하지 않습니다. 웹 가져오기와 코드 실행은 토큰 요금 외에 비용이 들지 않습니다.

지원 모델

활성화된 Claude 모델은 무엇이든 /v1/messages를 사용할 수 있습니다. Kunavo 슬러그를 model로 전송하세요.

• claude-fable-5, claude-sonnet-5
• claude-opus-5, claude-opus-4-7, claude-opus-4-6
• claude-sonnet-4-6, claude-haiku-4-5

GPT 모델은 여기서 사용할 수 없습니다. /v1/chat/completions를 통해 호출하세요.

원시 HTTP

SDK가 필요 없습니다. 이 엔드포인트는 일반 JSON POST 요청을 사용합니다.

curl https://api.kunavo.com/v1/messages \
  -H "x-api-key: sk-kn-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

다음 단계

• OpenAI 호환 채팅 완성
• 청구 방식(토큰 요금, 캐시 요금, 마크업)
• 모든 채팅 모델 둘러보기