Responses API

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

Die kleinste versoek is 'n model-id en 'n teks. Die antwoord word nie gestroom nie tensy jy daarvoor vra.

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

Die antwoord is 'n antwoordobjek. Sy output hou die redenering, wanneer die model geredeneer het, en die boodskap:

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

Versoekvelde

model en input is wat 'n versoek nodig het. Die kolom Toegepas deur noem die modelle waarop 'n veld die antwoord verander. Die gehuisveste oopgewig-modelle is die twaalf id's van die modellys; die Shannon 3-familie is shannon-3, shannon-3-pro, shannon-3.1 en shannon-3.1-pro. Modelle en pryse

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user en prompt_cache_key word aanvaar sodat bestaande kliëntkode ongewysig loop. Hulle verander nie die antwoord nie. Omdat geen gesprek gestoor word nie, dra 'n opvolgversoek die vroeëre beurte in input.

Invoeritems

'n Invoeritem is óf 'n boodskap, met 'n role en 'n content, óf 'n getipeerde item wat 'n gereedskapoproep of sy resultaat dra. content is 'n string of 'n skikking dele.

Sit instruksies in die instructions-veld. Met 'n id van die Shannon 3-familie, sit instruksies wat moet geld in die user-boodskap.

Die items van 'n antwoord se output kan soos hulle is terug in input gaan: message- en function_call-items word gelees, reasoning-items word oorgeslaan.

Inhoudsdele

Op die Shannon-vlakke word beelde en lêers uit die laaste user-item van input gelees. Groottes en perke het hul eie bladsy. Beelde en lêers

'n Versoek met instruksies en opsies

Hierdie versoek stuur instruksies, 'n gesprek as invoeritems, 'n uitvoerperk, 'n temperatuur en 'n redeneerpoging. Dit gebruik 'n gehuisveste oopgewig-model, wat almal toepas.

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

Die antwoord van 'n gehuisveste oopgewig-model het id, object, model, created_at, status, output en usage. Sy usage voeg die tokens wat uit die kas gelees is en die tokens wat aan redenering bestee is by:

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

Die antwoordobjek

id, object, status, output en usage is op elke antwoord. Bou jou kode op daardie.

Uitvoeritems

Die OpenAI-SDK's voeg die teks van die boodskap vir jou saam in response.output_text.

Stroming

Stel stream op true vir bediener-gestuurde gebeure. Elke raam het 'n event:-reël met die naam van die gebeurtenis en 'n data:-reël met 'n JSON-objek; die objek herhaal die naam in type. Pas deltas by hul item volgens output_index.

Met die OpenAI-SDK, lees die gebeure volgens hul 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
  }'

Die gebeure kom in hierdie volgorde aan. Die groepe vir redenering, die boodskap en gereedskapoproepe verskyn net wanneer die antwoord hulle het.

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

'n Stroom wat misluk

Op die Shannon-vlakke eindig 'n mislukte antwoord met response.failed in die plek van response.completed. Sy response.status is failed en response.error hou 'n code, rate_limit_exceeded of server_error, en 'n message.

Op die gehuisveste oopgewig-modelle is 'n mislukking 'n error-gebeurtenis met code api_error en 'n message. response.completed volg steeds daarop.

Behandel 'n stroom as mislukt wanneer dit 'n response.failed- of 'n error-gebeurtenis hou, en stuur die versoek weer.

Gereedskap

'n Gereedskap is 'n funksie wat jou kode uitvoer. Beskryf dit in tools; wanneer die model dit wil hê, hou die antwoord 'n function_call-item in die plek van, of langs, die boodskap.

'n Gereedskapdefinisie in tools:

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

Die output van 'n antwoord wat dit oproep:

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

Voer die funksie uit, en stuur dan die versoek weer met die oproep en sy resultaat by input gevoeg:

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

Net gereedskap van tipe function word gelees. Op shannon-1.6-*, shannon-2-* en shannon-coder-1 word die parameters-skema tot die algemene JSON Schema-sleutelwoorde verminder: oneOf word as anyOf gelees, en sleutelwoorde soos $ref, additionalProperties, const, default en title word nie aan die model deurgegee nie.

tool_choice-waardes required en 'n benoemde funksie word deur die gehuisveste oopgewig-modelle toegepas.

Die gereedskaplus word volledig op sy eie bladsy beskryf. Funksie-oproepe

Gestruktureerde uitvoer

Hierdie formaat skryf gestruktureerde uitvoer as text.format. Die skema sit direk in format, langs name en strict, nie onder 'n json_schema-lid soos op Chat Completions nie.

• {"type": "json_object"} vra vir enige JSON-objek.
• {"type": "json_schema", "name", "schema", "strict"} vra vir JSON wat jou skema volg. strict is true wanneer jy dit uitlaat.

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

Die JSON kom as teks in die output_text-deel van die boodskap aan; ontleed dit self. 'n Gehuisveste oopgewig-model sonder gestruktureerde uitvoer gee 400 terug.

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

Watter model watter vorm neem, word op sy eie bladsy gelys. Gestruktureerde uitvoer

Redenering

'n Model wat redeneer, gee sy redenering terug as 'n uitvoeritem van tipe reasoning, voor die boodskap. In 'n stroom kom dit as response.reasoning_summary_text.delta-gebeure aan.

Die gehuisveste oopgewig-modelle pas reasoning.effort toe: off, low, medium of high, met high wanneer jy niks stuur nie. off gee geen redeneeritem terug nie. Stuur dit as 'n objek; 'n kaal string word nie op hierdie eindpunt gelees nie.

Die pogings word op hul eie bladsy beskryf. Redeneringspoging

Uitvoerperk

max_output_tokens is 4,096 wanneer jy dit nie stuur nie. Dit is die getal tokens wat van jou balans opsy gesit word wanneer die versoek begin; wanneer die antwoord volledig is, word daardie bedrag vervang deur wat die versoek gebruik het. 'n Waarde wat nie in jou oorblywende balans inpas nie, gee 429 Quota exceeded terug.

Dit beperk die lengte van die antwoord op shannon-1.6-*, shannon-2-* en shannon-coder-1, en die lengte van die antwoordteks op die gehuisveste oopgewig-modelle.

Op hierdie eindpunt word shannon-coder-1 in tokens van jou balans gehef, soos elke ander model.

'n Versoekliggaam kan tot 32 MiB wees. Perke en balans

Foute

Foute gebruik die OpenAI-foutliggaam: 'n error-objek met type en message; sommige dra ook code en param met die waarde null. Die tabel lys wat hierdie eindpunt die meeste teruggee. Die volledige lys, met wat om weer te probeer, het sy eie bladsy. Fouthantering