Responses API

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

Den mindste anmodning er et model-id og en tekst. Svaret streames ikke, medmindre du beder 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 er et response-objekt. Dets output indeholder ræsonnementet, når modellen har ræsonneret, og beskeden:

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

Anmodningsfelter

model og input er det, en anmodning har brug for. Kolonnen Anvendes af nævner de modeller, hvor et felt ændrer svaret. De hostede open-weight-modeller er de tolv id'er på modellisten; Shannon 3-familien er shannon-3, shannon-3-pro, shannon-3.1 og shannon-3.1-pro. Modeller og priser

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user og prompt_cache_key accepteres, så eksisterende klientkode kører uændret. De ændrer ikke svaret. Fordi ingen samtale gemmes, bærer en opfølgende anmodning de tidligere ture i input.

Input-elementer

Et input-element er enten en besked, med en role og et content, eller et typet element, der bærer et værktøjskald eller dets resultat. content er en streng eller et array af dele.

Læg instruktioner i feltet instructions. Med et id fra Shannon 3-familien skal du lægge instruktioner, der skal holde, i user-beskeden.

Elementerne i et svars output kan sendes tilbage i input som de er: message- og function_call-elementer læses, reasoning-elementer springes over.

Indholdsdele

På Shannon-niveauerne læses billeder og filer fra det sidste user-element i input. Størrelser og grænser har deres egen side. Billeder og filer

En anmodning med instruktioner og indstillinger

Denne anmodning sender instruktioner, en samtale som input-elementer, en outputgrænse, en temperatur og en ræsonnementsindsats. Den bruger en hostet open-weight-model, som anvender dem alle.

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 fra en hostet open-weight-model har id, object, model, created_at, status, output og usage. Dets usage tilføjer de tokens, der er læst fra cachen, og de tokens, der er brugt på ræsonnement:

{
  "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 og usage findes i hvert svar. Byg din kode på dem.

Output-elementer

OpenAI-SDK'erne samler beskedens tekst for dig i response.output_text.

Streaming

Sæt stream til true for server-sent events. Hver ramme har en event:-linje med hændelsens navn og en data:-linje med et JSON-objekt; objektet gentager navnet i type. Knyt deltaer til deres element via output_index.

Med OpenAI-SDK'et læser du hændelserne efter deres 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ændelserne ankommer i denne rækkefølge. Grupperne for ræsonnement, beskeden og værktøjskald optræder kun, 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 stream, der fejler

På Shannon-niveauerne slutter et fejlet svar med response.failed i stedet for response.completed. Dets response.status er failed, og response.error indeholder en code, rate_limit_exceeded eller server_error, og en message.

På de hostede open-weight-modeller er en fejl en error-hændelse med code api_error og en message. response.completed følger stadig efter den.

Betragt en stream som fejlet, når den indeholder en response.failed- eller en error-hændelse, og send anmodningen igen.

Værktøjer

Et værktøj er en funktion, din kode kører. Beskriv det i tools; når modellen vil have det, indeholder svaret et function_call-element i stedet for beskeden eller ved siden af den.

En værktøjsdefinition i tools:

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

output i et svar, der kalder det:

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

Kør funktionen, og send så anmodningen igen med kaldet og dets resultat tilføjet til 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\"}"
  }
]

Kun værktøjer af typen function læses. På shannon-1.6-*, shannon-2-* og shannon-coder-1 reduceres parameters-skemaet til de almindelige JSON Schema-nøgleord: oneOf læses som anyOf, og nøgleord som $ref, additionalProperties, const, default og title gives ikke videre til modellen.

Værdierne required og en navngiven funktion i tool_choice anvendes af de hostede open-weight-modeller.

Værktøjsløkken er beskrevet fuldt ud på sin egen side. Funktionskald

Struktureret output

Dette format staver struktureret output som text.format. Skemaet står direkte i format, ved siden af name og strict, ikke under et json_schema-medlem som på Chat Completions.

• {"type": "json_object"} beder om et vilkårligt JSON-objekt.
• {"type": "json_schema", "name", "schema", "strict"} beder om JSON, der følger dit skema. strict er true, når du udelader 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'en ankommer som tekst i beskedens output_text-del; parse den selv. En hostet open-weight-model uden struktureret output returnerer 400.

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

Hvilken model der tager hvilken form, står på dens egen side. Strukturerede outputs

Ræsonnement

En model, der ræsonnerer, returnerer sit ræsonnement som et output-element af typen reasoning før beskeden. I en stream ankommer det som response.reasoning_summary_text.delta-hændelser.

De hostede open-weight-modeller anvender reasoning.effort: off, low, medium eller high, med high når du intet sender. off returnerer intet ræsonnementselement. Send det som et objekt; en ren streng læses ikke på dette endpoint.

Effort-niveauerne er beskrevet på deres egen side. Reasoning effort

Outputgrænse

max_output_tokens er 4,096, når du ikke sender det. Det er det antal tokens, der sættes til side fra din saldo, når anmodningen starter; når svaret er færdigt, erstattes beløbet af det, anmodningen brugte. En værdi, der ikke kan rummes i din resterende saldo, returnerer 429 Quota exceeded.

Den begrænser svarets længde på shannon-1.6-*, shannon-2-* og shannon-coder-1 og svarteksten på de hostede open-weight-modeller.

På dette endpoint afregnes shannon-coder-1 i tokens fra din saldo, som alle andre modeller.

En anmodnings body kan være op til 32 MiB. Grænser og saldo

Fejl

Fejl bruger OpenAI's fejl-body: et error-objekt med type og message; nogle har også code og param med værdien null. Tabellen opregner det, dette endpoint oftest returnerer. Den fulde liste, med hvad der kan prøves igen, har sin egen side. Fejlhåndtering