Preskoči na sadržaj
Strukturirani izlazi

Strukturirani izlazi

Zatražite odgovor kao JSON: bilo koji JSON objekt ili JSON koji prati shemu koju pošaljete. Koristite to kada odgovor čita program, a ne osoba.

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)

JSON je tekst odgovora, u 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}
  }
}

Načini response_format

response_format je polje endpointa /v1/chat/completions. Bez njega je odgovor običan tekst.

Način Vrijednost Što dobivate
JSON objekt {"type": "json_object"} Odgovor je JSON bez propisanog oblika. U promptu recite koje ključeve želite.
JSON shema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Odgovor prati shemu koju pošaljete: njezine ključeve, tipove i obavezna polja.
Strict "strict": true Polje u json_schema, a ne treći način. To je true osim ako pošaljete false.
Polje Tip Zadano Opis Primjenjuju
type string json_object ili json_schema. Obavezno unutar response_format. text se prihvaća i daje običan tekstualni odgovor. Svaki model koji prima taj način
json_schema.schema object JSON Schema koju odgovor prati. Pošaljite je kad god je type json_schema. Svaki model koji prima taj način
json_schema.name string Oznaka sheme, kao u OpenAI formatu. Hostirani open-weight modeli
json_schema.strict boolean true Mora li odgovor točno slijediti shemu. Shannon modeli primjenjuju svaku shemu kao strict. Hostirani open-weight modeli

Način JSON objekta ne treba shemu. Ključeve navedite u promptu:

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

Podrška po modelu

Model json_object json_schema
Svaki Shannon model (shannon-*) Da Da
Hostirani open-weight modeli, osim onih navedenih niže Da Da
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Da —

GET /v1/models prijavljuje isto po id-u: capabilities.json_schema na svakom modelu i capabilities.response_format na hostiranim open-weight modelima. Modeli i cijene

Podržane ključne riječi sheme

Što model primi od vaše sheme ovisi o modelu i o endpointu:

Modeli /v1/chat/completions /v1/responses
Shannon modeli Podskup ključnih riječi u nastavku, primijenjen kao strict. Shema onako kako je pošaljete, primijenjena kao strict.
Hostirani open-weight modeli Shema onako kako je pošaljete. strict je true osim ako ga pošaljete. Shema onako kako je pošaljete. strict je true osim ako ga pošaljete.

Podskup ključnih riječi Shannon modela na /v1/chat/completions:

Ključna riječ Kako se čita
Ključne riječi koje se čitaju type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Razrješava se iz $defs ili definitions na vrhu sheme. Ključne riječi napisane uz $ref, poput description, zadržavaju se. Referenca bez odgovarajuće definicije čita se kao {"type": "object"}.
allOf Članovi se spajaju u jednu shemu. Kada dva člana postavljaju istu ključnu riječ, vrijedi kasniji.
oneOf Čita se kao anyOf.
Sheme koje upućuju na same sebe Proširuju se do 24 razine. Dublja razina čita se kao {"type": "object"}.
Izvan podskupa Svaka druga ključna riječ, na primjer additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not i if / then / else. One nisu dio sheme koju model prima.

Na /v1/responses: text.format

/v1/responses isti zahtjev zapisuje kao text.format. Shema stoji izravno u format, pokraj name i strict, a ne pod ključem json_schema. Za način JSON objekta pošaljite {"format": {"type": "json_object"}}.

Tijelo zahtjeva 
{
  "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 je text dijela output_text stavke 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": []
        }
      ]
    }
  ]
}

Podrška po modelu i greške iste su kao na /v1/chat/completions. Responses API

Na /v1/messages: alat kao shema

Format Messages nema polje za strukturirani izlaz. Za JSON s istih modela pozovite /v1/chat/completions ili /v1/responses s istim ključem.

Da ostanete na /v1/messages, opišite objekt kao alat: shemu stavite u input_schema i imenujte alat u tool_choice. input bloka tool_use tada je vaš objekt, već parsiran. Imenovani tool_choice primjenjuju hostirani open-weight modeli.

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

Provjerite je li stop_reason tool_use prije nego pročitate blok. Pozivanje funkcija

Kako JSON stiže

  • JSON je niz. Odgovor uz njega nema parsirani objekt: pokrenite svoj JSON parser nad message.content.
  • Uz stream: true JSON stiže u dijelovima delta.content. Spojite ih i parsirajte tek kada stream završi; pojedinačni dio nije valjani JSON.
  • Hostirani open-weight model odgovara na zahtjev s response_format bez teksta razmišljanja: reasoning_content je null.

Provjerite što primate

Shema vodi kako model piše. API ne uspoređuje gotov odgovor s vašom shemom, pa konačnu provjeru radi vaš kod:

  • Parsirajte unutar rukovatelja greškama, kao što to radi primjer na vrhu.
  • Validirajte parsirani objekt istom shemom u vlastitom kodu, na primjer s bibliotekom za JSON Schema, Pydanticom ili Zodom.
  • Dug odgovor može završiti prije nego JSON bude potpun. Odgovor bez streaminga prijavljuje finish_reason samo kao stop ili tool_calls, pa je signal greška parsiranja. Pitajte ponovno ili tražite manji objekt.

Greške

Status Tip Poruka Kada
400 invalid_request_error <id> does not accept response_format Model ne prima nijedan način.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Model prima json_object, a vi ste poslali json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format nema type ili nije JSON objekt.

Dva odgovora 400 šalju se prije nego se išta uzme s vašeg stanja. Upravljanje greškama