Kudanwa kwemabasa
Tsanangura functions dzako mu-request uye model inopindura ne-calls yaunoda dzitwe. Code yako inodzimhanyisa ndokutumira mhedzisiro kudzoka: API inodzosa tool calls uye haimhanyise tool pachayo.
POST https://api.shannon-ai.com/v1/chat/completions
Ma-sample ari papeji rino anoshandisa /v1/chat/completions. Loop imwechete inomhanya pa-/v1/responses ne-/v1/messages; kwakanyorwa zvakasiyana ne-format, zvikamu zviri pazasi zvinoratidza ese matatu.
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"]
}
}
}]
}' Mhinduro yekutanga haipindure mubvunzo. Inokumbira 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}
}
} Mushure mekutumira mhedzisiro, mhinduro inotevera i-answer yakajairika: message.content ine text uye finish_reason i-stop.
Loop, danho nedanho
| Danho | Ani | Zvinoitika |
|---|---|---|
| 1 | Iwe | Tumira messages pamwe chete ne-tools, list ye-functions dzinogona kukumbirwa ne-model. |
| 2 | Model | Mhinduro inotakura tool_calls ne-finish_reason: "tool_calls". Call imwe neimwe inotumidza function uye inopa arguments dzayo. |
| 3 | Iwe | Parse arguments ye-call imwe neimwe uye umhanyise function yako. |
| 4 | Iwe | Wedzera assistant message ne-tool message imwe pa-call imwe mu-messages, wobva watumira request zvakare ne-tools dzimwechete. |
| 5 | Model | Model inopindura ne-text ine finish_reason: "stop", kana kukumbira calls dzimwe. Mune iyoyo nyaya dzokera ku-danho 3. |
Request imwe i-model turn imwe. API haichengeti hurukuro pakati pe-requests uye haiise huwandu hwe-rounds: code yako inochengeta messages uye inosarudza kuti inomira rinhi.
Kutsanangura tools
tools i-array ine entry imwe pa-function imwe. Model imwe neimwe yemu-catalogue inoigamuchira; GET /v1/models inoratidza capabilities.tools: true ye-id imwe neimwe.
| Field | Mhando | Tsananguro |
|---|---|---|
type | string | Inogara iri function. |
function.name | string | Zita rinoshandiswa ne-model kana ichikumbira function iyi. Rinodiwa. |
function.description | string | Zvinoitwa ne-function, mumashoko akajeka. |
function.parameters | object | Arguments se-JSON Schema ine type: "object" kumusoro. Tarisa Schema keywords pazasi. |
Endpoint imwe neimwe ine manyorerwo ayo e-tool. Tumira iyo yeendpoint yaunodanidzira:
{
"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 inoti model inogona, kana inofanira, kudanidzira tool. Inoverengwa pamwe chete ne-tools chete.
| Value | Tsananguro | Inoshandiswa ne |
|---|---|---|
"auto" | Model inosarudza kupindura nge-text kana kudanidzira tool. Iyi ndiyo default. | Ma-model ese |
"required" | Mhinduro inodanidzira tool imwe zvishoma. | Hosted open-weight models |
{"type": "function", "function": {"name": "get_weather"}} | Mhinduro inodanidzira function iyi. Zita rinofanira kuva rimwe re-functions dziri mu-tools. Calls kune dzimwe functions dzinosiiwa mumhinduro. | Hosted open-weight models |
Shannon models (shannon-*) dzinosarudza pa-request imwe neimwe, sezvakaita ne-auto.
Ne-required kana function yakatumidzwa, verenga finish_reason usati waverenga tool_calls. Kana model isingagadzire call, mhinduro i-text answer ine finish_reason: "stop".
| Zvinorehwa | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Model inosarudza | "auto" | "auto" | {"type": "auto"} |
| Danidzira tool imwe zvishoma | "required" | "required" | {"type": "any"} |
| Danidzira function imwe yakatumidzwa | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Dzinogamuchirwa kuti zvienderane: tool_choice: "none" ne-parallel_tool_calls. Pa-turn isina tool calls, tumira request isina tools.
Tool calls mumhinduro
| Field | Mhando | Tsananguro |
|---|---|---|
finish_reason | string | tool_calls kana mhinduro ine call imwe zvishoma. |
message.tool_calls | array | Entry imwe pa-call imwe. Field iripo chete kana model yakukumbira call. |
tool_calls[].id | string | call_ inoteverwa ne-hexadecimal characters 32. Idzorere se-tool_call_id pamwe chete nemhedzisiro. |
tool_calls[].type | string | Inogara iri function. |
tool_calls[].function.name | string | Function yekumhanyisa. |
tool_calls[].function.arguments | string | Arguments se-JSON string, "{}" kana dzisipo. Dzi-parse usati wadzishandisa. |
message.content | string | null | null kana mhinduro ine calls bedzi. Hosted open-weight models dzinogona kudzosa text padivi pe-calls; Shannon models dzinodzosa null. |
Call imwechete mu-format imwe neimwe. Pa-/v1/responses i-function_call item ye-output, ine arguments se-JSON string. Pa-/v1/messages i-tool_use content block ine input iri JSON object, id yayo inotanga ne-toolu_, uye stop_reason i-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 dzakawanda mu-turn imwe
Mhinduro inogona kutakura calls dzakawanda. Dzimhanyise dzese uye utumire mhedzisiro imwe pa-call imwe, imwe neimwe ine tool_call_id yayo, mu-request inotevera.
Hosted open-weight models dzinodzosa call imwe neimwe yakasiyana kamwe: calls mbiri dzine zita rimwechete uye arguments dzimwechete dzinouya sechimwe.
Streamed tool calls
Ne-stream: true, call inouya yakazara: chunk ine arguments string yakazara, saka hapana zvimedu zvekubatanidza. index inoverenga calls dze-turn kubva pa-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 | Zvinouya |
|---|---|
/v1/chat/completions | chat.completion.chunk imwe pa-call imwe, ine call mu-delta.tool_calls[0]. Chunk yekupedzisira ine finish_reason: "tool_calls" ne-usage. |
/v1/responses | Pa-call imwe: response.output_item.added (function_call item ine arguments isina chinhu), response.function_call_arguments.delta (string yose), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Pa-call imwe: content_block_start (tool_use block ine input isina chinhu), content_block_delta imwe ine input_json_delta.partial_json iri arguments text yose, content_block_stop. message_delta inobva yatakura stop_reason: "tool_use". |
Pa-shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ne-shannon-coder-1, request ye-stream inotakura tools inounza text yemhinduro mu-content delta imwe pakupera kwe-turn. Kuyerera
Kutumira mhedzisiro kudzoka
Request yechipiri inodzokorora hurukuro uye inowedzera zvinhu zviviri: assistant turn yakakumbira calls, nemhedzisiro imwe pa-call imwe.
{
"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\"}"
}
]
}
]
} - Dzorera assistant turn sezvawainge wakaiwana, pamberi pemhedzisiro. Mhedzisiro imwe neimwe inowirirana ne-call yayo nge-id:
tool_call_idpa-/v1/chat/completions,call_idpa-/v1/responses,tool_use_idpa-/v1/messages. - Mhedzisiro i-text. Shandura object kuita JSON string ye-
content(outputpa-/v1/responses). Pa-/v1/messagescontentye-tool_resultblock i-string kana list ye-text blocks. - Mu-assistant turn,
function.argumentsinoramba iri JSON string, sezvayakasvika. - Hurukuro inogona kupera ne-tool result. Hapana user message itsva inodiwa: model inoenderera kubva pamhedzisiro.
- Kana function yako ikundikana, tumira kundikana se-result text. Model inobva yaigona kuiudza kana kukumbira call imwe.
Schema keywords
parameters (input_schema pa-/v1/messages) i-JSON Schema. Mhuri ye-Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ne-hosted open-weight models dzinoigamuchira sezvaunotumira.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ne-shannon-coder-1 dzinogamuchira subset iyi, pa-endpoints dzese nhatu:
| Kubatwa | Keywords |
|---|---|
| Inoverengwa sezvatumirwa | Keyword imwe neimwe isina kutumidzwa mumarow ari pazasi, semuenzaniso type, properties, required, items, enum, description, minimum, maximum, anyOf ne-allOf, pa-level imwe neimwe ye-schema. |
format | Inoverengwa pa-values int32, int64, float, double, byte, date, date-time ne-enum. |
oneOf | Inoverengwa se-anyOf. |
| Haisi chikamu che-schema inogamuchirwa nema-model aya | $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 ne-exclusiveMaximum kana ari manhamba; mamwe values e-format. |
Hunhu ne-limits
- API haiise maximum ye-tools uye haiise maximum ye-rounds.
- Request body inogona kusvika ku-32 MiB, uye hurukuro pamwe nemhedzisiro yayo inofanira kukwana mu-context window ye-model.
- Kana request ichitakura
tools,shannon-1.6-lite,shannon-1.6-pro,shannon-2-litene-shannon-2-prodzinoshandisa defaulttemperatureye-0.2. Tumiratemperaturekuti uise value imwe. - Round imwe neimwe i-request yayo pachayo: inotora kubva mu-balance yako uye inoverengwa mu-flood protection semamwe ma-request ese. Limits ne-balance
Errors
Tool call i-reply yakajairika ine status 200. Ma-error aya anoreva request pachayo:
| Status | Mhando | Message | Rinhi |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model haisi id yemu-published list. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools haisi array, kana imwe field ine JSON type isiriyo. |
413 | invalid_request_error | Failed to buffer the request body: … | Request body yakakura kupfuura 32 MiB. Error inotakura code: "request_too_large". |
Model ndiyo inonyora arguments. Dzitarise nechishandiso che-schema yako usati wamhanyisa function, sezvaungatarisa input yega yega yekunze.
Authentication, balance ne-server errors zvakafanana nepa-request imwe neimwe. Zvikanganiso