Responses API

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

Pienin pyyntö on mallin id ja teksti. Vastaus ei ole striimattu, ellet pyydä sitä.

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

Vastaus on vasteobjekti. Sen output sisältää päättelyn, kun malli päätteli, ja viestin:

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

Pyynnön kentät

model ja input ovat se, mitä pyyntö tarvitsee. Sarake Ottavat huomioon nimeää mallit, joilla kenttä muuttaa vastausta. Hostatut avoimen painon mallit ovat mallilistan kaksitoista id:tä; Shannon 3 -perhe on shannon-3, shannon-3-pro, shannon-3.1 ja shannon-3.1-pro. Mallit ja hinnoittelu

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user ja prompt_cache_key hyväksytään, jotta olemassa oleva asiakaskoodi toimii muuttumattomana. Ne eivät muuta vastausta. Koska keskustelua ei tallenneta, jatkopyyntö sisältää aiemmat vuorot kentässä input.

Syötealkiot

Syötealkio on joko viesti, jossa on role ja content, tai tyypitetty alkio, joka sisältää työkalukutsun tai sen tuloksen. content on merkkijono tai osien taulukko.

Pane ohjeet kenttään instructions. Shannon 3 -perheen id:llä pane ohjeet, joiden on pidettävä, user-viestiin.

Vastauksen output-kentän alkiot voi palauttaa kenttään input sellaisinaan: message- ja function_call-alkiot luetaan, reasoning-alkiot ohitetaan.

Sisältöosat

Shannon-tasoilla kuvat ja tiedostot luetaan input-kentän viimeisestä user-alkiosta. Koot ja rajat ovat omalla sivullaan. Kuvat ja tiedostot

Pyyntö ohjeilla ja asetuksilla

Tämä pyyntö lähettää ohjeet, keskustelun syötealkioina, tulosteen rajan, lämpötilan ja päättelytehon. Se käyttää hostattua avoimen painon mallia, joka ottaa ne kaikki huomioon.

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

Hostatun avoimen painon mallin vastauksessa on id, object, model, created_at, status, output ja usage. Sen usage lisää välimuistista luetut tokenit ja päättelyyn kulutetut tokenit:

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

Vasteobjekti

id, object, status, output ja usage ovat jokaisessa vastauksessa. Rakenna koodisi niiden varaan.

Tulostealkiot

OpenAI-SDK:t yhdistävät viestin tekstin puolestasi kenttään response.output_text.

Striimaus

Aseta stream arvoon true saadaksesi server-sent events -tapahtumat. Jokaisessa kehyksessä on event:-rivi tapahtuman nimellä ja data:-rivi JSON-objektilla; objekti toistaa nimen kentässä type. Yhdistä deltat alkioonsa kentän output_index mukaan.

OpenAI-SDK:lla lue tapahtumat niiden type-kentän mukaan:

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

Tapahtumat saapuvat tässä järjestyksessä. Päättelyn, viestin ja työkalukutsujen ryhmät ilmestyvät vain, kun vastauksessa on niitä.

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

Striimi, joka epäonnistuu

Shannon-tasoilla epäonnistunut vastaus päättyy tapahtumaan response.failed tapahtuman response.completed sijaan. Sen response.status on failed ja response.error sisältää code-kentän, rate_limit_exceeded tai server_error, sekä message-kentän.

Hostatuilla avoimen painon malleilla virhe on error-tapahtuma, jossa on code api_error ja message. response.completed seuraa sitä silti.

Pidä striimiä epäonnistuneena, kun siinä on response.failed- tai error-tapahtuma, ja lähetä pyyntö uudelleen.

Työkalut

Työkalu on funktio, jonka koodisi suorittaa. Kuvaa se kentässä tools; kun malli haluaa sen, vastauksessa on function_call-alkio viestin tilalla tai sen vieressä.

Työkalumääritys kentässä tools:

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

Sen kutsuvan vastauksen output:

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

Suorita funktio ja lähetä sitten pyyntö uudelleen niin, että kutsu ja sen tulos on lisätty kenttään 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\"}"
  }
]

Vain tyypin function työkalut luetaan. Malleilla shannon-1.6-*, shannon-2-* ja shannon-coder-1 parameters-skeema supistetaan yleisiin JSON Schema -avainsanoihin: oneOf luetaan kuten anyOf, eikä avainsanoja, kuten $ref, additionalProperties, const, default ja title, välitetä mallille.

tool_choice-arvot required ja nimetty funktio otetaan huomioon hostatuilla avoimen painon malleilla.

Työkaluilla toimiva silmukka on kuvattu kokonaan omalla sivullaan. Toiminto kutsu

Strukturoitu tuloste

Tämä muoto kirjoittaa strukturoidun tulosteen muodossa text.format. Skeema on suoraan kentässä format, kenttien name ja strict vieressä, ei json_schema-jäsenen alla kuten Chat Completionsissa.

• {"type": "json_object"} pyytää mitä tahansa JSON-objektia.
• {"type": "json_schema", "name", "schema", "strict"} pyytää JSONia, joka noudattaa skeemaasi. strict on true, kun jätät sen pois.

{
  "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 saapuu tekstinä viestin output_text-osassa; jäsennä se itse. Hostattu avoimen painon malli ilman strukturoitua tulostetta palauttaa 400.

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

Mikä malli ottaa minkä muodon, on listattu omalla sivullaan. Strukturoidut lähdöt

Päättely

Päättelevä malli palauttaa päättelynsä tyypin reasoning tulostealkiona ennen viestiä. Striimissä se saapuu response.reasoning_summary_text.delta-tapahtumina.

Hostatut avoimen painon mallit ottavat huomioon reasoning.effort: off, low, medium tai high, ja high, kun et lähetä mitään. off ei palauta päättelyalkiota. Lähetä se objektina; pelkkää merkkijonoa ei lueta tässä päätepisteessä.

Tehot on kuvattu omalla sivullaan. Päättelyn teho

Tulosteen raja

max_output_tokens on 4,096, kun et lähetä sitä. Se on tokenmäärä, joka varataan saldostasi pyynnön alkaessa; kun vastaus on valmis, tämä määrä korvataan pyynnön käyttämällä määrällä. Arvo, joka ei mahdu jäljellä olevaan saldoosi, palauttaa 429 Quota exceeded.

Se rajaa vastauksen pituutta malleilla shannon-1.6-*, shannon-2-* ja shannon-coder-1 sekä vastaustekstin pituutta hostatuilla avoimen painon malleilla.

Tässä päätepisteessä shannon-coder-1 veloitetaan tokeneina saldostasi, kuten kaikki muutkin mallit.

Pyynnön runko voi olla enintään 32 MiB. Rajat ja saldo

Virheet

Virheet käyttävät OpenAI:n virherunkoa: error-objekti, jossa on type ja message; joissakin on myös code ja param arvolla null. Taulukossa on yleisimmin palautuvat virheet tästä päätepisteestä. Täydellinen lista uudelleenyrityksineen on omalla sivullaan. Virheiden käsittely