Responses API

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

Väikseim päring on mudeli id ja tekst. Vastus ei ole voogedastatud, kui sa seda ei küsi.

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

Vastus on response-objekt. Selle output sisaldab arutlust, kui mudel arutles, ja sõnumit:

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

Päringu väljad

model ja input on see, mida päring vajab. Veerg Rakendavad nimetab mudelid, millel väli vastust muudab. Hostitud avatud kaaludega mudelid on mudelite loendi kaksteist id-d; Shannon 3 perekond on shannon-3, shannon-3-pro, shannon-3.1 ja shannon-3.1-pro. Mudelid ja hinnad

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user ja prompt_cache_key võetakse vastu, et olemasolev kliendikood töötaks muutmata kujul. Need ei muuda vastust. Kuna vestlust ei salvestata, kannab järgmine päring varasemaid vahetusi väljas input.

Sisendüksused

Sisendüksus on kas sõnum, mis koosneb väljadest role ja content, või tüübitud üksus, mis kannab tööriistakutset või selle tulemust. content on string või osade massiiv.

Pane juhised väljale instructions. Shannon 3 perekonna id puhul pane juhised, mis peavad kehtima, user-sõnumisse.

Vastuse output üksused võivad minna tagasi väljale input sellisena, nagu need on: message ja function_call üksusi loetakse, reasoning üksused jäetakse vahele.

Sisuosad

Shannoni tasemetel loetakse pilte ja faile input viimasest user üksusest. Suurustel ja piirangutel on oma leht. Pildid ja failid

Päring juhiste ja valikutega

See päring saadab juhised, vestluse sisendüksustena, väljundi piirangu, temperatuuri ja arutluse pingutuse. Kasutusel on hostitud avatud kaaludega mudel, mis rakendab neid kõiki.

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

Hostitud avatud kaaludega mudeli vastusel on id, object, model, created_at, status, output ja usage. Selle usage lisab vahemälust loetud tokenid ja arutlusele kulutatud tokenid:

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

Response-objekt

id, object, status, output ja usage on igal vastusel. Ehita oma kood nende peale.

Väljundüksused

OpenAI SDK-d ühendavad sõnumi teksti sinu eest väljas response.output_text.

Voogedastus

Määra stream väärtuseks true, et saada server-sent events. Igal kaadril on event:-rida sündmuse nimega ja data:-rida JSON-objektiga; objekt kordab nime väljas type. Seo deltad oma üksusega välja output_index järgi.

OpenAI SDK-ga loe sündmusi nende type järgi:

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

Sündmused saabuvad selles järjekorras. Arutluse, sõnumi ja tööriistakutsete rühmad ilmuvad ainult siis, kui vastusel need on.

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}, …}}

Voog, mis ebaõnnestub

Shannoni tasemetel lõpeb ebaõnnestunud vastus sündmusega response.failed sündmuse response.completed asemel. Selle response.status on failed ja response.error sisaldab code, rate_limit_exceeded või server_error, ning message.

Hostitud avatud kaaludega mudelitel on tõrge error-sündmus koos code api_error ja message. response.completed järgneb sellele siiski.

Käsitle voogu ebaõnnestununa, kui selles on response.failed või error sündmus, ja saada päring uuesti.

Tööriistad

Tööriist on funktsioon, mida sinu kood käivitab. Kirjelda see väljas tools; kui mudel seda soovib, sisaldab vastus function_call üksust sõnumi asemel või selle kõrval.

Tööriista definitsioon väljas tools:

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

Seda kutsuva vastuse output:

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

Käivita funktsioon ja saada päring uuesti, lisades kutse ja selle tulemuse väljale 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\"}"
  }
]

Loetakse ainult tüübi function tööriistu. Mudelitel shannon-1.6-*, shannon-2-* ja shannon-coder-1 vähendatakse parameters skeem tavalistele JSON Schema märksõnadele: oneOf loetakse kui anyOf ning märksõnu nagu $ref, additionalProperties, const, default ja title mudelile edasi ei anta.

tool_choice väärtusi required ja nimetatud funktsioon rakendavad hostitud avatud kaaludega mudelid.

Tööriistatsüklit kirjeldatakse täielikult selle oma lehel. Funktsioonikutse

Struktureeritud väljund

See formaat kirjutab struktureeritud väljundi kujul text.format. Skeem asub otse väljas format, välja name ja strict kõrval, mitte json_schema liikme all nagu Chat Completions'is.

• {"type": "json_object"} küsib mis tahes JSON-objekti.
• {"type": "json_schema", "name", "schema", "strict"} küsib JSON-i, mis järgib sinu skeemi. strict on true, kui jätad selle välja.

{
  "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 saabub tekstina sõnumi output_text osas; parsi see ise. Hostitud avatud kaaludega mudel ilma struktureeritud väljundita tagastab 400.

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

Milline mudel võtab millist vormi, on loetletud selle oma lehel. Struktureeritud väljundid

Arutlus

Arutlev mudel tagastab oma arutluse väljundüksusena tüübiga reasoning, enne sõnumit. Voos saabub see response.reasoning_summary_text.delta sündmustena.

Hostitud avatud kaaludega mudelid rakendavad reasoning.effort: off, low, medium või high, kus high on siis, kui sa midagi ei saada. off ei tagasta arutlusüksust. Saada see objektina; paljast stringi selles lõpp-punktis ei loeta.

Pingutuse tasemeid kirjeldatakse nende oma lehel. Reasoning-pingutus

Väljundi piirang

max_output_tokens on 4,096, kui sa seda ei saada. See on tokenite arv, mis päringu alguses sinu saldost kõrvale pannakse; kui vastus on valmis, asendatakse see summa päringu tegelikult kasutatuga. Väärtus, mis ei mahu sinu allesolevasse saldosse, annab 429 Quota exceeded.

See piirab vastuse pikkust mudelitel shannon-1.6-*, shannon-2-* ja shannon-coder-1 ning vastuse teksti pikkust hostitud avatud kaaludega mudelitel.

Selles lõpp-punktis arveldatakse shannon-coder-1 tokenites sinu saldost, nagu iga teine mudel.

Päringu sisu võib olla kuni 32 MiB. Piirangud ja saldo

Vead

Vead kasutavad OpenAI vea sisu: error-objekt väljadega type ja message; mõnel on ka code ja param väärtusega null. Tabel loetleb, mida see lõpp-punkt kõige sagedamini tagastab. Täielik loend koos sellega, mida korrata, on oma lehel. Vigade käsitlus