Responses API

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

Die kleinste Anfrage besteht aus einer Modell-ID und einem Text. Die Antwort wird nicht gestreamt, es sei denn, Sie fordern es an.

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 Antwort ist ein Response-Objekt. Sein output enthält das Reasoning, wenn das Modell nachgedacht hat, und die Nachricht:

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

Anfragefelder

model und input braucht eine Anfrage. Die Spalte Angewendet von nennt die Modelle, bei denen ein Feld die Antwort verändert. Die gehosteten Open-Weight-Modelle sind die zwölf IDs der Modellliste; die Shannon-3-Familie besteht aus shannon-3, shannon-3-pro, shannon-3.1 und shannon-3.1-pro. Modelle & Preise

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user und prompt_cache_key werden akzeptiert, damit vorhandener Client-Code unverändert läuft. Sie verändern die Antwort nicht. Da keine Konversation gespeichert wird, trägt eine Folgeanfrage die früheren Turns in input.

Input-Elemente

Ein Input-Element ist entweder eine Nachricht, mit einer role und einem content, oder ein typisiertes Element, das einen Tool-Aufruf oder sein Ergebnis trägt. content ist ein String oder ein Array von Teilen.

Legen Sie Anweisungen in das Feld instructions. Bei einer ID der Shannon-3-Familie gehören Anweisungen, die gelten müssen, in die user-Nachricht.

Die Elemente von output einer Antwort können unverändert in input zurückgehen: message- und function_call-Elemente werden gelesen, reasoning-Elemente übersprungen.

Content-Teile

Bei den Shannon-Stufen werden Bilder und Dateien aus dem letzten user-Element von input gelesen. Größen und Limits haben eine eigene Seite. Bilder und Dateien

Eine Anfrage mit Anweisungen und Optionen

Diese Anfrage sendet Anweisungen, eine Konversation als Input-Elemente, ein Output-Limit, eine Temperatur und einen Reasoning-Aufwand. Sie verwendet ein gehostetes Open-Weight-Modell, das alle davon anwendet.

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 Antwort eines gehosteten Open-Weight-Modells hat id, object, model, created_at, status, output und usage. Ihre usage ergänzt die aus dem Cache gelesenen Tokens und die für Reasoning aufgewendeten Tokens:

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

Das Response-Objekt

id, object, status, output und usage sind in jeder Antwort enthalten. Bauen Sie Ihren Code darauf auf.

Output-Elemente

Die OpenAI-SDKs fügen den Text der Nachricht für Sie in response.output_text zusammen.

Streaming

Setzen Sie stream auf true, um Server-Sent Events zu erhalten. Jeder Frame hat eine event:-Zeile mit dem Namen des Events und eine data:-Zeile mit einem JSON-Objekt; das Objekt wiederholt den Namen in type. Ordnen Sie Deltas ihrem Element über output_index zu.

Lesen Sie die Events mit dem OpenAI-SDK nach ihrem 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 Events treffen in dieser Reihenfolge ein. Die Gruppen für Reasoning, die Nachricht und Tool-Aufrufe erscheinen nur, wenn die Antwort sie enthält.

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

Ein Stream, der fehlschlägt

Bei den Shannon-Stufen endet eine fehlgeschlagene Antwort mit response.failed anstelle von response.completed. Ihr response.status ist failed, und response.error enthält einen code, rate_limit_exceeded oder server_error, und eine message.

Bei den gehosteten Open-Weight-Modellen ist ein Fehler ein error-Event mit code api_error und einer message. response.completed folgt trotzdem darauf.

Behandeln Sie einen Stream als fehlgeschlagen, wenn er ein Event response.failed oder error enthält, und senden Sie die Anfrage erneut.

Tools

Ein Tool ist eine Funktion, die Ihr Code ausführt. Beschreiben Sie es in tools; wenn das Modell es braucht, enthält die Antwort ein Element function_call anstelle der Nachricht oder neben ihr.

Eine Tool-Definition in tools:

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

Der output einer Antwort, die es aufruft:

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

Führen Sie die Funktion aus und senden Sie die Anfrage dann erneut, wobei der Aufruf und sein Ergebnis zu input hinzugefügt werden:

[
  {
    "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 Tools vom Typ function werden gelesen. Bei shannon-1.6-*, shannon-2-* und shannon-coder-1 wird das Schema parameters auf die gängigen JSON-Schema-Schlüsselwörter reduziert: oneOf wird als anyOf gelesen, und Schlüsselwörter wie $ref, additionalProperties, const, default und title werden nicht an das Modell weitergegeben.

Die tool_choice-Werte required und eine benannte Funktion werden von den gehosteten Open-Weight-Modellen angewendet.

Die Tool-Schleife ist auf einer eigenen Seite vollständig beschrieben. Funktionsaufrufe

Strukturierte Ausgabe

Dieses Format schreibt strukturierte Ausgabe als text.format. Das Schema steht direkt in format, neben name und strict, nicht unter einem Member json_schema wie bei Chat Completions.

• {"type": "json_object"} fordert ein beliebiges JSON-Objekt an.
• {"type": "json_schema", "name", "schema", "strict"} fordert JSON an, das Ihrem Schema folgt. strict ist true, wenn Sie es weglassen.

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

Das JSON trifft als Text im output_text-Teil der Nachricht ein; parsen Sie es selbst. Ein gehostetes Open-Weight-Modell ohne strukturierte Ausgabe gibt 400 zurück.

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

Welches Modell welche Form annimmt, ist auf einer eigenen Seite aufgeführt. Strukturierte Ausgaben

Reasoning

Ein Modell, das nachdenkt, liefert sein Reasoning als Output-Element vom Typ reasoning, vor der Nachricht. In einem Stream trifft es als response.reasoning_summary_text.delta-Events ein.

Die gehosteten Open-Weight-Modelle wenden reasoning.effort an: off, low, medium oder high, mit high, wenn Sie nichts senden. off liefert kein Reasoning-Element. Senden Sie es als Objekt; ein bloßer String wird bei diesem Endpunkt nicht gelesen.

Die Aufwandsstufen sind auf einer eigenen Seite beschrieben. Reasoning-Aufwand

Output-Limit

max_output_tokens beträgt 4,096, wenn Sie es nicht senden. Es ist die Anzahl der Tokens, die beim Start der Anfrage von Ihrem Guthaben zurückgelegt werden; ist die Antwort vollständig, wird dieser Betrag durch das ersetzt, was die Anfrage verbraucht hat. Ein Wert, der nicht in Ihr verbleibendes Guthaben passt, gibt 429 Quota exceeded zurück.

Es begrenzt die Länge der Antwort bei shannon-1.6-*, shannon-2-* und shannon-coder-1 sowie die Länge des Antworttextes bei den gehosteten Open-Weight-Modellen.

Bei diesem Endpunkt wird shannon-coder-1 wie jedes andere Modell in Tokens von Ihrem Guthaben berechnet.

Ein Request-Body darf bis zu 32 MiB groß sein. Limits und Guthaben

Fehler

Fehler verwenden den OpenAI-Fehler-Body: ein Objekt error mit type und message; manche enthalten zusätzlich code und param mit dem Wert null. Die Tabelle listet, was dieser Endpunkt am häufigsten zurückgibt. Die vollständige Liste, mit Hinweisen, was wiederholt werden sollte, hat eine eigene Seite. Fehlerbehandlung