Chuyển đến nội dung
Định dạng Anthropic

Định dạng Anthropic

POST /v1/messages nhận yêu cầu theo định dạng Anthropic Messages và trả lời theo cùng định dạng, dạng streaming hoặc không. Dùng với Anthropic SDK và các công cụ xây dựng trên nó, như Claude Code: đặt base URL, dùng Shannon API key của bạn và chỉ định một model id của Shannon.

POST https://api.shannon-ai.com/v1/messages

Trỏ Anthropic SDK tới base URL của Shannon. SDK thêm /v1/messages và gửi key của bạn trong header x-api-key.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Phản hồi là một message có content là danh sách các block. Hãy tìm các block theo type: khi model có suy luận, block đầu tiên là thinking và văn bản nằm sau nó.

200 JSON
{
  "id": "msg_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "type": "message",
  "role": "assistant",
  "model": "shannon-3",
  "content": [
    {
      "type": "thinking",
      "thinking": "The user wants a greeting in one sentence. Keep it short and friendly."
    },
    {
      "type": "text",
      "text": "Hello, it is good to meet you."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46
  }
}

Header

Header Giá trị Mô tả
x-api-key YOUR_API_KEY API key của bạn. Có thể dùng Authorization: Bearer YOUR_API_KEY thay thế.
content-type application/json Bắt buộc.
anthropic-version 2023-06-01 Được chấp nhận, không bắt buộc. Anthropic SDK gửi 2023-06-01; phản hồi có cùng định dạng bất kể giá trị nào.
anthropic-beta Được chấp nhận, không bắt buộc.
x-request-id Tùy chọn. Id riêng của bạn cho yêu cầu. Id này được trả về nguyên vẹn trong phản hồi; nếu không có, phản hồi mang một id gồm 12 ký tự thập lục phân.

Các trường yêu cầu

Chỉ messages là bắt buộc. Cột Áp dụng bởi nêu tên các model mà một trường làm thay đổi phản hồi. Các model open-weight hosted là mười hai id trong danh sách model; dòng Shannon 3 gồm shannon-3, shannon-3-pro, shannon-3.1 và shannon-3.1-pro. Model và giá

Trường Loại Mặc định Mô tả Áp dụng bởi
model string shannon-1.6-lite Một model id của Shannon từ danh sách model. Hãy gửi kèm trong mọi yêu cầu. Việc khớp tên không phân biệt chữ hoa chữ thường. Mọi tên khác trả về 400 unknown model, nên một công cụ tự gửi tên model riêng phải được đặt thành model id của Shannon. Tất cả model
messages array Bắt buộc. Cuộc hội thoại, tin nhắn cũ nhất trước, với các vai trò user và assistant. Xem Tin nhắn và content block bên dưới. Tất cả model
system string | array Chỉ dẫn cho model: một chuỗi hoặc một mảng các block văn bản. Xem System prompt bên dưới. Các model open-weight hosted, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Giới hạn trên của phản hồi, tính bằng token. Tùy chọn trên endpoint này; Anthropic SDK luôn gửi trường này. Giá trị ngoài khoảng 1 đến 65,536 sẽ được đưa về trong khoảng đó. Đây cũng là lượng được giữ lại từ số dư của bạn trong lúc yêu cầu chạy. Các model open-weight hosted, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true gửi phản hồi dưới dạng server-sent events. Xem Streaming bên dưới. Tất cả model
temperature number Temperature lấy mẫu. Trên các model open-weight hosted, giá trị được giữ trong khoảng từ 0 đến 2. Các model open-weight hosted, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Nucleus sampling. Các model open-weight hosted
stop_sequences array Tối đa 4 chuỗi. Câu trả lời kết thúc trước chuỗi đầu tiên xuất hiện. stop_reason vẫn là end_turn. Các model open-weight hosted
tools array Các tool mà model có thể gọi, mỗi tool có dạng {"name", "description", "input_schema"}. Xem Tools bên dưới. Tất cả model
tool_choice object {"type": "auto"} để model tự quyết định, {"type": "any"} buộc model gọi một tool, {"type": "tool", "name": "…"} buộc model gọi đúng tool đó. Các model open-weight hosted
thinking object Mức model suy luận trước khi trả lời. Xem Thinking bên dưới. Các model open-weight hosted
web_search boolean false Một phần bổ sung của Shannon cho định dạng này: true cho phép model tìm kiếm trên web trước khi trả lời. shannon-1.6-*, shannon-2-*, dòng Shannon 3

Khi không có max_tokens, giá trị là 4,096, và 65,536 trên shannon-coder-1.

Các metadata, top_k, service_tier và dấu cache_control trên block được chấp nhận để mã client hiện có chạy không cần sửa. Chúng không làm thay đổi phản hồi; prompt caching trên các model open-weight hosted là tự động.

Câu trả lời JSON theo một schema được yêu cầu bằng response_format trên Chat Completions và bằng text.format trên Responses. Đầu ra có cấu trúc

Yêu cầu có system prompt và thinking

Yêu cầu này gửi một system prompt, ngân sách thinking, temperature và một chuỗi dừng. Nó dùng một model open-weight hosted, áp dụng tất cả các tùy chọn đó.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    max_tokens=4096,
    system="You are a physics teacher. Answer in two sentences.",
    thinking={"type": "enabled", "budget_tokens": 2048},
    temperature=0.3,
    stop_sequences=["\n\n"],
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

for block in message.content:
    if block.type == "thinking":
        print("reasoning:", block.thinking)
    elif block.type == "text":
        print("answer:", block.text)
print(message.usage)

Trên các model open-weight hosted, usage báo cáo riêng số token đọc từ prompt cache, tách khỏi các token đầu vào khác.

200 JSON
{
  "usage": {
    "input_tokens": 31,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 62
  }
}

System prompt

system là một chuỗi, hoặc một mảng các block văn bản có dạng [{"type": "text", "text": "…"}]. Văn bản của các block được nối với nhau bằng dấu xuống dòng.

Được áp dụng bởi các model open-weight hosted, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro và shannon-coder-1. Với id thuộc dòng Shannon 3, hãy đặt các chỉ dẫn bắt buộc phải giữ vào tin nhắn của người dùng.

Tin nhắn và content block

Một tin nhắn có role, là user hoặc assistant, và content. content là một chuỗi hoặc một mảng các block.

Block Mô tả Có trên
{"type": "text", "text": "…"} Văn bản. Tất cả model
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
Một hình ảnh trong tin nhắn user, dưới dạng base64 hoặc qua URL. Dòng Shannon 3, shannon-1.6-lite, shannon-1.6-pro, và các model open-weight hosted có hỗ trợ đầu vào hình ảnh
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Một tài liệu (PDF, Word, PowerPoint hoặc Excel) trong tin nhắn user, dưới dạng base64 hoặc qua URL. Dòng Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Trong tin nhắn assistant: một lần gọi tool mà model đã thực hiện ở phản hồi trước. Tất cả model
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} Trong tin nhắn user: kết quả của lần gọi đó. content là một chuỗi hoặc một danh sách các block văn bản. Tất cả model

Bạn có thể gửi lại nguyên content của một phản hồi trước đó: block text và tool_use được đọc, block thinking bị bỏ qua.

Trên các bậc Shannon, hình ảnh và tài liệu được đọc từ tin nhắn user cuối cùng. Kích thước và giới hạn có trang riêng. Hình ảnh và tệp

Thinking

Các model open-weight hosted ánh xạ thinking sang một mức độ suy luận. Khi không có trường này, mức độ là cao.

Dạng budget_tokens Tác dụng
{"type": "disabled"} Không suy luận. Phản hồi không có block thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Mức độ thấp.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Mức độ trung bình.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Mức độ cao.

Model có suy luận trả về phần suy luận dưới dạng block {"type": "thinking", "thinking": "…"} đặt trước văn bản. Các bậc Shannon có suy luận cũng gửi phần này.

Các mức độ được mô tả ở trang riêng. Mức độ suy luận

Tools

Tool là một hàm do mã của bạn chạy. Mô tả từng tool bằng name, description và input_schema. Khi model muốn dùng một tool, phản hồi chứa block tool_use và stop_reason là tool_use.

Một định nghĩa tool trong tools:

tools
[
  {
    "name": "get_weather",
    "description": "Current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

content của một phản hồi gọi tool đó:

200 content
[
  {
    "type": "text",
    "text": ""
  },
  {
    "type": "tool_use",
    "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "input": {
      "city": "Paris"
    }
  }
]

Chạy tool, rồi gửi lại yêu cầu với lần gọi đó và một block tool_result được thêm vào messages:

messages
[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "name": "get_weather",
        "input": {
          "city": "Paris"
        }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "content": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
      }
    ]
  }
]

tool_choice

Dạng Tác dụng Áp dụng bởi
{"type": "auto"} Model tự quyết định có gọi tool hay không. Đây là mặc định. Tất cả model
{"type": "any"} Model phải gọi một trong các tool. Các model open-weight hosted
{"type": "tool", "name": "…"} Model phải gọi tool có tên được chỉ định. Các model open-weight hosted

Chỉ các tool có input_schema mới được đọc. Tìm kiếm web không phải là tool trên endpoint này: hãy đặt trường web_search.

Vòng lặp tool được mô tả đầy đủ ở trang riêng. Gọi hàm

Phản hồi

Trường Loại Mô tả Gửi bởi
id string msg_ theo sau là 32 ký tự thập lục phân. Tất cả model
type string Luôn là message. Tất cả model
role string Luôn là assistant. Tất cả model
model string Id chuẩn của model đã trả lời. Tất cả model
content array Các block của phản hồi, theo thứ tự này: thinking khi model có suy luận, text, rồi mỗi lần gọi tool một tool_use. Tất cả model
stop_reason string Lý do phản hồi kết thúc. Xem các giá trị bên dưới. Tất cả model
usage object input_tokens và output_tokens. Tất cả model
sources array Chỉ có trên yêu cầu gửi web_search: true mà lượt tìm kiếm tìm thấy kết quả: các kết quả đã đưa cho model, mỗi kết quả có index, title và url. [1] trong câu trả lời là mục có index bằng 1. Trong stream, nó đi cùng sự kiện message_delta. shannon-1.6-*, shannon-2-*, dòng Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens là phần của prompt được đọc từ cache; input_tokens là phần còn lại. cache_creation_input_tokens luôn là 0. Các model open-weight hosted

Các block của phản hồi

Block Mô tả
{"type": "thinking", "thinking": "…"} Phần suy luận của model. Không có thành phần signature.
{"type": "text", "text": "…"} Nội dung câu trả lời. Có thể rỗng khi phản hồi là một lần gọi tool.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Một lần gọi tool. input là một đối tượng JSON. Hãy gửi kết quả trở lại với cùng id.

stop_reason

stop_reason Mô tả Gửi bởi
end_turn Model đã hoàn tất câu trả lời, hoặc một trong các stop_sequences của bạn đã xuất hiện. Tất cả model
tool_use Phản hồi chứa một hoặc nhiều lần gọi tool. Tất cả model
max_tokens Phản hồi bị cắt ở giới hạn đầu ra. Dòng Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, trong stream

Streaming

Đặt stream thành true để nhận server-sent events. Mỗi frame có một dòng event: chứa tên sự kiện và một dòng data: chứa đối tượng JSON lặp lại tên đó trong type. Các stream helper của Anthropic SDK đọc các sự kiện này giúp bạn:

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

with client.messages.stream(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain server-sent events in three sentences."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    message = stream.get_final_message()

print()
print(message.stop_reason, message.usage)

Các sự kiện, theo thứ tự đến:

Sự kiện Dữ liệu Khi nào
message_start message Luôn đến đầu tiên. message chứa id, vai trò, model, content rỗng và usage bắt đầu từ không.
content_block_start index, content_block Một block mở ra. content_block là một block text hoặc thinking rỗng, hoặc một block tool_use cùng id và name của nó.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} Một đoạn của phần suy luận, cho block thinking.
content_block_delta index, delta {"type": "text_delta", "text"} Một đoạn của câu trả lời, cho block text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} Các đối số của một lần gọi tool, đầy đủ trong một delta, cho block tool_use.
content_block_stop index Block có index này đã hoàn tất.
message_delta delta {stop_reason, stop_sequence}, usage Phần cuối của phản hồi: delta.stop_reason và usage của yêu cầu.
message_stop Luôn đến cuối cùng.

Các block được đánh số bằng index theo thứ tự mở, và một block hoàn tất trước khi block tiếp theo mở. Hãy đọc từng block theo loại, không theo số: một stream có thể mở một block text rỗng trước, rồi block thinking, và đưa câu trả lời ở một block text sau đó.

200 text/event-stream
event: message_start
data: {"type":"message_start","message":{"id":"msg_5f0c…","type":"message","role":"assistant","model":"shannon-3","content":[],"usage":{"input_tokens":0,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Three sentences: what it is, how it is framed, why it is used."}}

event: ping
data: {"type": "ping"}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"text_delta","text":"Server-sent events let a server push text over one HTTP reply."}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":1190,"output_tokens":84}}

event: message_stop
data: {"type":"message_stop"}

Keep-alive

Gửi bởi Mô tả
Dòng Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Một sự kiện ping với dữ liệu {"type": "ping"}, cứ 15 giây một lần.
Các model open-weight hosted Một dòng chú thích : keepalive, cứ 15 giây một lần khi model đang xử lý.

Một stream bị lỗi

Một lỗi xảy ra sau khi stream đã bắt đầu là một sự kiện error có cùng nội dung với phản hồi lỗi: {"type": "error", "error": {"type", "message"}}. Các sự kiện kết thúc, message_delta và message_stop, vẫn theo sau. Hãy coi phản hồi là thất bại và gửi lại yêu cầu.

Lỗi

Lỗi dùng nội dung lỗi của Anthropic: type là error, và đối tượng error chứa type và message. Bảng liệt kê những gì endpoint này trả về thường xuyên nhất. Danh sách đầy đủ, kèm những lỗi nên thử lại, có trang riêng. Xử lý lỗi

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Trạng thái Loại Thông báo Khi nào
401 authentication_error Missing authentication
Invalid API key
Không có API key nào được gửi, hoặc key không xác định hoặc đã bị thu hồi.
400 invalid_request_error unknown model: <id> model không phải là model id của Shannon.
400 invalid_request_error No user message provided Các bậc Shannon: yêu cầu không có văn bản người dùng và không có tools.
400 invalid_request_error <id> does not accept image input Một hình ảnh đã được gửi tới model open-weight hosted không hỗ trợ đầu vào hình ảnh.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Thiếu messages, hoặc một trường có kiểu JSON sai.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens lớn hơn phần còn lại trong số dư của bạn.
429 rate_limit_error Too many requests. Retry in <n>s. Flood protection: hơn 120 yêu cầu trong một phút trên tài khoản của bạn.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: các lượt gọi Shannon Coder của gói bạn trong khung 4 giờ hiện tại đã dùng hết.
500 server_error The model backend failed to answer. Please retry. Model không tạo ra phản hồi. Hãy gửi lại yêu cầu.
502 api_error The model backend failed to answer. Please retry. Model không tạo ra phản hồi. Hãy gửi lại yêu cầu.

Đếm token

POST /v1/messages/count_tokens nhận cùng nội dung với một yêu cầu message (model, system, messages, tools) và trả về {"input_tokens": n}: số token đầu vào mà yêu cầu sẽ bị tính phí. Endpoint này đếm được cho các model open-weight hosted, miễn phí và không bị tính vào flood protection.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

count = client.messages.count_tokens(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    system="You are a physics teacher. Answer in two sentences.",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(count.input_tokens)

Việc đếm có trang riêng, với endpoint văn bản thuần và các giới hạn. Đếm token