Responses-API

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

Déi klengst Ufro ass eng Modell-ID an en Text. D'Äntwert gëtt net gestreamt, ausser Dir freet dorëms.

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

D'Äntwert ass e Response-Objet. Säin output enthält d'Reasoning, wann de Modell reasonéiert huet, an d'Message:

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

Request-Felder

model an input brauch eng Ufro. D'Kolonn Ugewannt vun nennt d'Modeller, bei deenen e Feld d'Äntwert ännert. D'Hosted Open-Weight-Modeller sinn déi zwielef IDen aus der Modellëscht; d'Shannon-3-Famill ass shannon-3, shannon-3-pro, shannon-3.1 an shannon-3.1-pro. Modeller a Präisser

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user an prompt_cache_key ginn akzeptéiert, sou datt bestoenden Client-Code onverännert leeft. Si änneren d'Äntwert net. Well keng Konversatioun gespäichert gëtt, enthält eng Folleg-Ufro déi fréiere Tourë an input.

Input-Items

En Input-Item ass entweder eng Message, mat engem role an engem content, oder en typiséiert Item, dat en Tool-Ruff oder säi Resultat enthält. content ass e String oder en Array vun Deeler.

Setzt Instruktiounen an d'Feld instructions. Bei enger ID aus der Shannon-3-Famill setzt Instruktiounen, déi gëllen mussen, an d'user-Message.

D'Items aus output vun enger Äntwert kënnen esou, wéi se sinn, zréck an input: message- a function_call-Items ginn gelies, reasoning-Items ginn iwwersprong.

Inhaltsdeeler

Bei de Shannon-Stufe ginn Biller a Fichieren aus dem leschten user-Item vun input gelies. Gréissten a Limite hunn eng eege Säit. Biller a Fichieren

Eng Ufro mat Instruktiounen an Optiounen

Dës Ufro schéckt Instruktiounen, eng Konversatioun als Input-Items, eng Output-Limit, eng Temperatur an en Reasoning-Effort. Si benotzt en Hosted Open-Weight-Modell, dat all dës benotzt.

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

D'Äntwert vun engem Hosted Open-Weight-Modell huet id, object, model, created_at, status, output an usage. Säin usage füügt d'Tokens, déi aus dem Cache gelies goufen, an d'Tokens, déi fir Reasoning ausginn goufen, derbäi:

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

D'Response-Objet

id, object, status, output an usage sinn an all Äntwert. Baut Äre Code op dës op.

Output-Items

D'OpenAI-SDKs setzen den Text vun der Message fir Iech an response.output_text zesummen.

Streaming

Setzt stream op true fir Server-sent Events. All Frame huet eng event:-Zeil mam Numm vum Event an eng data:-Zeil mat engem JSON-Objet; d'Objet widderhëlt den Numm an type. Ordnet d'Deltaen hirem Item no output_index zou.

Liest d'Events mam OpenAI-SDK no hirem 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
  }'

D'Events kommen an dëser Reiefolleg un. D'Gruppe fir Reasoning, d'Message an d'Tool-Ruffer erscheinen nëmmen, wann d'Äntwert se huet.

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

E Stream, dee feelschléit

Bei de Shannon-Stufe hält eng gescheitert Äntwert mat response.failed amplaz vun response.completed op. Hire response.status ass failed an response.error enthält e code, rate_limit_exceeded oder server_error, an eng message.

Bei den Hosted Open-Weight-Modeller ass e Feeler en error-Event mat code api_error an enger message. response.completed follegt trotzdem dernoer.

Behandelt e Stream als gescheitert, wann en e response.failed- oder en error-Event enthält, a schéckt d'Ufro nach eng Kéier.

Tools

E Tool ass eng Funktioun, déi Äre Code ausféiert. Beschreift se an tools; wann de Modell se wëll, enthält d'Äntwert e function_call-Item amplaz vun, oder niewent, der Message.

Eng Tool-Definitioun an tools:

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

Den output vun enger Äntwert, déi se rifft:

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

Féiert d'Funktioun aus, schéckt dann d'Ufro nach eng Kéier, mam Ruff a sengem Resultat an input derbäigesat:

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

Nëmmen Tools vum Typ function ginn gelies. Bei shannon-1.6-*, shannon-2-* a shannon-coder-1 gëtt d'parameters-Schema op déi gemeinsam JSON-Schema-Schlësselwierder reduzéiert: oneOf gëtt als anyOf gelies, a Schlësselwierder wéi $ref, additionalProperties, const, default an title ginn net un de Modell weiderginn.

D'tool_choice-Wäerter required an eng genannt Funktioun ginn vun den Hosted Open-Weight-Modeller ugewannt.

D'Tool-Loop ass op hirer eegener Säit am Ganze beschriwwen. Funktiounsofruff

Strukturéierten Output

Dëst Format schreift strukturéierten Output als text.format. D'Schema steet direkt an format, niewent name an strict, net ënner engem json_schema-Member wéi bei Chat Completions.

• {"type": "json_object"} freet e JSON-Objet vun enger Form no Wal un.
• {"type": "json_schema", "name", "schema", "strict"} freet JSON no Ärem Schema un. strict ass true, wann Dir et ewech léisst.

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

D'JSON kënnt als Text am output_text-Deel vun der Message; parst et selwer. En Hosted Open-Weight-Modell ouni strukturéierten Output gëtt 400 zréck.

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

Wéi e Modell wéi eng Form hëlt, steet op senger eegener Säit. Strukturéiert Output

Reasoning

E Modell, dee reasonéiert, gëtt seng Reasoning als Output-Item vum Typ reasoning zréck, virun der Message. An engem Stream kënnt se als response.reasoning_summary_text.delta-Events.

D'Hosted Open-Weight-Modeller wenden reasoning.effort un: off, low, medium oder high, mat high, wann Dir näischt schéckt. off gëtt kee Reasoning-Item zréck. Schéckt et als Objet; e bloussen String gëtt op dësem Endpoint net gelies.

D'Efforten si op hirer eegener Säit beschriwwen. Reasoning-Effort

Output-Längt

max_output_tokens ass 4,096, wann Dir et net schéckt. Et ass d'Zuel vun Tokens, déi aus Ärem Solde apaart geluecht ginn, wann d'Ufro ufänkt; wann d'Äntwert komplett ass, gëtt dee Betrag duerch dat ersat, wat d'Ufro benotzt huet. E Wäert, deen net an Ären iwwerbleiwende Solde passt, gëtt 429 Quota exceeded zréck.

Et begrenzt d'Längt vun der Äntwert bei shannon-1.6-*, shannon-2-* a shannon-coder-1, an d'Längt vum Äntwert-Text bei den Hosted Open-Weight-Modeller.

Op dësem Endpoint gëtt shannon-coder-1 a Tokens aus Ärem Solde berechent, wéi all aner Modell.

E Body vun enger Ufro däerf bis zu 32 MiB grouss sinn. Limiten a Solde

Feeler

Feeler benotzen de OpenAI-Feeler-Body: en error-Objet mat type a message; e puer enthalen och code a param mam Wäert null. D'Tabell lëscht op, wat dësen Endpoint am meeschten zréckgëtt. Déi komplett Lëscht, mat deem, wat nach eng Kéier probéiert gëtt, huet eng eege Säit. Feelerbehandlung