Responses API

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

La plej malgranda peto estas model-id kaj teksto. La respondo ne estas fluata, krom se vi petas tion.

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

La respondo estas objekto de respondo. Ĝia output enhavas la rezonadon, kiam la modelo rezonis, kaj la mesaĝon:

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

Kampoj de peto

model kaj input estas tio, kion peto bezonas. La kolumno Applied by nomas la modelojn, ĉe kiuj kampo ŝanĝas la respondon. La gastigitaj malfermpezaj modeloj estas la dek du id de la modellisto; la familio Shannon 3 estas shannon-3, shannon-3-pro, shannon-3.1 kaj shannon-3.1-pro. Modeloj kaj prezoj

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user kaj prompt_cache_key estas akceptataj, por ke ekzistanta klienta kodo funkciu senŝanĝe. Ili ne ŝanĝas la respondon. Ĉar neniu konversacio estas konservata, posta peto portas la pli fruajn vicojn en input.

Enigaj eroj

Enigan eron estas aŭ mesaĝo, kun role kaj content, aŭ tipita ero, kiu portas vokon de ilo aŭ ĝian rezulton. content estas ĉeno aŭ tabelo de partoj.

Metu instrukciojn en la kampon instructions. Kun id de la familio Shannon 3, metu instrukciojn, kiuj devas validi, en la mesaĝon user.

La eroj de output de respondo povas reiri en input kiel ili estas: eroj message kaj function_call estas legataj, eroj reasoning estas preterlasataj.

Partoj de enhavo

Ĉe la niveloj de Shannon bildoj kaj dosieroj estas legataj el la lasta ero user de input. Grandoj kaj limoj havas propran paĝon. Bildoj kaj dosieroj

Peto kun instrukcioj kaj opcioj

Ĉi tiu peto sendas instrukciojn, konversacion kiel enigajn erojn, eligan limon, temperaturon kaj raciuman penon. Ĝi uzas gastigitan malfermpezan modelon, kiu aplikas ĉiujn el ili.

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

La respondo de gastigita malfermpeza modelo havas id, object, model, created_at, status, output kaj usage. Ĝia usage aldonas la tokenojn legitajn el la kaŝmemoro kaj la tokenojn elspezitajn por rezonado:

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

La objekto de respondo

id, object, status, output kaj usage ĉeestas en ĉiu respondo. Bazu vian kodon sur ili.

Eligaj eroj

La SDK de OpenAI kunigas por vi la tekston de la mesaĝo en response.output_text.

Streaming

Agordu stream al true por server-sent events. Ĉiu kadro havas linion event: kun la nomo de la evento kaj linion data: kun JSON-objekto; la objekto ripetas la nomon en type. Kongruigu deltojn kun ilia ero per output_index.

Kun la SDK de OpenAI, legu la eventojn laŭ ilia 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
  }'

La eventoj alvenas en ĉi tiu ordo. La grupoj por rezonado, la mesaĝo kaj vokoj de iloj aperas nur kiam la respondo havas ilin.

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

Fluo, kiu malsukcesas

Ĉe la niveloj de Shannon malsukcesa respondo finiĝas per response.failed anstataŭ response.completed. Ĝia response.status estas failed kaj response.error enhavas code, rate_limit_exceeded aŭ server_error, kaj message.

Ĉe la gastigitaj malfermpezaj modeloj malsukceso estas evento error kun code api_error kaj message. response.completed tamen sekvas ĝin.

Traktu fluon kiel malsukcesan kiam ĝi enhavas eventon response.failed aŭ error, kaj resendu la peton.

Iloj

Ilo estas funkcio, kiun via kodo plenumas. Priskribu ĝin en tools; kiam la modelo volas ĝin, la respondo enhavas eron function_call anstataŭ la mesaĝo aŭ apud ĝi.

Difino de ilo en tools:

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

La output de respondo, kiu vokas ĝin:

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

Plenumu la funkcion, poste resendu la peton kun la voko kaj ĝia rezulto aldonitaj al 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\"}"
  }
]

Nur iloj de tipo function estas legataj. Ĉe shannon-1.6-*, shannon-2-* kaj shannon-coder-1 la skemo parameters estas reduktita al la komunaj ŝlosilvortoj de JSON Schema: oneOf estas legata kiel anyOf, kaj ŝlosilvortoj kiel $ref, additionalProperties, const, default kaj title ne estas transdonataj al la modelo.

La valoroj de tool_choice required kaj nomita funkcio estas aplikataj de la gastigitaj malfermpezaj modeloj.

La ciklo de iloj estas priskribita plene en sia propra paĝo. Funkci-alvokoj

Strukturita eligo

Ĉi tiu formato literumas strukturitan eligon kiel text.format. La skemo troviĝas rekte en format, apud name kaj strict, ne sub membro json_schema kiel ĉe Chat Completions.

• {"type": "json_object"} petas ajnan JSON-objekton.
• {"type": "json_schema", "name", "schema", "strict"} petas JSON, kiu sekvas vian skemon. strict estas true kiam vi lasas ĝin ekster.

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

La JSON alvenas kiel teksto en la parto output_text de la mesaĝo; analizu ĝin mem. Gastigita malfermpeza modelo sen strukturita eligo redonas 400.

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

Kiu modelo akceptas kiun formon, estas listigita en sia propra paĝo. Strukturitaj eligoj

Rezonado

Modelo, kiu rezonas, redonas sian rezonadon kiel eligan eron de tipo reasoning, antaŭ la mesaĝo. En fluo ĝi alvenas kiel eventoj response.reasoning_summary_text.delta.

La gastigitaj malfermpezaj modeloj aplikas reasoning.effort: off, low, medium aŭ high, kun high kiam vi sendas nenion. off redonas neniun eron de rezonado. Sendu ĝin kiel objekton; nuda ĉeno ne estas legata ĉe ĉi tiu endpoint.

La penoj estas priskribitaj en sia propra paĝo. Peno de reasoning

Eliga limo

max_output_tokens estas 4,096 kiam vi ne sendas ĝin. Ĝi estas la nombro da tokenoj rezervitaj el via saldo kiam la peto komenciĝas; kiam la respondo estas kompleta, tiu kvanto estas anstataŭata per tio, kion la peto uzis. Valoro, kiu ne eniras en vian restantan saldon, redonas 429 Quota exceeded.

Ĝi limigas la longecon de la respondo ĉe shannon-1.6-*, shannon-2-* kaj shannon-coder-1, kaj la longecon de la teksto de la respondo ĉe la gastigitaj malfermpezaj modeloj.

Ĉe ĉi tiu endpoint shannon-coder-1 estas kalkulata en tokenoj el via saldo, kiel ĉiu alia modelo.

Korpo de peto povas esti ĝis 32 MiB. Limoj kaj saldo

Eraroj

Eraroj uzas la erarkorpon de OpenAI: objekton error kun type kaj message; kelkaj portas ankaŭ code kaj param kun la valoro null. La tabelo listigas kion ĉi tiu endpoint plej ofte redonas. La plena listo, kun tio, kion reprovi, havas propran paĝon. Erarotraktado