Matokeo yaliyopangwa

Omba jibu kama JSON: kitu chochote cha JSON, au JSON inayofuata schema unayotuma. Itumie programu, si mtu, inaposoma jibu.

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 ni maandishi ya jibu, kwenye choices[0].message.content:

200 JSON

{
  "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}
  }
}

Hali za response_format

response_format ni field ya /v1/chat/completions. Bila hiyo jibu ni maandishi ya kawaida.

Hali	Thamani	Unachopata
Kitu cha JSON	`{"type": "json_object"}`	Jibu ni JSON bila umbo lililoagizwa. Sema kwenye prompt ni keys zipi unazotaka.
JSON schema	`{"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}}`	Jibu linafuata schema unayotuma: keys zake, aina zake na fields zinazohitajika.
Strict	`"strict": true`	Field ya `json_schema`, si hali ya tatu. Ni `true` usipotuma `false`.

Field	Aina	Chaguo-msingi	Maelezo	Inatumiwa na
`type`	`string`		`json_object` au `json_schema`. Inahitajika ndani ya `response_format`. `text` inakubaliwa na hutoa jibu la kawaida la maandishi.	Kila model inayokubali hali hiyo
`json_schema.schema`	`object`		JSON Schema ambayo jibu linafuata. Itume kila wakati `type` ni `json_schema`.	Kila model inayokubali hali hiyo
`json_schema.name`	`string`		Lebo ya schema, kama kwenye umbizo la OpenAI.	Model za open-weight zinazopangishwa
`json_schema.strict`	`boolean`	`true`	Kama jibu lazima lifuate schema kikamilifu. Model za Shannon hutumia kila schema kama strict.	Model za open-weight zinazopangishwa

Hali ya kitu cha JSON haihitaji schema. Taja keys kwenye prompt:

Mwili wa ombi

{
  "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"}
}

Msaada kwa kila model

Model	`json_object`	`json_schema`
Kila model ya Shannon (`shannon-*`)	Ndiyo	Ndiyo
Model za open-weight zinazopangishwa, isipokuwa zile zilizotajwa hapa chini	Ndiyo	Ndiyo
`Laguna-S-2.1-W4A16-AUTOROUND-REAP`	—	—
`inkling-W4A16-AUTOROUND-REAP`	Ndiyo	—

GET /v1/models huripoti vivyo hivyo kwa kila id: capabilities.json_schema kwenye kila model, na capabilities.response_format kwenye model za open-weight zinazopangishwa. Model na bei

Keywords za schema zinazoungwa mkono

Kile model inapokea cha schema yako kinategemea model na endpoint:

Model	`/v1/chat/completions`	`/v1/responses`
Model za Shannon	Sehemu ndogo ya keywords iliyo hapa chini, inatumika kama strict.	Schema kama unavyoituma, inatumika kama strict.
Model za open-weight zinazopangishwa	Schema kama unavyoituma. `strict` ni `true` usipoituma.	Schema kama unavyoituma. `strict` ni `true` usipoituma.

Sehemu ndogo ya keywords ya model za Shannon kwenye /v1/chat/completions:

Keyword	Jinsi inavyosomwa
Keywords zinazosomwa	`type`, `format`, `title`, `description`, `nullable`, `enum`, `items`, `properties`, `required`, `minItems`, `maxItems`, `minimum`, `maximum`, `minLength`, `maxLength`, `pattern`, `anyOf`, `default`
`$ref`	Hutatuliwa kutoka `$defs` au `definitions` katika ngazi ya juu ya schema. Keywords zilizoandikwa kando ya `$ref`, kama `description`, huhifadhiwa. Rejeleo lisilo na ufafanuzi unaolingana husomwa kama `{"type": "object"}`.
`allOf`	Members huunganishwa kuwa schema moja. Members wawili wakiweka keyword ile ile, ya baadaye ndiyo inayohesabiwa.
`oneOf`	Husomwa kama `anyOf`.
Schemas zinazojirejelea zenyewe	Hupanuliwa hadi ngazi 24. Ngazi ya ndani zaidi husomwa kama `{"type": "object"}`.
Nje ya sehemu hiyo ndogo	Kila keyword nyingine, kwa mfano `additionalProperties`, `const`, `multipleOf`, `uniqueItems`, `exclusiveMinimum`, `exclusiveMaximum`, `patternProperties`, `prefixItems`, `minProperties`, `maxProperties`, `not` na `if` / `then` / `else`. Hizi si sehemu ya schema ambayo model inapokea.

Kwenye /v1/responses: text.format

/v1/responses huandika ombi lile lile kama text.format. Schema iko moja kwa moja kwenye format, kando ya name na strict, si chini ya key ya json_schema. Kwa hali ya kitu cha JSON tuma {"format": {"type": "json_object"}}.

Mwili wa ombi

{
  "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 ni text ya sehemu ya output_text ya item ya message:

200 JSON

{
  "output": [
    {
      "id": "msg_7e1d3c5b9a2f4d6e8c0b1a3f5e7d9c2b",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
          "annotations": []
        }
      ]
    }
  ]
}

Msaada kwa kila model na makosa ni yale yale kama kwenye /v1/chat/completions. Responses API

Kwenye /v1/messages: tool kama schema

Umbizo la Messages halina field ya matokeo yaliyopangwa. Kwa JSON kutoka model zile zile, ita /v1/chat/completions au /v1/responses na key ile ile.

Ili kubaki kwenye /v1/messages, eleza kitu kama tool: weka schema yako kwenye input_schema na utaje tool kwenye tool_choice. input ya block ya tool_use kisha ni kitu chako, tayari kimechanganuliwa. tool_choice iliyotajwa inatumiwa na model za open-weight zinazopangishwa.

Mwili wa ombi

{
  "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"}
}

200 JSON

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_4b8d2f6a1c3e4a5b9d7f0e2c4a6b8d1f",
      "name": "record_person",
      "input": {"name": "John Doe", "age": 30, "occupation": "engineer"}
    }
  ]
}

Hakikisha stop_reason ni tool_use kabla ya kusoma block. Uitoaji wa kazi

Jinsi JSON inavyofika

JSON ni string. Jibu halina kitu kilichochanganuliwa kando yake: endesha JSON parser yako kwenye message.content.
Kwa stream: true JSON hufika kwa vipande vya delta.content. Viunganishe na uchanganue (parse) mara moja stream ikiisha; kipande peke yake si JSON halali.
Model ya open-weight inayopangishwa hujibu ombi la response_format bila maandishi ya reasoning: reasoning_content ni null.

Kagua unachopokea

Schema huongoza jinsi model inavyoandika. API haililinganishi jibu lililokamilika na schema yako, kwa hiyo code yako hufanya ukaguzi wa mwisho:

Changanua (parse) ndani ya error handler, kama mfano ulio juu unavyofanya.
Thibitisha kitu kilichochanganuliwa kwa schema ile ile kwenye code yako mwenyewe, kwa mfano kwa maktaba ya JSON Schema, Pydantic au Zod.
Jibu refu linaweza kuisha kabla JSON haijakamilika. Jibu lisilo la stream huripoti finish_reason kama stop au tool_calls pekee, kwa hiyo kosa la parse ndilo ishara. Omba tena, au omba kitu kidogo zaidi.

Makosa

Hali	Aina	Ujumbe	Lini
`400`	`invalid_request_error`	`<id> does not accept response_format`	Model haikubali hali yoyote kati ya hizo mbili.
`400`	`invalid_request_error`	`<id> does not accept response_format json_schema; use json_object`	Model inakubali `json_object` na ulituma `json_schema`.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type: …`	`response_format` haina `type`, au si kitu cha JSON.

Majibu mawili ya 400 hutumwa kabla ya kitu chochote kutolewa kwenye salio lako. Ushughulikiaji wa Makosa