Responses API

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

Den minste forespørselen er en modell-id og en tekst. Svaret sendes ikke som strøm med mindre du 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 er et respons-objekt. Dets output inneholder resonneringen, når modellen resonnerte, og meldingen:

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

Forespørselsfelt

model og input er det en forespørsel trenger. Kolonnen Brukes av oppgir modellene der et felt endrer svaret. De hostede åpne vektmodellene er de tolv id-ene i modelllisten; 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 godtas, slik at eksisterende klientkode kjører uendret. De endrer ikke svaret. Fordi ingen samtale lagres, har en oppfølgingsforespørsel de tidligere rundene i input.

Input-elementer

Et input-element er enten en melding, med en role og en content, eller et typet element som bærer et verktøykall eller resultatet av det. content er en streng eller en matrise av deler.

Legg instruksjoner i feltet instructions. Med en id fra Shannon 3-familien legger du instruksjoner som må gjelde, i user-meldingen.

Elementene i output fra et svar kan sendes tilbake i input som de er: message- og function_call-elementer leses, reasoning-elementer hoppes over.

Innholdsdeler

På Shannon-nivåene leses bilder og filer fra det siste user-elementet i input. Størrelser og grenser har en egen side. Bilder og filer

En forespørsel med instruksjoner og valg

Denne forespørselen sender instruksjoner, en samtale som input-elementer, en utdatagrense, en temperatur og en resonneringsinnsats. Den bruker en hostet åpen vektmodell, som tar hensyn til 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 åpen vektmodell har id, object, model, created_at, status, output og usage. Dens usage legger til tokens lest fra cachen og tokens brukt på resonnering:

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

Respons-objektet

id, object, status, output og usage finnes i hvert svar. Bygg koden din på dem.

Output-elementer

OpenAI-SDK-ene slår sammen teksten i meldingen for deg i response.output_text.

Streaming

Sett stream til true for server-sent events. Hver ramme har en event:-linje med navnet på hendelsen og en data:-linje med et JSON-objekt; objektet gjentar navnet i type. Knytt deltaer til elementet sitt med output_index.

Med OpenAI-SDK-en leser du hendelsene etter 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
  }'

Hendelsene kommer i denne rekkefølgen. Gruppene for resonnering, meldingen og verktøykall finnes bare 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 feiler

På Shannon-nivåene ender et mislykket svar med response.failed i stedet for response.completed. Dets response.status er failed, og response.error inneholder en code, rate_limit_exceeded eller server_error, og en message.

På de hostede åpne vektmodellene er en feil en error-hendelse med code api_error og en message. response.completed følger likevel etter den.

Behandle en strøm som mislykket når den inneholder en response.failed- eller en error-hendelse, og send forespørselen på nytt.

Verktøy

Et verktøy er en funksjon koden din kjører. Beskriv det i tools; når modellen vil bruke det, inneholder svaret et function_call-element i stedet for meldingen, eller ved siden av den.

En verktøydefinisjon 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 som kaller det:

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

Kjør funksjonen, og send så forespørselen på nytt med kallet og resultatet lagt til 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\"}"
  }
]

Bare verktøy av typen function leses. På shannon-1.6-*, shannon-2-* og shannon-coder-1 reduseres parameters-skjemaet til de vanlige JSON Schema-nøkkelordene: oneOf leses som anyOf, og nøkkelord som $ref, additionalProperties, const, default og title videresendes ikke til modellen.

tool_choice-verdiene required og en navngitt funksjon brukes av de hostede åpne vektmodellene.

Verktøysløyfen er beskrevet fullt ut på sin egen side. Funksjonskall

Strukturert utdata

Dette formatet skriver strukturert utdata som text.format. Skjemaet ligger direkte i format, ved siden av name og strict, ikke under et json_schema-medlem som på Chat Completions.

• {"type": "json_object"} ber om et vilkårlig JSON-objekt.
• {"type": "json_schema", "name", "schema", "strict"} ber om JSON som følger skjemaet ditt. strict er true når du utelater 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 kommer som tekst i output_text-delen av meldingen; parse den selv. En hostet åpen vektmodell uten strukturert utdata returnerer 400.

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

Hvilken modell som tar hvilken form, er listet på sin egen side. Strukturerte utdata

Resonnering

En modell som resonnerer, returnerer resonneringen som et output-element av typen reasoning, før meldingen. I en strøm kommer den som response.reasoning_summary_text.delta-hendelser.

De hostede åpne vektmodellene bruker reasoning.effort: off, low, medium eller high, med high når du ikke sender noe. off returnerer ikke noe resonneringselement. Send det som et objekt; en ren streng leses ikke på dette endepunktet.

Innsatsnivåene er beskrevet på sin egen side. Resonneringsinnsats

Utdatagrense

max_output_tokens er 4,096 når du ikke sender det. Det er antallet tokens som settes av fra saldoen din når forespørselen starter; når svaret er fullført, erstattes dette beløpet av det forespørselen brukte. En verdi som ikke får plass i den resterende saldoen din, returnerer 429 Quota exceeded.

Den begrenser lengden på svaret på shannon-1.6-*, shannon-2-* og shannon-coder-1, og lengden på svarteksten på de hostede åpne vektmodellene.

På dette endepunktet belastes shannon-coder-1 i tokens fra saldoen din, som alle andre modeller.

En forespørselskropp kan være opptil 32 MiB. Grenser og saldo

Feil

Feil bruker OpenAI-feilkroppen: et error-objekt med type og message; noen har også code og param med verdien null. Tabellen lister det dette endepunktet oftest returnerer. Den fullstendige listen, med hva som kan prøves på nytt, har en egen side. Feilhåndtering