Structured outputs

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"]
        }
      }
    }
  }'

Ang JSON ay ang text ng sagot, sa 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}
  }
}

Ang mga mode ng response_format

Ang response_format ay isang field ng /v1/chat/completions. Kung wala ito, karaniwang text ang sagot.

Hindi kailangan ng schema ang JSON object mode. Pangalanan ang mga key sa 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"}
}

Suporta kada model

Iniuulat din ng GET /v1/models ang pareho kada id: capabilities.json_schema sa bawat model, at capabilities.response_format sa mga hosted open-weight model. Mga model at presyo

Mga sinusuportahang schema keyword

Ang natatanggap ng model mula sa iyong schema ay nakadepende sa model at sa endpoint:

Ang subset ng keyword ng mga Shannon model sa /v1/chat/completions:

Sa /v1/responses: text.format

Isinusulat ng /v1/responses ang parehong request bilang text.format. Ang schema ay direktang nasa format, katabi ng name at strict, hindi sa ilalim ng key na json_schema. Para sa JSON object mode, ipadala ang {"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"]
      }
    }
  }
}

Ang JSON ay ang text ng output_text part ng message item:

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

Pareho ng sa /v1/chat/completions ang suporta kada model at ang mga error. Responses API

Sa /v1/messages: tool bilang schema

Walang structured-output field ang Messages format. Para sa JSON mula sa parehong mga model, tawagin ang /v1/chat/completions o /v1/responses gamit ang parehong key.

Para manatili sa /v1/messages, ilarawan ang object bilang tool: ilagay ang iyong schema sa input_schema at pangalanan ang tool sa tool_choice. Ang input ng tool_use block ay ang iyong object na, naka-parse na. Ina-apply ng mga hosted open-weight model ang pinangalanang tool_choice.

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

Tiyaking tool_use ang stop_reason bago basahin ang block. Function calling

Paano dumarating ang JSON

• Ang JSON ay isang string. Walang naka-parse na object katabi ng reply: patakbuhin ang iyong JSON parser sa message.content.
• Gamit ang stream: true, dumarating ang JSON sa mga piraso ng delta.content. Pagdugtungin ang mga ito at i-parse nang minsan pagkatapos matapos ang stream; ang isang piraso nang mag-isa ay hindi valid na JSON.
• Sinasagot ng hosted open-weight model ang request na may response_format nang walang reasoning text: ang reasoning_content ay null.

Suriin ang natatanggap mo

Ginagabayan ng schema kung paano sumusulat ang model. Hindi inihahambing ng API ang natapos na sagot sa iyong schema, kaya ang iyong code ang gumagawa ng huling pagsusuri:

• Mag-parse sa loob ng error handler, tulad ng sample sa itaas.
• I-validate ang naka-parse na object gamit ang parehong schema sa sarili mong code, halimbawa gamit ang JSON Schema library, Pydantic o Zod.
• Ang mahabang sagot ay maaaring matapos bago kumpleto ang JSON. Ang reply na hindi naka-stream ay nag-uulat ng finish_reason na stop o tool_calls lamang, kaya ang parse error ang senyales. Magtanong muli, o humingi ng mas maliit na object.

Mga error

Ipinapadala ang dalawang reply na 400 bago kumuha ng anuman mula sa iyong balance. Paghawak ng Error