Responses API

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

Den minsta begäran är ett modell-id och en text. Svaret streamas inte om du inte ber om det.

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

Svaret är ett response-objekt. Dess output innehåller resonemanget, när modellen resonerade, och meddelandet:

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

Begäranfält

model och input är vad en begäran behöver. Kolumnen Tillämpas av anger de modeller där ett fält ändrar svaret. De hostade open-weight-modellerna är de tolv id:na i modelllistan; Shannon 3-familjen är shannon-3, shannon-3-pro, shannon-3.1 och shannon-3.1-pro. Modeller och priser

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user och prompt_cache_key accepteras så att befintlig klientkod körs oförändrad. De ändrar inte svaret. Eftersom ingen konversation sparas bär en uppföljande begäran de tidigare vändningarna i input.

Inputobjekt

Ett inputobjekt är antingen ett meddelande, med en role och ett content, eller ett typat objekt som bär ett verktygsanrop eller dess resultat. content är en sträng eller en array av delar.

Lägg instruktioner i fältet instructions. Med ett id i Shannon 3-familjen lägger du instruktioner som måste gälla i user-meddelandet.

Objekten i ett svars output kan gå tillbaka in i input som de är: message- och function_call-objekt läses, reasoning-objekt hoppas över.

Innehållsdelar

På Shannon-nivåerna läses bilder och filer från det sista user-objektet i input. Storlekar och gränser har en egen sida. Bilder och filer

En begäran med instruktioner och alternativ

Den här begäran skickar instruktioner, en konversation som inputobjekt, en outputgräns, en temperatur och en resonemangsnivå. Den använder en hostad open-weight-modell, som tillämpar alla.

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

Svaret från en hostad open-weight-modell har id, object, model, created_at, status, output och usage. Dess usage lägger till de tokens som lästes från cachen och de tokens som gick åt till resonemang:

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

Response-objektet

id, object, status, output och usage finns i varje svar. Bygg din kod på dem.

Outputobjekt

OpenAI-SDK:erna sammanfogar meddelandets text åt dig i response.output_text.

Streaming

Sätt stream till true för server-sent events. Varje frame har en event:-rad med händelsens namn och en data:-rad med ett JSON-objekt; objektet upprepar namnet i type. Koppla deltan till sitt objekt med output_index.

Med OpenAI-SDK:n läser du händelserna efter deras 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
  }'

Händelserna kommer i den här ordningen. Grupperna för resonemang, meddelandet och verktygsanrop förekommer bara när svaret har dem.

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

En ström som misslyckas

På Shannon-nivåerna slutar ett misslyckat svar med response.failed i stället för response.completed. Dess response.status är failed och response.error innehåller en code, rate_limit_exceeded eller server_error, och ett message.

På de hostade open-weight-modellerna är ett fel en error-händelse med code api_error och ett message. response.completed följer ändå efter den.

Behandla en ström som misslyckad när den innehåller en response.failed- eller en error-händelse, och skicka begäran igen.

Verktyg

Ett verktyg är en funktion som din kod kör. Beskriv det i tools; när modellen vill ha det innehåller svaret ett function_call-objekt i stället för, eller bredvid, meddelandet.

En verktygsdefinition i tools:

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

output i ett svar som anropar det:

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

Kör funktionen och skicka sedan begäran igen med anropet och dess resultat tillagda i 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\"}"
  }
]

Endast verktyg av typen function läses. På shannon-1.6-*, shannon-2-* och shannon-coder-1 reduceras parameters-schemat till de vanliga JSON Schema-nyckelorden: oneOf läses som anyOf, och nyckelord som $ref, additionalProperties, const, default och title förs inte vidare till modellen.

tool_choice-värdena required och en namngiven funktion tillämpas av de hostade open-weight-modellerna.

Verktygsloopen beskrivs i sin helhet på sin egen sida. Funktionsanrop

Strukturerad output

Det här formatet skriver strukturerad output som text.format. Schemat ligger direkt i format, bredvid name och strict, inte under en json_schema-medlem som på Chat Completions.

• {"type": "json_object"} ber om vilket JSON-objekt som helst.
• {"type": "json_schema", "name", "schema", "strict"} ber om JSON som följer ditt schema. strict är true när du utelämnar det.

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

JSON-koden kommer som text i meddelandets output_text-del; parsa den själv. En hostad open-weight-modell utan strukturerad output returnerar 400.

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

Vilken modell som tar vilken form listas på sin egen sida. Strukturerade utdata

Resonemang

En modell som resonerar returnerar sitt resonemang som ett outputobjekt av typen reasoning, före meddelandet. I en ström kommer det som response.reasoning_summary_text.delta-händelser.

De hostade open-weight-modellerna tillämpar reasoning.effort: off, low, medium eller high, med high när du inte skickar något. off returnerar inget resonemangsobjekt. Skicka det som ett objekt; en ren sträng läses inte på den här endpointen.

Resonemangsnivåerna beskrivs på sin egen sida. Resonemangsansträngning

Outputgräns

max_output_tokens är 4,096 när du inte skickar det. Det är det antal tokens som reserveras från din balans när begäran startar; när svaret är komplett ersätts det beloppet av det som begäran använde. Ett värde som inte ryms i din återstående balans returnerar 429 Quota exceeded.

Den begränsar svarets längd på shannon-1.6-*, shannon-2-* och shannon-coder-1, och svarstextens längd på de hostade open-weight-modellerna.

På den här endpointen debiteras shannon-coder-1 i tokens från din balans, som varje annan modell.

En begäranbody kan vara upp till 32 MiB. Gränser och balans

Fel

Fel använder OpenAI:s felbody: ett error-objekt med type och message; vissa bär också code och param med värdet null. Tabellen listar det som den här endpointen oftast returnerar. Den fullständiga listan, med vad som kan försökas igen, har en egen sida. Felhantering