Đị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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const message = await client.messages.create({
model: "shannon-3",
max_tokens: 1024,
messages: [{ role: "user", content: "Say hello in one sentence." }],
});
for (const block of message.content) {
if (block.type === "text") console.log(block.text);
} curl https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "shannon-3",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Say hello in one sentence."}]
}' 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ó.
{
"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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const message = await 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 (const block of message.content) {
if (block.type === "thinking") console.log("reasoning:", block.thinking);
if (block.type === "text") console.log("answer:", block.text);
}
console.log(message.usage); curl https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"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?"}]
}' 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.
{
"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:
[
{
"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 đó:
[
{
"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:
[
{
"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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const stream = client.messages.stream({
model: "shannon-3",
max_tokens: 1024,
messages: [{ role: "user", content: "Explain server-sent events in three sentences." }],
});
stream.on("text", (text) => process.stdout.write(text));
const message = await stream.finalMessage();
console.log("\n", message.stop_reason, message.usage); curl -N https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "shannon-3",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Explain server-sent events in three sentences."}]
}' 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 đó.
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
{
"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 authenticationInvalid 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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const count = await client.messages.countTokens({
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?" }],
});
console.log(count.input_tokens); curl https://api.shannon-ai.com/v1/messages/count_tokens \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"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?"}]
}'
# {"input_tokens": 31} 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