Responses API

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

De kleinste aanvraag is een model-id en een tekst. Het antwoord komt niet met streaming tenzij je erom vraagt.

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

Het antwoord is een response-object. Zijn output bevat de redenering, als het model heeft geredeneerd, en het bericht:

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

Requestvelden

model en input heeft een aanvraag nodig. De kolom Toegepast door noemt de modellen waarop een veld het antwoord verandert. De gehoste open-weight modellen zijn de twaalf id's van de modellijst; de Shannon 3-familie is shannon-3, shannon-3-pro, shannon-3.1 en shannon-3.1-pro. Modellen en prijzen

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user en prompt_cache_key worden geaccepteerd zodat bestaande clientcode ongewijzigd draait. Ze veranderen het antwoord niet. Omdat er geen gesprek wordt opgeslagen, bevat een vervolgaanvraag de eerdere beurten in input.

Inputitems

Een inputitem is ofwel een bericht, met een role en een content, ofwel een getypeerd item dat een toolaanroep of het resultaat ervan bevat. content is een string of een array van delen.

Zet instructies in het veld instructions. Zet bij een id van de Shannon 3-familie instructies die moeten gelden in het user-bericht.

De items van de output van een antwoord kunnen ongewijzigd terug in input: message- en function_call-items worden gelezen, reasoning-items worden overgeslagen.

Contentdelen

Bij de Shannon-niveaus worden afbeeldingen en bestanden gelezen uit het laatste user-item van input. Groottes en limieten hebben een eigen pagina. Afbeeldingen en bestanden

Een aanvraag met instructies en opties

Deze aanvraag stuurt instructies, een gesprek als inputitems, een outputlimiet, een temperatuur en een redeneer-effort mee. Ze gebruikt een gehost open-weight model, dat ze allemaal toepast.

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

Het antwoord van een gehost open-weight model heeft id, object, model, created_at, status, output en usage. Zijn usage voegt de tokens toe die uit de cache zijn gelezen en de tokens die aan redeneren zijn besteed:

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

Het response-object

id, object, status, output en usage staan in elk antwoord. Bouw je code daarop.

Outputitems

De OpenAI-SDK's voegen de tekst van het bericht voor je samen in response.output_text.

Streaming

Zet stream op true voor server-sent events. Elk frame heeft een event:-regel met de naam van het event en een data:-regel met een JSON-object; het object herhaalt de naam in type. Koppel deltas aan hun item via output_index.

Lees de events met de OpenAI-SDK op hun 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
  }'

De events komen in deze volgorde binnen. De groepen voor redenering, het bericht en toolaanroepen verschijnen alleen als het antwoord ze heeft.

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

Een stream die mislukt

Bij de Shannon-niveaus eindigt een mislukt antwoord met response.failed in plaats van response.completed. Zijn response.status is failed en response.error bevat een code, rate_limit_exceeded of server_error, en een message.

Bij de gehoste open-weight modellen is een fout een error-event met code api_error en een message. Daarna volgt nog steeds response.completed.

Behandel een stream als mislukt als hij een response.failed- of een error-event bevat, en verstuur de aanvraag opnieuw.

Tools

Een tool is een functie die je code uitvoert. Beschrijf hem in tools; als het model hem wil, bevat het antwoord een function_call-item in plaats van, of naast, het bericht.

Een tooldefinitie in tools:

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

De output van een antwoord dat hem aanroept:

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

Voer de functie uit en verstuur de aanvraag daarna opnieuw, met de aanroep en het resultaat toegevoegd aan 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\"}"
  }
]

Alleen tools van het type function worden gelezen. Bij shannon-1.6-*, shannon-2-* en shannon-coder-1 wordt het schema van parameters teruggebracht tot de gangbare JSON Schema-trefwoorden: oneOf wordt gelezen als anyOf, en trefwoorden zoals $ref, additionalProperties, const, default en title worden niet aan het model doorgegeven.

De tool_choice-waarden required en een benoemde functie worden toegepast door de gehoste open-weight modellen.

De toollus wordt volledig beschreven op een eigen pagina. Function calling

Gestructureerde output

Dit formaat schrijft gestructureerde output als text.format. Het schema staat direct in format, naast name en strict, niet onder een json_schema-lid zoals bij Chat Completions.

• {"type": "json_object"} vraagt om een willekeurig JSON-object.
• {"type": "json_schema", "name", "schema", "strict"} vraagt om JSON die je schema volgt. strict is true als je het weglaat.

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

De JSON komt als tekst binnen in het output_text-deel van het bericht; parse hem zelf. Een gehost open-weight model zonder gestructureerde output geeft 400.

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

Welk model welke vorm accepteert, staat op een eigen pagina. Gestructureerde outputs

Redenering

Een model dat redeneert, geeft zijn redenering terug als outputitem van het type reasoning, vóór het bericht. In een stream komt het binnen als response.reasoning_summary_text.delta-events.

De gehoste open-weight modellen passen reasoning.effort toe: off, low, medium of high, met high als je niets stuurt. off geeft geen reasoning-item terug. Stuur het als object; een kale string wordt op dit endpoint niet gelezen.

De efforts worden op hun eigen pagina beschreven. Reasoning effort

Outputlimiet

max_output_tokens is 4,096 als je het niet meestuurt. Het is het aantal tokens dat van je saldo apart wordt gezet als de aanvraag begint; als het antwoord compleet is, wordt dat bedrag vervangen door wat de aanvraag heeft gebruikt. Een waarde die niet in je resterende saldo past, geeft 429 Quota exceeded.

Het begrenst de lengte van het antwoord bij shannon-1.6-*, shannon-2-* en shannon-coder-1, en de lengte van de antwoordtekst bij de gehoste open-weight modellen.

Op dit endpoint wordt shannon-coder-1 in tokens van je saldo in rekening gebracht, zoals elk ander model.

Een aanvraagbody mag maximaal 32 MiB zijn. Limieten en saldo

Fouten

Fouten gebruiken de OpenAI-foutbody: een error-object met type en message; sommige bevatten ook code en param met de waarde null. De tabel noemt wat dit endpoint het vaakst teruggeeft. De volledige lijst, met wat je opnieuw kunt proberen, heeft een eigen pagina. Foutafhandeling