Responses API

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

Mažiausia užklausa yra modelio id ir tekstas. Atsakymas nėra srautinis, nebent to paprašote.

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

Atsakymas yra atsakymo objektas. Jo output talpina mąstymą, jei modelis mąstė, ir pranešimą:

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

Užklausos laukai

Užklausai reikia model ir input. Stulpelyje Taiko nurodyti modeliai, kuriuose laukas keičia atsakymą. Talpinami atvirų svorių modeliai yra dvylika modelių sąrašo id; Shannon 3 šeima yra shannon-3, shannon-3-pro, shannon-3.1 ir shannon-3.1-pro. Modeliai ir kainos

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user ir prompt_cache_key priimami, kad esamas kliento kodas veiktų nepakeistas. Jie atsakymo nekeičia. Kadangi pokalbis nesaugomas, tolesnė užklausa ankstesnius ėjimus perduoda input.

Įvesties elementai

Įvesties elementas yra arba pranešimas su role ir content, arba tipizuotas elementas, kuris talpina įrankio kreipinį ar jo rezultatą. content yra eilutė arba dalių masyvas.

Nurodymus dėkite į lauką instructions. Su Shannon 3 šeimos id nurodymus, kurie turi galioti, dėkite į user pranešimą.

Atsakymo output elementai gali grįžti į input tokie, kokie yra: message ir function_call elementai skaitomi, reasoning elementai praleidžiami.

Turinio dalys

Shannon pakopose vaizdai ir failai skaitomi iš paskutinio user elemento input. Dydžiai ir ribos turi savo puslapį. Vaizdai ir failai

Užklausa su nurodymais ir parinktimis

Ši užklausa siunčia nurodymus, pokalbį kaip įvesties elementus, išvesties ribą, temperatūrą ir mąstymo pastangas. Ji naudoja talpinamą atvirų svorių modelį, kuris taiko visus šiuos dalykus.

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

Talpinamo atvirų svorių modelio atsakyme yra id, object, model, created_at, status, output ir usage. Jo usage prideda iš kešo nuskaitytus tokenus ir mąstymui išleistus tokenus:

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

Atsakymo objektas

id, object, status, output ir usage yra kiekviename atsakyme. Savo kodą kurkite pagal juos.

Išvesties elementai

OpenAI SDK pranešimo tekstą už jus sujungia response.output_text.

Srautinis perdavimas

Nustatykite stream į true, kad gautumėte serverio siunčiamus įvykius. Kiekvienas kadras turi eilutę event: su įvykio pavadinimu ir eilutę data: su JSON objektu; objektas pavadinimą pakartoja type. Delta su jų elementu susiekite pagal output_index.

Su OpenAI SDK įvykius skaitykite pagal jų 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
  }'

Įvykiai ateina šia tvarka. Mąstymo, pranešimo ir įrankių kreipinių grupės atsiranda tik tada, kai atsakyme jų yra.

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

Srautas, kuris nepavyksta

Shannon pakopose nepavykęs atsakymas baigiasi response.failed vietoj response.completed. Jo response.status yra failed, o response.error talpina code, rate_limit_exceeded arba server_error, ir message.

Talpinamuose atvirų svorių modeliuose nesėkmė yra error įvykis su code api_error ir message. Po jo vis tiek eina response.completed.

Srautą laikykite nepavykusiu, kai jame yra response.failed arba error įvykis, ir siųskite užklausą dar kartą.

Įrankiai

Įrankis yra funkcija, kurią vykdo jūsų kodas. Apibūdinkite ją tools; kai modelis jos nori, atsakyme yra function_call elementas vietoj pranešimo arba šalia jo.

Įrankio apibrėžimas tools:

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

Atsakymo, kuriame jis kviečiamas, output:

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

Vykdykite funkciją, tada siųskite užklausą iš naujo, į input pridėję kreipinį ir jo rezultatą:

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

Skaitomi tik tipo function įrankiai. Su shannon-1.6-*, shannon-2-* ir shannon-coder-1 schema parameters sumažinama iki bendrų JSON Schema raktažodžių: oneOf skaitomas kaip anyOf, o tokie raktažodžiai kaip $ref, additionalProperties, const, default ir title modeliui neperduodami.

tool_choice reikšmes required ir įvardytą funkciją taiko talpinami atvirų svorių modeliai.

Įrankių ciklas pilnai aprašytas savo puslapyje. Funkcijų kvietimas

Struktūruota išvestis

Šis formatas struktūruotą išvestį užrašo kaip text.format. Schema yra tiesiai format, šalia name ir strict, o ne po nariu json_schema, kaip Chat Completions.

• {"type": "json_object"} prašo bet kokio JSON objekto.
• {"type": "json_schema", "name", "schema", "strict"} prašo JSON, atitinkančio jūsų schemą. strict yra true, kai jo nenurodote.

{
  "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 ateina kaip tekstas pranešimo daly output_text; išanalizuokite jį patys. Talpinamas atvirų svorių modelis be struktūruotos išvesties grąžina 400.

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

Kuris modelis kokią formą priima, išvardyta savo puslapyje. Struktūruoti išėjimai

Mąstymas

Modelis, kuris mąsto, grąžina mąstymą kaip tipo reasoning išvesties elementą prieš pranešimą. Sraute jis ateina kaip response.reasoning_summary_text.delta įvykiai.

Talpinami atvirų svorių modeliai taiko reasoning.effort: off, low, medium arba high, o jei nesiunčiate nieko – high. off mąstymo elemento negrąžina. Siųskite jį kaip objektą; paprasta eilutė šiame galiniame taške neskaitoma.

Pastangos aprašytos savo puslapyje. Mąstymo pastangos

Išvesties riba

max_output_tokens yra 4,096, kai jo nesiunčiate. Tai tokenų skaičius, atidedamas iš jūsų balanso užklausai prasidedant; kai atsakymas baigtas, ši suma pakeičiama tuo, ką užklausa panaudojo. Reikšmė, netelpanti į likusį balansą, grąžina 429 Quota exceeded.

Jis riboja atsakymo ilgį shannon-1.6-*, shannon-2-* ir shannon-coder-1, o talpinamuose atvirų svorių modeliuose – atsakymo teksto ilgį.

Šiame galiniame taške shannon-coder-1 apmokestinamas tokenais iš jūsų balanso, kaip ir kiekvienas kitas modelis.

Užklausos turinys gali siekti 32 MiB. Ribos ir balansas

Klaidos

Klaidos naudoja OpenAI klaidos turinį: objektas error su type ir message; kai kuriose taip pat yra code ir param su reikšme null. Lentelėje išvardyta tai, ką šis galinis taškas grąžina dažniausiai. Pilnas sąrašas, nurodant, ką kartoti, turi savo puslapį. Klaidų tvarkymas