Responses API

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

Ny fangatahana kely indrindra dia id model sy soratra. Ny valiny dia tsy streamed raha tsy angatahinao.

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

Ny valiny dia response object. Ny output-ny dia misy ny reasoning, raha nanao reasoning ny model, sy ny hafatra:

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

Saha fangatahana

Ny model sy input no ilain'ny fangatahana. Ny tsanganana Applied by dia manonona ny model izay anovan'ny saha ny valiny. Ny model open-weight hosted dia ny id roa ambin'ny folo ao amin'ny lisitry ny model; ny fianakavian'i Shannon 3 dia shannon-3, shannon-3-pro, shannon-3.1 ary shannon-3.1-pro. Model & vidiny

Raisina ny previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user ary prompt_cache_key mba hahafahan'ny kaody client efa misy mandeha tsy miova. Tsy manova ny valiny izy ireo. Satria tsy misy resaka voatahiry, ny fangatahana manaraka dia mitondra ny fihodinana teo aloha ao amin'ny input.

Input item

Ny input item dia na hafatra, misy role sy content, na item misy karazana mitondra tool call na ny valiny. Ny content dia string na array misy ampahany.

Apetraho ao amin'ny saha instructions ny toromarika. Amin'ny id ao amin'ny fianakavian'i Shannon 3, apetraho ao amin'ny hafatra user ny toromarika tsy maintsy tanteraka.

Ny item ao amin'ny output an'ny valiny dia azo averina ao amin'ny input araka izy: ny item message sy function_call dia vakiana, ny item reasoning dia lavina.

Content part

Amin'ny tier Shannon, ny sary sy rakitra dia vakiana avy amin'ny item user farany ao amin'ny input. Ny habe sy fetra dia manana pejy manokana. Sary sy rakitra

Fangatahana misy instructions sy options

Ity fangatahana ity dia mandefa instructions, resaka ho input item, output limit, temperature ary reasoning effort. Mampiasa model open-weight hosted izy, izay mampihatra ireo rehetra.

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

Ny valin'ny model open-weight hosted dia manana id, object, model, created_at, status, output ary usage. Ny usage-ny dia manampy ny token novakina avy amin'ny cache sy ny token lany tamin'ny reasoning:

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

Ny response object

Ny id, object, status, output ary usage dia misy amin'ny valiny rehetra. Iorina amin'ireo ny kaody-nao.

Output item

Ny SDK OpenAI dia manambatra ho anao ny soratry ny hafatra ao amin'ny response.output_text.

Streaming

Apetraho ho true ny stream ho server-sent events. Ny frame tsirairay dia manana andalana event: misy ny anaran'ny event ary andalana data: misy object JSON; ny object dia mamerina ny anarana ao amin'ny type. Ampifanaraho amin'ny item-ny amin'ny output_index ny delta.

Miaraka amin'ny SDK OpenAI, vakio araka ny type-ny ny event:

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

Tonga araka ity filaharana ity ny event. Ny vondrona ho an'ny reasoning, ny hafatra ary ny tool call dia miseho rehefa manana azy ny valiny ihany.

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 tsy mahomby

Amin'ny tier Shannon, ny valiny tsy nahomby dia mifarana amin'ny response.failed fa tsy response.completed. Ny response.status-ny dia failed ary ny response.error dia mitazona code, rate_limit_exceeded na server_error, ary message.

Amin'ny model open-weight hosted, ny tsy fahombiazana dia event error miaraka amin'ny code api_error sy message. Mbola manaraka azy ny response.completed.

Heverina ho tsy nahomby ny stream rehefa misy event response.failed na error, ary alefaso indray ny fangatahana.

Tools

Ny tool dia function ampandehanin'ny kaody-nao. Faritano ao amin'ny tools; rehefa mila azy ny model, ny valiny dia misy item function_call solon'ny hafatra, na eo anilany.

Famaritana tool ao amin'ny tools:

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

Ny output an'ny valiny miantso azy:

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

Ampandehano ny function, avy eo alefaso indray ny fangatahana miaraka amin'ny antso sy ny valiny nampidirina ao amin'ny 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\"}"
  }
]

Ny tool karazana function ihany no vakiana. Amin'ny shannon-1.6-*, shannon-2-* ary shannon-coder-1 ny schema parameters dia ahena ho keyword JSON Schema iraisana: ny oneOf dia vakiana ho anyOf, ary ny keyword toy ny $ref, additionalProperties, const, default ary title dia tsy atolotra ny model.

Ny sanda tool_choice required sy function voatondro dia ampiharin'ny model open-weight hosted.

Ny tool loop dia voasoratra tanteraka ao amin'ny pejiny manokana. Antso fiasa

Structured output

Ity endrika ity dia manoratra ny structured output ho text.format. Ny schema dia mipetraka mivantana ao amin'ny format, eo anilan'ny name sy strict, fa tsy ao ambanin'ny mpikambana json_schema toy ny amin'ny Chat Completions.

• Ny {"type": "json_object"} dia mangataka object JSON na inona na inona.
• Ny {"type": "json_schema", "name", "schema", "strict"} dia mangataka JSON araka ny schema-nao. Ny strict dia true raha tsy asianao.

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

Ny JSON dia tonga ho soratra ao amin'ny ampahany output_text an'ny hafatra; parse-o ianao. Ny model open-weight hosted tsy manana structured output dia mamerina 400.

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

Izay model mandray izay endrika dia voatanisa ao amin'ny pejiny manokana. Vokatra voarafitra

Reasoning

Ny model manao reasoning dia mamerina ny reasoning-ny ho output item karazana reasoning, alohan'ny hafatra. Ao anaty stream dia tonga ho event response.reasoning_summary_text.delta.

Ny model open-weight hosted dia mampihatra ny reasoning.effort: off, low, medium na high, miaraka amin'ny high raha tsy mandefa na inona na inona ianao. Ny off dia tsy mamerina item reasoning. Alefaso ho object; ny string tsotra dia tsy vakiana amin'ity endpoint ity.

Voasoratra ao amin'ny pejiny manokana ny effort. Reasoning effort

Output limit

4,096 ny max_output_tokens raha tsy alefanao. Io no isan'ny token voatahiry avy amin'ny balance-nao rehefa manomboka ny fangatahana; rehefa vita ny valiny, io habetsaka io dia soloina izay nampiasain'ny fangatahana. Ny sanda tsy mifanaraka amin'ny balance sisa dia mamerina 429 Quota exceeded.

Mametra ny halavan'ny valiny izy amin'ny shannon-1.6-*, shannon-2-* ary shannon-coder-1, ary ny halavan'ny soratry ny valiny amin'ny model open-weight hosted.

Amin'ity endpoint ity, ny shannon-coder-1 dia vidiana amin'ny token avy amin'ny balance-nao, tahaka ny model hafa rehetra.

Ny body ny fangatahana dia hatramin'ny 32 MiB. Fetra sy balance

Hadisoana

Ny hadisoana dia mampiasa ny body hadisoana OpenAI: object error misy type sy message; ny sasany dia mitondra code sy param koa miaraka amin'ny sanda null. Ny tabilao dia mitanisa izay averin'ity endpoint ity matetika indrindra. Ny lisitra feno, miaraka amin'izay hatao retry, dia manana pejy manokana. Fitantanana hadisoana