Messages API

Điểm cuối: POST /v1/messages. Yêu cầu và phản hồi khớp chính xác với Messages API của Anthropic, vì vậy Anthropic SDK — hoặc bất kỳ công cụ nào hỗ trợ API này — đều hoạt động với Kunavo chỉ bằng cách đổi URL cơ sở và khóa.

Tôi nên dùng điểm cuối nào?

Kunavo cung cấp dòng Claude theo hai cách. Mức phí giống hệt nhau; hãy chọn theo định dạng yêu cầu mà mã của bạn đang dùng.

Xác thực

Đặt URL cơ sở thành https://api.kunavo.com — Anthropic SDK tự thêm /v1/messages. Truyền khóa Kunavo của bạn (sk-kn-...) làm API key; điểm cuối chấp nhận khóa qua tiêu đề x-api-key (mặc định của Anthropic SDK) hoặc 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)

bộ nhớ đệm prompt

Đây là lý do chính để dùng điểm cuối gốc. Gắn điểm đánh dấu cache_control vào bất kỳ khối system, khối nội dung tin nhắn hoặc định nghĩa công cụ nào. Phần tiền tố được đánh dấu sẽ được ghi vào bộ nhớ đệm một lần, rồi dùng lại trong các lệnh gọi sau có chung phần đó.

Bản thân việc lưu bộ nhớ đệm không cần đến điểm cuối này: trên /v1/chat/completions và /v1/responses, Kunavo tự đặt các điểm ngắt cho các mô hình Claude với prompt dài. Khác biệt của điểm cuối này là nó không thêm điểm ngắt nào: phần thân yêu cầu được chuyển tiếp đúng như bạn đã gửi, nên mọi điểm ngắt trong đó đều do bạn đặt.

# 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)

Giá của dòng Claude trên Kunavo:

• cache_read_input_tokens — được cung cấp từ bộ nhớ đệm, tính phí bằng 0.10× mức giá đầu vào (giảm 90%); 0.025× ở Claude Fable 5.1, 0.05× ở Claude Opus 5.5.
• cache_creation_input_tokens — được ghi vào bộ nhớ đệm, tính phí bằng 1.25× mức giá đầu vào. Kunavo tính phí cho thao tác ghi với TTL 1 giờ ở mức 1.25×, thấp hơn mức 2× của Anthropic.

Truyền dữ liệu theo luồng

Đặt stream: true (hoặc dùng hàm hỗ trợ stream() của SDK). Kunavo chuyển tiếp nguyên văn luồng sự kiện gốc của 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)

Hình ảnh

Gửi hình ảnh dưới dạng nguồn base64 hoặc url. Nguồn url là phần duy nhất trong nội dung yêu cầu mà Kunavo viết lại: Kunavo tự tải hình ảnh HTTPS xuống (hoặc giải nén URI data:) rồi chuyển tiếp dưới dạng base64, vì hệ thống ở nhà cung cấp gốc bỏ qua nguồn url và sẽ trả lời như thể không có hình ảnh nào được gửi. Hình ảnh bên trong tool_result cũng được xử lý tương tự. Giới hạn: 16 hình ảnh mỗi yêu cầu, 5 MB mỗi hình ảnh, tổng cộng 20 MB; nếu không thể tải hình ảnh về, hệ thống sẽ trả lỗi thay vì bỏ qua.

Đối tượng usage

Mỗi phản hồi (cũng như các sự kiện luồng message_delta / message_start) đều chứa đối tượng usage gốc của Anthropic:

Công cụ phía máy chủ

Các công cụ phía máy chủ của Anthropic (web_search, web_fetch, code_execution) được chuyển tiếp như các định nghĩa công cụ thông thường. Nội dung chúng bổ sung vào cuộc trò chuyện (kết quả tìm kiếm, trang được tải về, đầu ra chương trình) được trả về trong usage dưới dạng token và tính phí theo mức giá ở trên.

Tìm kiếm web còn bị tính phí theo mỗi lượt tìm kiếm, ngoài phí token: Anthropic niêm yết mức phí $10 cho mỗi 1.000 lượt tìm kiếm, còn Kunavo áp dụng mức này theo mức chiết khấu riêng của từng model. Số lượt được tính trong usage.server_tool_use.web_search_requests, trong phản hồi hoặc message_delta cuối cùng của luồng; lượt tìm kiếm trả về lỗi (chẳng hạn max_uses_exceeded) sẽ không được tính. Tải trang web và thực thi mã không mất phí ngoài phí token.

Các model được hỗ trợ

Mọi model Claude được bật đều chấp nhận /v1/messages. Gửi slug của Kunavo dưới dạng 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

Không hỗ trợ model GPT tại đây — hãy gọi chúng qua /v1/chat/completions.

HTTP thô

Không cần SDK — điểm cuối nhận yêu cầu POST JSON thuần:

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"}]
  }'

Tiếp theo nên xem gì

• Claude API trên Kunavo: mọi mô hình và giá của từng mô hình
• Chat completions tương thích OpenAI
• Cách tính phí (giá token, mức phí bộ nhớ đệm, phần cộng thêm)
• Duyệt tất cả mô hình chat