API Responses

POST https://api.shannon-ai.com/v1/responses

Najmanjši zahtevek je id modela in besedilo. Odgovor ni pretakan, razen če to zahtevate.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.responses.create(
    model="shannon-3",
    input="Say hello in one sentence.",
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.shannon-ai.com/v1",
});

const response = await client.responses.create({
  model: "shannon-3",
  input: "Say hello in one sentence.",
});

console.log(response.output_text);

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "input": "Say hello in one sentence."
  }'

Odgovor je objekt odgovora. Njegov output vsebuje razmišljanje, kadar je model razmišljal, in sporočilo:

{
  "id": "resp_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "response",
  "created_at": 1791625200,
  "model": "shannon-3",
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "parallel_tool_calls": true,
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "output": [
    {
      "id": "rs_8a2e6c1f4b7d4e03b9c5a1d70f3e2b64",
      "type": "reasoning",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user wants a greeting in one sentence. Keep it short and friendly."
        }
      ]
    },
    {
      "id": "msg_1c7b9e3a5d2f4a86b0e4c8d19a6f7e25",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello, it is good to meet you.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46,
    "total_tokens": 1230
  }
}

Polja zahtevka

Zahtevek potrebuje model in input. Stolpec Upoštevajo navaja modele, pri katerih polje spremeni odgovor. Gostovani modeli z odprtimi utežmi so dvanajst id s seznama modelov; družina Shannon 3 so shannon-3, shannon-3-pro, shannon-3.1 in shannon-3.1-pro. Modeli in cene

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user in prompt_cache_key so sprejeti, da obstoječa odjemalska koda deluje nespremenjena. Odgovora ne spreminjajo. Ker se noben pogovor ne shranjuje, nadaljevalni zahtevek v input nosi prejšnje obrate.

Elementi vhoda

Element vhoda je sporočilo, z role in content, ali tipiziran element, ki nosi klic orodja ali njegov rezultat. content je niz ali polje delov.

Navodila vstavite v polje instructions. Pri id družine Shannon 3 navodila, ki morajo veljati, vstavite v sporočilo user.

Elemente output odgovora lahko vrnete v input take, kot so: elementi message in function_call se preberejo, elementi reasoning se preskočijo.

Deli vsebine

Pri stopnjah Shannon se slike in datoteke berejo iz zadnjega elementa user v input. Velikosti in omejitve imajo svojo stran. Slike in datoteke

Zahtevek z navodili in možnostmi

Ta zahtevek pošilja navodila, pogovor kot elemente vhoda, omejitev izhoda, temperaturo in napor razmišljanja. Uporablja gostovani model z odprtimi utežmi, ki upošteva vse to.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.responses.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    instructions="You are a physics teacher. Answer in two sentences.",
    input=[
        {"role": "user", "content": "Why is the sky blue?"},
        {"role": "assistant", "content": "Air scatters blue light more than red light."},
        {"role": "user", "content": "And why are sunsets red?"},
    ],
    max_output_tokens=512,
    temperature=0.3,
    reasoning={"effort": "low"},
)

for item in response.output:
    if item.type == "reasoning":
        print("reasoning:", item.summary[0].text)
    elif item.type == "message":
        print("answer:", item.content[0].text)
print(response.usage)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.shannon-ai.com/v1",
});

const response = await client.responses.create({
  model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  instructions: "You are a physics teacher. Answer in two sentences.",
  input: [
    { role: "user", content: "Why is the sky blue?" },
    { role: "assistant", content: "Air scatters blue light more than red light." },
    { role: "user", content: "And why are sunsets red?" },
  ],
  max_output_tokens: 512,
  temperature: 0.3,
  reasoning: { effort: "low" },
});

for (const item of response.output) {
  if (item.type === "reasoning") console.log("reasoning:", item.summary[0].text);
  if (item.type === "message") console.log("answer:", item.content[0].text);
}
console.log(response.usage);

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "instructions": "You are a physics teacher. Answer in two sentences.",
    "input": [
      {"role": "user", "content": "Why is the sky blue?"},
      {"role": "assistant", "content": "Air scatters blue light more than red light."},
      {"role": "user", "content": "And why are sunsets red?"}
    ],
    "max_output_tokens": 512,
    "temperature": 0.3,
    "reasoning": {"effort": "low"}
  }'

Odgovor gostovanega modela z odprtimi utežmi ima id, object, model, created_at, status, output in usage. Njegov usage doda tokene, prebrane iz predpomnilnika, in tokene, porabljene za razmišljanje:

{
  "usage": {
    "input_tokens": 58,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 67,
    "output_tokens_details": {
      "reasoning_tokens": 19
    },
    "total_tokens": 125
  }
}

Objekt odgovora

id, object, status, output in usage so v vsakem odgovoru. Svojo kodo gradite na njih.

Elementi izhoda

SDK-ji OpenAI besedilo sporočila združijo namesto vas v response.output_text.

Pretakanje

Za dogodke, ki jih pošilja strežnik (server-sent events), nastavite stream na true. Vsak okvir ima vrstico event: z imenom dogodka in vrstico data: z objektom JSON; objekt ponovi ime v type. Delte povežite z njihovim elementom prek output_index.

Z SDK-jem OpenAI dogodke preberite po njihovem type:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

stream = client.responses.create(
    model="shannon-3",
    input="Explain server-sent events in three sentences.",
    stream=True,
)

for event in stream:
    kind = getattr(event, "type", "error")     # an event without a type is an error event
    if kind == "response.reasoning_summary_text.delta":
        pass                                   # a piece of reasoning: event.delta
    elif kind == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif kind == "response.output_item.done" and event.item.type == "function_call":
        print("\ntool call:", event.item.name, event.item.arguments)
    elif kind == "response.completed":
        print("\n", event.response.usage)
    elif kind in ("response.failed", "error"):
        raise RuntimeError("the stream failed, send the request again")

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.shannon-ai.com/v1",
});

const stream = await client.responses.create({
  model: "shannon-3",
  input: "Explain server-sent events in three sentences.",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.reasoning_summary_text.delta") {
    // a piece of reasoning: event.delta
  } else if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  } else if (event.type === "response.output_item.done" && event.item.type === "function_call") {
    console.log("\ntool call:", event.item.name, event.item.arguments);
  } else if (event.type === "response.completed") {
    console.log("\n", event.response.usage);
  } else if (event.type === "response.failed" || event.type === "error") {
    throw new Error("the stream failed, send the request again");
  }
}

curl -N https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "input": "Explain server-sent events in three sentences.",
    "stream": true
  }'

Dogodki prispejo v tem vrstnem redu. Skupine za razmišljanje, sporočilo in klice orodij se pojavijo samo, kadar jih odgovor ima.

event: response.created
data: {"type":"response.created","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"in_progress","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Server-sent"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":" events let a server push text over one HTTP reply."}

event: response.output_text.done
data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Server-sent events let a server push text over one HTTP reply."}

event: response.content_part.done
data: {"type":"response.content_part.done","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply."}}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_5f0c…","object":"response","status":"completed","output":[…],"usage":{"input_tokens":1190,"output_tokens":18,"total_tokens":1208}, …}}

Tok, ki odpove

Pri stopnjah Shannon se neuspel odgovor konča z response.failed namesto z response.completed. Njegov response.status je failed, response.error pa vsebuje code, rate_limit_exceeded ali server_error, in message.

Pri gostovanih modelih z odprtimi utežmi je napaka dogodek error s code api_error in message. Za njim še vedno sledi response.completed.

Tok obravnavajte kot neuspel, kadar vsebuje dogodek response.failed ali error, in zahtevek pošljite znova.

Orodja

Orodje je funkcija, ki jo zažene vaša koda. Opišite ga v tools; kadar ga model želi, odgovor namesto sporočila ali ob njem vsebuje element function_call.

Definicija orodja v tools:

[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

output odgovora, ki ga kliče:

[
  {
    "id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "arguments": "{\"city\":\"Paris\"}"
  }
]

Zaženite funkcijo, nato zahtevek pošljite znova, z dodanim klicem in njegovim rezultatom v input:

[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "type": "function_call",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "arguments": "{\"city\":\"Paris\"}"
  },
  {
    "type": "function_call_output",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "output": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
  }
]

Berejo se samo orodja tipa function. Pri shannon-1.6-*, shannon-2-* in shannon-coder-1 je shema parameters zožena na skupne ključne besede JSON Schema: oneOf se bere kot anyOf, ključne besede, kot so $ref, additionalProperties, const, default in title, pa se modelu ne posredujejo.

Vrednosti tool_choice required in poimenovana funkcija upoštevajo gostovani modeli z odprtimi utežmi.

Zanka orodij je v celoti opisana na svoji strani. Klicanje funkcij

Strukturiran izhod

Ta format strukturiran izhod zapiše kot text.format. Shema je neposredno v format, ob name in strict, ne pod članom json_schema kot pri Chat Completions.

• {"type": "json_object"} zahteva poljuben objekt JSON.
• {"type": "json_schema", "name", "schema", "strict"} zahteva JSON, ki sledi vaši shemi. strict je true, kadar ga izpustite.

{
  "model": "shannon-1.6-lite",
  "input": "Extract the city and the date: 'The conference opens in Lisbon on 12 May 2027.'",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "event",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "ISO 8601 date"
          }
        },
        "required": [
          "city",
          "date"
        ]
      }
    }
  }
}

JSON prispe kot besedilo v delu output_text sporočila; razčlenite ga sami. Gostovani model z odprtimi utežmi brez strukturiranega izhoda vrne 400.

{"city": "Lisbon", "date": "2027-05-12"}

Kateri model sprejema katero obliko, je navedeno na svoji strani. Strukturirani izhodi

Razmišljanje

Model, ki razmišlja, vrne svoje razmišljanje kot element izhoda tipa reasoning, pred sporočilom. V toku prispe kot dogodki response.reasoning_summary_text.delta.

Gostovani modeli z odprtimi utežmi upoštevajo reasoning.effort: off, low, medium ali high, pri čemer velja high, kadar ne pošljete ničesar. off ne vrne elementa razmišljanja. Pošljite ga kot objekt; goli niz na tej končni točki ni prebran.

Napori so opisani na svoji strani. Napor razmišljanja

Omejitev izhoda

max_output_tokens je 4,096, kadar ga ne pošljete. To je število tokenov, odloženih z vašega stanja, ko se zahtevek začne; ko je odgovor popoln, se ta znesek nadomesti s tem, kar je zahtevek porabil. Vrednost, ki se ne prilega v vaše preostalo stanje, vrne 429 Quota exceeded.

Omejuje dolžino odgovora pri shannon-1.6-*, shannon-2-* in shannon-coder-1 ter dolžino besedila odgovora pri gostovanih modelih z odprtimi utežmi.

Na tej končni točki se shannon-coder-1 obračuna v tokenih z vašega stanja, kot vsak drug model.

Telo zahtevka je lahko veliko do 32 MiB. Omejitve in stanje

Napake

Napake uporabljajo telo napake OpenAI: objekt error s type in message; nekatere nosijo tudi code in param z vrednostjo null. Tabela navaja, kar ta končna točka vrača najpogosteje. Celoten seznam, s tem, kaj ponoviti, ima svojo stran. Obravnava napak