Đầu ra có cấu trúc
Yêu cầu câu trả lời dưới dạng JSON: một đối tượng JSON bất kỳ, hoặc JSON theo schema bạn gửi. Hãy dùng khi chương trình, chứ không phải con người, đọc phản hồi.
POST https://api.shannon-ai.com/v1/chat/completions
import json
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")
response = client.chat.completions.create(
model="Kimi-K3-3BIT-REAP",
messages=[
{"role": "user", "content": "Extract the person: John Doe, 30 years old, engineer."}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "person",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"occupation": {"type": "string"},
},
"required": ["name", "age", "occupation"],
},
},
},
)
# The JSON arrives as text in message.content: parse it, then check it.
try:
person = json.loads(response.choices[0].message.content)
except json.JSONDecodeError:
person = None # ask again, or report the failure
print(person) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const response = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
messages: [
{ role: "user", content: "Extract the person: John Doe, 30 years old, engineer." },
],
response_format: {
type: "json_schema",
json_schema: {
name: "person",
strict: true,
schema: {
type: "object",
properties: {
name: { type: "string" },
age: { type: "integer" },
occupation: { type: "string" },
},
required: ["name", "age", "occupation"],
},
},
},
});
// The JSON arrives as text in message.content: parse it, then check it.
let person = null;
try {
person = JSON.parse(response.choices[0].message.content);
} catch {
// ask again, or report the failure
}
console.log(person); 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": "Extract the person: John Doe, 30 years old, engineer."}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "person",
"strict": true,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"occupation": {"type": "string"}
},
"required": ["name", "age", "occupation"]
}
}
}
}' JSON là văn bản của câu trả lời, trong choices[0].message.content:
{
"id": "chatcmpl-0c4e7a1b9d2f4e6a8b3c5d7e9f1a2b3c",
"object": "chat.completion",
"created": 1791590400,
"model": "Kimi-K3-3BIT-REAP",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
"reasoning_content": null
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 96,
"completion_tokens": 19,
"total_tokens": 115,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 0}
}
} Các chế độ của response_format
response_format là một trường của /v1/chat/completions. Không có nó, câu trả lời là văn bản thông thường.
| Chế độ | Giá trị | Bạn nhận được gì |
|---|---|---|
| Đối tượng JSON | {"type": "json_object"} | Câu trả lời là JSON không có hình dạng quy định. Hãy nêu trong prompt những key bạn muốn. |
| JSON schema | {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} | Câu trả lời tuân theo schema bạn gửi: các key, kiểu và trường bắt buộc của nó. |
| Strict | "strict": true | Một trường của json_schema, không phải chế độ thứ ba. Nó là true trừ khi bạn gửi false. |
| Trường | Loại | Mặc định | Mô tả | Áp dụng bởi |
|---|---|---|---|---|
type | string | json_object hoặc json_schema. Bắt buộc bên trong response_format. text được chấp nhận và cho câu trả lời văn bản thông thường. | Mọi model nhận chế độ này | |
json_schema.schema | object | JSON Schema mà câu trả lời tuân theo. Hãy gửi nó bất cứ khi nào type là json_schema. | Mọi model nhận chế độ này | |
json_schema.name | string | Nhãn cho schema, như trong định dạng OpenAI. | Các model open-weight hosted | |
json_schema.strict | boolean | true | Câu trả lời có phải tuân theo schema chính xác hay không. Các model Shannon áp dụng mọi schema ở chế độ strict. | Các model open-weight hosted |
Chế độ đối tượng JSON không cần schema. Hãy nêu các key trong prompt:
{
"model": "shannon-3",
"messages": [
{
"role": "user",
"content": "Name the capital of France. Answer as JSON with the keys city and country."
}
],
"response_format": {"type": "json_object"}
} Hỗ trợ theo từng model
| Model | json_object | json_schema |
|---|---|---|
Mọi model Shannon (shannon-*) | Có | Có |
| Các model open-weight hosted, trừ những model được nêu bên dưới | Có | Có |
Laguna-S-2.1-W4A16-AUTOROUND-REAP | — | — |
inkling-W4A16-AUTOROUND-REAP | Có | — |
GET /v1/models báo cáo điều tương tự cho từng id: capabilities.json_schema trên mọi model, và capabilities.response_format trên các model open-weight hosted. Model và giá
Các từ khóa schema được hỗ trợ
Những gì model nhận được từ schema của bạn phụ thuộc vào model và endpoint:
| Model | /v1/chat/completions | /v1/responses |
|---|---|---|
| Các model Shannon | Tập con từ khóa bên dưới, được áp dụng ở chế độ strict. | Schema đúng như bạn gửi, được áp dụng ở chế độ strict. |
| Các model open-weight hosted | Schema đúng như bạn gửi. strict là true trừ khi bạn gửi nó. | Schema đúng như bạn gửi. strict là true trừ khi bạn gửi nó. |
Tập con từ khóa của các model Shannon trên /v1/chat/completions:
| Từ khóa | Cách nó được đọc |
|---|---|
| Từ khóa được đọc | type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default |
$ref | Được phân giải từ $defs hoặc definitions ở cấp cao nhất của schema. Các từ khóa viết cạnh $ref, như description, được giữ lại. Tham chiếu không có định nghĩa tương ứng được đọc là {"type": "object"}. |
allOf | Các thành viên được gộp thành một schema. Khi hai thành viên đặt cùng một từ khóa, thành viên sau được ưu tiên. |
oneOf | Được đọc như anyOf. |
| Schema tham chiếu đến chính nó | Được mở rộng đến 24 cấp. Cấp sâu hơn được đọc là {"type": "object"}. |
| Ngoài tập con | Mọi từ khóa khác, ví dụ additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not và if / then / else. Chúng không nằm trong schema mà model nhận. |
Trên /v1/responses: text.format
/v1/responses viết cùng yêu cầu đó là text.format. Schema nằm trực tiếp trong format, cạnh name và strict, không nằm dưới key json_schema. Với chế độ đối tượng JSON, hãy gửi {"format": {"type": "json_object"}}.
{
"model": "Kimi-K3-3BIT-REAP",
"input": "Extract the person: John Doe, 30 years old, engineer.",
"text": {
"format": {
"type": "json_schema",
"name": "person",
"strict": true,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"occupation": {"type": "string"}
},
"required": ["name", "age", "occupation"]
}
}
}
} JSON là text của phần output_text trong mục message:
{
"output": [
{
"id": "msg_7e1d3c5b9a2f4d6e8c0b1a3f5e7d9c2b",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
"annotations": []
}
]
}
]
} Hỗ trợ theo từng model và các lỗi giống như trên /v1/chat/completions. Responses API
Trên /v1/messages: một tool làm schema
Định dạng Messages không có trường đầu ra có cấu trúc. Để lấy JSON từ cùng các model đó, hãy gọi /v1/chat/completions hoặc /v1/responses với cùng key.
Để ở lại trên /v1/messages, hãy mô tả đối tượng như một tool: đặt schema của bạn vào input_schema và nêu tên tool trong tool_choice. Khi đó input của khối tool_use là đối tượng của bạn, đã được phân tích sẵn. tool_choice có tên được áp dụng bởi các model open-weight hosted.
{
"model": "Kimi-K3-3BIT-REAP",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Extract the person: John Doe, 30 years old, engineer."
}
],
"tools": [
{
"name": "record_person",
"description": "Record the extracted person.",
"input_schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"occupation": {"type": "string"}
},
"required": ["name", "age", "occupation"]
}
}
],
"tool_choice": {"type": "tool", "name": "record_person"}
} {
"stop_reason": "tool_use",
"content": [
{
"type": "tool_use",
"id": "toolu_4b8d2f6a1c3e4a5b9d7f0e2c4a6b8d1f",
"name": "record_person",
"input": {"name": "John Doe", "age": 30, "occupation": "engineer"}
}
]
} Hãy kiểm tra stop_reason là tool_use trước khi đọc khối. Gọi hàm
JSON đến như thế nào
- JSON là một chuỗi. Phản hồi không có đối tượng đã phân tích đi kèm: hãy chạy trình phân tích JSON của bạn trên
message.content. - Với
stream: true, JSON đến thành từng đoạndelta.content. Hãy ghép chúng lại và phân tích sau khi stream kết thúc; một đoạn riêng lẻ không phải là JSON hợp lệ. - Model open-weight hosted trả lời yêu cầu có
response_formatmà không có văn bản suy luận:reasoning_contentlànull.
Kiểm tra những gì bạn nhận được
Schema định hướng cách model viết. API không so sánh câu trả lời hoàn chỉnh với schema của bạn, nên mã của bạn thực hiện bước kiểm tra cuối:
- Hãy phân tích bên trong một trình xử lý lỗi, như ví dụ ở đầu trang.
- Hãy xác thực đối tượng đã phân tích bằng cùng schema trong mã của bạn, ví dụ với thư viện JSON Schema, Pydantic hoặc Zod.
- Một câu trả lời dài có thể kết thúc trước khi JSON hoàn chỉnh. Phản hồi không streaming chỉ báo cáo
finish_reasonlàstophoặctool_calls, nên lỗi phân tích là tín hiệu. Hãy hỏi lại, hoặc yêu cầu một đối tượng nhỏ hơn.
Lỗi
| Trạng thái | Loại | Thông báo | Khi nào |
|---|---|---|---|
400 | invalid_request_error | <id> does not accept response_format | Model không nhận chế độ nào trong hai chế độ. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | Model nhận json_object và bạn đã gửi json_schema. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | response_format không có type, hoặc không phải là đối tượng JSON. |
Hai phản hồi 400 được gửi trước khi có gì bị trừ khỏi số dư của bạn. Xử lý lỗi