Responses API

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

Nejmenší požadavek je id modelu a text. Odpověď není streamovaná, pokud o to nepožádáte.

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

Odpověď je objekt odpovědi. Jeho output obsahuje uvažování, pokud model uvažoval, a zprávu:

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

Pole požadavku

Požadavek potřebuje model a input. Sloupec Uplatňují uvádí modely, u kterých pole mění odpověď. Hostované modely s otevřenými váhami jsou dvanáct id ze seznamu modelů; rodina Shannon 3 je shannon-3, shannon-3-pro, shannon-3.1 a shannon-3.1-pro. Modely a ceny

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user a prompt_cache_key se přijímají, aby stávající klientský kód běžel beze změn. Odpověď nemění. Protože se žádná konverzace neukládá, navazující požadavek nese dřívější kola v input.

Vstupní položky

Vstupní položka je buď zpráva s role a content, nebo typovaná položka, která nese volání nástroje nebo jeho výsledek. content je řetězec nebo pole částí.

Instrukce dejte do pole instructions. S id z rodiny Shannon 3 dejte instrukce, které musí platit, do zprávy user.

Položky output odpovědi mohou jít zpět do input tak, jak jsou: položky message a function_call se čtou, položky reasoning se přeskakují.

Části obsahu

Na úrovních Shannon se obrázky a soubory čtou z poslední položky user v input. Velikosti a limity mají vlastní stránku. Obrázky a soubory

Požadavek s instrukcemi a volbami

Tento požadavek posílá instrukce, konverzaci jako vstupní položky, limit výstupu, teplotu a úsilí o uvažování. Používá hostovaný model s otevřenými váhami, který uplatní všechno z toho.

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

Odpověď hostovaného modelu s otevřenými váhami má id, object, model, created_at, status, output a usage. Jeho usage přidává tokeny přečtené z cache a tokeny vynaložené na uvažování:

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

Objekt odpovědi

id, object, status, output a usage jsou v každé odpovědi. Na nich stavějte svůj kód.

Výstupní položky

SDK OpenAI za vás spojí text zprávy do response.output_text.

Streamování

Nastavte stream na true pro server-sent events. Každý rámec má řádek event: s názvem události a řádek data: s objektem JSON; objekt název opakuje v type. Delty přiřazujte k jejich položce podle output_index.

V SDK OpenAI čtěte události podle jejich 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
  }'

Události přicházejí v tomto pořadí. Skupiny pro uvažování, zprávu a volání nástrojů se objeví, jen když je odpověď má.

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

Stream, který selže

Na úrovních Shannon končí neúspěšná odpověď událostí response.failed místo response.completed. Její response.status je failed a response.error obsahuje code, rate_limit_exceeded nebo server_error, a message.

U hostovaných modelů s otevřenými váhami je selhání událost error s code api_error a message. Po ní stále následuje response.completed.

Stream považujte za neúspěšný, když obsahuje událost response.failed nebo error, a pošlete požadavek znovu.

Nástroje

Nástroj je funkce, kterou spouští váš kód. Popište ji v tools; když ji model chce, odpověď obsahuje položku function_call místo zprávy nebo vedle ní.

Definice nástroje v tools:

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

output odpovědi, která jej volá:

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

Spusťte funkci a pak pošlete požadavek znovu s přidaným voláním a jeho výsledkem v 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\"}"
  }
]

Čtou se jen nástroje typu function. U shannon-1.6-*, shannon-2-* a shannon-coder-1 se schéma parameters zredukuje na běžná klíčová slova JSON Schema: oneOf se čte jako anyOf a klíčová slova jako $ref, additionalProperties, const, default a title se modelu nepředávají.

Hodnoty tool_choice required a pojmenovaná funkce uplatňují hostované modely s otevřenými váhami.

Smyčka nástrojů je popsána celá na vlastní stránce. Volání funkcí

Strukturovaný výstup

Tento formát zapisuje strukturovaný výstup jako text.format. Schéma leží přímo v format, vedle name a strict, ne pod členem json_schema jako u Chat Completions.

• {"type": "json_object"} žádá o libovolný objekt JSON.
• {"type": "json_schema", "name", "schema", "strict"} žádá o JSON podle vašeho schématu. strict je true, když jej vynecháte.

{
  "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 přichází jako text v části output_text zprávy; zpracujte jej sami. Hostovaný model s otevřenými váhami bez strukturovaného výstupu vrací 400.

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

Který model přijímá kterou formu, je uvedeno na vlastní stránce. Strukturované výstupy

Uvažování

Model, který uvažuje, vrací své uvažování jako výstupní položku typu reasoning, před zprávou. Ve streamu přichází jako události response.reasoning_summary_text.delta.

Hostované modely s otevřenými váhami uplatňují reasoning.effort: off, low, medium nebo high, přičemž high platí, když nic neposíláte. off nevrací žádnou položku uvažování. Pošlete jej jako objekt; holý řetězec se na tomto endpointu nečte.

Úrovně úsilí jsou popsány na vlastní stránce. Úsilí uvažování

Limit výstupu

max_output_tokens je 4,096, když jej neposíláte. Je to počet tokenů odložených ze zůstatku na začátku požadavku; když je odpověď kompletní, tato částka se nahradí tím, co požadavek použil. Hodnota, která se nevejde do zbývajícího zůstatku, vrátí 429 Quota exceeded.

Omezuje délku odpovědi u shannon-1.6-*, shannon-2-* a shannon-coder-1 a délku textu odpovědi u hostovaných modelů s otevřenými váhami.

Na tomto endpointu se shannon-coder-1 účtuje v tokenech ze zůstatku, jako každý jiný model.

Tělo požadavku může mít až 32 MiB. Limity a zůstatek

Chyby

Chyby používají tělo chyby OpenAI: objekt error s type a message; některé nesou také code a param s hodnotou null. Tabulka uvádí, co tento endpoint vrací nejčastěji. Úplný seznam, včetně toho, co opakovat, má vlastní stránku. Zpracování chyb