Oku ọrụ
Kọwaa functions gị na request, model ga-aza site na calls ọ chọrọ ka e mee. Koodu gị na-agba ha ma zighachi results: API na-eweghachi tool calls, ọ naghị agba tool n'onwe ya.
POST https://api.shannon-ai.com/v1/chat/completions
Samples dị na peeji a na-eji /v1/chat/completions. Otu loop ahụ na-agba na /v1/responses na /v1/messages; ebe format na-ede ihe n'ụzọ ọzọ, akụkụ ndị dị n'okpuru na-egosi atọ ahụ niile.
import json
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, for example Paris"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["city"],
},
},
}]
def get_weather(city, unit="celsius"):
# Your code: ask a weather service here.
return {"city": city, "temperature": 18, "unit": unit, "conditions": "cloudy"}
messages = [{"role": "user", "content": "What is the weather in Paris right now?"}]
answer = None
for _ in range(5): # the API sets no limit on rounds: set your own
response = client.chat.completions.create(
model="Kimi-K3-3BIT-REAP",
messages=messages,
tools=tools,
)
choice = response.choices[0]
if choice.finish_reason != "tool_calls":
answer = choice.message.content
break
messages.append(choice.message) # the assistant turn with its tool_calls
for call in choice.message.tool_calls:
args = json.loads(call.function.arguments) # arguments is a JSON string
result = get_weather(**args)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
print(answer) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const tools = [{
type: "function",
function: {
name: "get_weather",
description: "Get the current weather for a city.",
parameters: {
type: "object",
properties: {
city: { type: "string", description: "City name, for example Paris" },
unit: { type: "string", enum: ["celsius", "fahrenheit"] },
},
required: ["city"],
},
},
}];
// Your code: ask a weather service here.
function getWeather({ city, unit = "celsius" }) {
return { city, temperature: 18, unit, conditions: "cloudy" };
}
const messages = [{ role: "user", content: "What is the weather in Paris right now?" }];
let answer = null;
// The API sets no limit on rounds: set your own.
for (let round = 0; round < 5; round++) {
const response = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
messages,
tools,
});
const choice = response.choices[0];
if (choice.finish_reason !== "tool_calls") {
answer = choice.message.content;
break;
}
messages.push(choice.message); // the assistant turn with its tool_calls
for (const call of choice.message.tool_calls) {
const args = JSON.parse(call.function.arguments); // arguments is a JSON string
messages.push({
role: "tool",
tool_call_id: call.id,
content: JSON.stringify(getWeather(args)),
});
}
}
console.log(answer); # 1. Send the conversation with the tools.
curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"}
],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, for example Paris"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
}
}]
}'
# 2. Run the function yourself, then send the assistant turn and the result.
# Use the id of the call you received.
curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{"role": "assistant", "content": null, "tool_calls": [{
"id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"type": "function",
"function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}
}]},
{"role": "tool", "tool_call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"content": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"}
],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, for example Paris"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
}
}]
}' Azịza mbụ anaghị aza ajụjụ ahụ. Ọ na-arịọ call:
{
"id": "chatcmpl-5b0c1d8e7f6a4b3c9d2e1f0a8b7c6d5e",
"object": "chat.completion",
"created": 1791590400,
"model": "Kimi-K3-3BIT-REAP",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"reasoning_content": "The user asks for the current weather in Paris. I should call get_weather.",
"tool_calls": [
{
"id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 312,
"completion_tokens": 58,
"total_tokens": 370,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 31}
}
} Mgbe ị zipụrụ result, azịza na-esote bụ azịza nkịtị: message.content nwere text, finish_reason bụkwa stop.
Loop ahụ, nzọụkwụ site na nzọụkwụ
| Nzọụkwụ | Onye | Ihe na-eme |
|---|---|---|
| 1 | Gị | Zipụ messages ya na tools, ndepụta functions model nwere ike ịrịọ. |
| 2 | Model | Azịza ahụ nwere tool_calls na finish_reason: "tool_calls". Call ọ bụla na-akpọ function ma nye arguments ya. |
| 3 | Gị | Parse arguments nke call ọ bụla ma gbaa function gị. |
| 4 | Gị | Tinye assistant message na otu tool message maka call ọ bụla na messages, wee zighachi request ahụ na otu tools. |
| 5 | Model | Model na-aza na text nwere finish_reason: "stop", ma ọ bụ na-arịọ calls ndị ọzọ. N'okwu ahụ laghachi na nzọụkwụ 3. |
Otu request bụ otu model turn. API anaghị edebe mkparịta ụka n'etiti requests ma ọ naghị atọ ọnụọgụ gburugburu: koodu gị na-ejide messages ma kpebie mgbe a ga-akwụsị.
Ịkọwa tools
tools bụ array nwere otu entry maka function ọ bụla. Model ọ bụla nke catalogue na-anabata ya; GET /v1/models na-akọ capabilities.tools: true maka id ọ bụla.
| Field | Ụdị | Nkọwa |
|---|---|---|
type | string | Mgbe niile function. |
function.name | string | Aha model na-eji mgbe ọ na-arịọ function a. Achọrọ. |
function.description | string | Ihe function na-eme, n'asụsụ dị mfe. |
function.parameters | object | Arguments dị ka JSON Schema nwere type: "object" n'elu. Lee Schema keywords n'okpuru. |
Endpoint ọ bụla nwere otu o si ede tool. Zipụ nke bụ nke endpoint ị na-akpọ:
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, for example Paris"
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
}
} {
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, for example Paris"
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
} {
"name": "get_weather",
"description": "Get the current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, for example Paris"
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
} tool_choice
tool_choice na-ekwu ma model nwere ike, ma ọ bụ ga-akpọ tool. A na-agụ ya naanị ya na tools.
| Uru | Nkọwa | Ndị na-etinye ya |
|---|---|---|
"auto" | Model na-ekpebi ma ọ ga-aza na text ka ọ ga-akpọ tool. Nke a bụ default. | Models niile |
"required" | Azịza ahụ na-akpọ opekata mpe otu tool. | Hosted open-weight models |
{"type": "function", "function": {"name": "get_weather"}} | Azịza ahụ na-akpọ function a. Aha ahụ ga-abụ otu n'ime functions dị na tools. A na-ahapụ calls maka functions ndị ọzọ n'azịza ahụ. | Hosted open-weight models |
Shannon models (shannon-*) na-ekpebi n'ime request ọ bụla, dị ka site na auto.
Site na required ma ọ bụ function akpọrọ aha, gụọ finish_reason tupu ị gụọ tool_calls. Mgbe model emepụtaghị call, azịza bụ text nwere finish_reason: "stop".
| Nkọwa | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Model na-ekpebi | "auto" | "auto" | {"type": "auto"} |
| Kpọọ opekata mpe otu tool | "required" | "required" | {"type": "any"} |
| Kpọọ otu function akpọrọ aha | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Anabatara maka ndakọrịta: tool_choice: "none" na parallel_tool_calls. Maka turn na-enweghị tool calls, zipụ request na-enweghị tools.
Tool calls n'azịza
| Field | Ụdị | Nkọwa |
|---|---|---|
finish_reason | string | tool_calls mgbe azịza ahụ nwere opekata mpe otu call. |
message.tool_calls | array | Otu entry maka call ọ bụla. Field ahụ dị naanị mgbe model rịọrọ call. |
tool_calls[].id | string | call_ sochiri mkpụrụedemede hexadecimal 32. Zighachi ya dị ka tool_call_id na result. |
tool_calls[].type | string | Mgbe niile function. |
tool_calls[].function.name | string | Function a ga-arụ. |
tool_calls[].function.arguments | string | Arguments dị ka JSON string, "{}" mgbe ọ nweghị. Parse ya tupu ojiji. |
message.content | string | null | null mgbe azịza nwere naanị calls. Hosted open-weight models nwere ike ịweghachi text n'akụkụ calls; Shannon models na-eweghachi null. |
Otu call ahụ n'format ọ bụla. Na /v1/responses ọ bụ item function_call nke output, nwere arguments dị ka JSON string. Na /v1/messages ọ bụ tool_use content block nke input ya bụ JSON object, id ya na-amalite na toolu_, stop_reason bụkwa tool_use.
{
"finish_reason": "tool_calls",
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
}
}
]
}
} {
"output": [
{
"id": "fc_3d2c1b0a9f8e4d7c6b5a4f3e2d1c0b9a",
"type": "function_call",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}",
"status": "completed"
}
]
} {
"stop_reason": "tool_use",
"content": [
{
"type": "tool_use",
"id": "toolu_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"input": {"city": "Paris"}
}
]
} Calls dị iche iche n'otu turn
Azịza nwere ike ibu calls dị iche iche. Gbaa ha niile ma zipụ otu result maka call ọ bụla, nke ọ bụla na tool_call_id nke ya, na request na-esote.
Hosted open-weight models na-eweghachi call ọ bụla dị iche otu ugboro: calls abụọ nwere otu aha na otu arguments na-abịa dị ka otu.
Tool calls na stream
Site na stream: true, call na-abịa n'otu akụkụ: chunk nwere string arguments zuru ezu, ya mere enweghị iberibe a ga-ejikọta. index na-agụ calls nke turn site na 0.
{
"id": "chatcmpl-5b0c1d8e7f6a4b3c9d2e1f0a8b7c6d5e",
"object": "chat.completion.chunk",
"created": 1791590400,
"model": "Kimi-K3-3BIT-REAP",
"choices": [
{
"index": 0,
"delta": {
"tool_calls": [
{
"index": 0,
"id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
}
}
]
},
"finish_reason": null
}
]
} | Endpoint | Ihe na-abịa |
|---|---|
/v1/chat/completions | Otu chat.completion.chunk maka call ọ bụla, na call ahụ na delta.tool_calls[0]. Chunk ikpeazụ nwere finish_reason: "tool_calls" na usage. |
/v1/responses | Maka call ọ bụla: response.output_item.added (item function_call nwere arguments efu), response.function_call_arguments.delta (string dum), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Maka call ọ bụla: content_block_start (tool_use block nwere input efu), otu content_block_delta nke input_json_delta.partial_json ya bụ ederede arguments dum, content_block_stop. Mgbe ahụ message_delta nwere stop_reason: "tool_use". |
Na shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro na shannon-coder-1, request stream nwere tools na-ebuga ederede azịza ya n'otu content delta na njedebe nke turn. Nzipu ozugbo
Izighachi results
Request nke abụọ na-ekwughachi mkparịta ụka ma na-agbakwunye ihe abụọ: assistant turn rịọrọ calls, na otu result maka call ọ bụla.
{
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"content": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"
}
]
} {
"input": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{
"type": "function_call",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
},
{
"type": "function_call_output",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"output": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"
}
]
} {
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"input": {"city": "Paris"}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"content": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"
}
]
}
]
} - Zighachi assistant turn dị ka ị natara ya, tupu results. A na-ejikọta result ọ bụla na call ya site na id:
tool_call_idna/v1/chat/completions,call_idna/v1/responses,tool_use_idna/v1/messages. - Result bụ text. Mee serialise object ka ọ bụrụ JSON string maka
content(outputna/v1/responses). Na/v1/messagescontentnketool_resultblock bụ string ma ọ bụ ndepụta text blocks. - N'assistant turn,
function.argumentska bụ JSON string, kpọmkwem dị ka o si bịa. - Mkparịta ụka nwere ike ịgwụ na tool result. Achọghị user message ọhụrụ: model na-aga n'ihu site na result ahụ.
- Mgbe function gị daa, zipụ ọdịda ahụ dị ka result text. Model nwere ike ịkọ ya ma ọ bụ rịọ call ọzọ.
Schema keywords
parameters (input_schema na /v1/messages) bụ JSON Schema. Shannon 3 family (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) na hosted open-weight models na-anata ya dị ka ị zipụrụ ya.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro na shannon-coder-1 na-anata subset a, na endpoints atọ ahụ niile:
| Ọgwụgwọ | Keywords |
|---|---|
| A na-agụ dị ka e zipụrụ | Keyword ọ bụla akpọbeghị aha n'ahịrị dị n'okpuru, dịka type, properties, required, items, enum, description, minimum, maximum, anyOf na allOf, n'ọkwa ọ bụla nke schema. |
format | A na-agụ maka uru int32, int64, float, double, byte, date, date-time na enum. |
oneOf | A na-agụ dị ka anyOf. |
| Abụghị akụkụ nke schema models ndị a na-anata | $schema, $id, $ref, $defs, $comment, definitions, additionalProperties, unevaluatedProperties, patternProperties, propertyNames, examples, default, title, const, not, if, then, else, contains, minContains, maxContains, dependentRequired, dependentSchemas, dependencies, readOnly, writeOnly, deprecated, contentEncoding, contentMediaType, contentSchema, multipleOf, uniqueItems; exclusiveMinimum na exclusiveMaximum mgbe ha bụ ọnụọgụ; uru ndị ọzọ nke format. |
Omume na limits
- API anaghị atọ oke ọnụọgụ tools, ọ naghịkwa atọ oke ọnụọgụ gburugburu.
- Request body nwere ike ịbụ ruo 32 MiB, mkparịta ụka na results ya ga-abakwa n'ime context window nke model.
- Mgbe request nwere
tools,shannon-1.6-lite,shannon-1.6-pro,shannon-2-litenashannon-2-prona-eji defaulttemperaturenke 0.2. Zipụtemperatureiji tọọ uru ọzọ. - Gburugburu ọ bụla bụ request nke ya: ọ na-ewepụ site na balance gị ma na-agụ n'ime flood protection dị ka request ọ bụla ọzọ. Limits na balance
Njehie
Tool call bụ azịza nkịtị nwere status 200. Njehie ndị a metụtara request n'onwe ya:
| Status | Ụdị | Ozi | Mgbe |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model abụghị id dị na ndepụta e bipụtara. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools abụghị array, ma ọ bụ field ọzọ nwere JSON type na-ezighi ezi. |
413 | invalid_request_error | Failed to buffer the request body: … | Request body buru ibu karịa 32 MiB. Njehie ahụ nwere code: "request_too_large". |
Model na-ede arguments. Lelee ha megide schema gị tupu ị gbaa function ahụ, dị ka ị ga-eme maka input ọ bụla si n'èzí.
Authentication, balance na njehie server bụ otu ihe ahụ dị ka maka request ọ bụla. Njikwa njehie