Responses API

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

Ang pinakamaliit na request ay isang model id at isang text. Hindi naka-stream ang reply maliban kung hilingin mo.

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

Ang reply ay isang response object. Hawak ng output nito ang reasoning, kung nag-reason ang model, at ang message:

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

Mga request field

Ang model at input ang kailangan ng request. Pinangangalanan ng column na Ina-apply ng ang mga model kung saan binabago ng isang field ang reply. Ang mga hosted open-weight model ay ang labindalawang id sa listahan ng model; ang pamilyang Shannon 3 ay shannon-3, shannon-3-pro, shannon-3.1 at shannon-3.1-pro. Mga model at presyo

Tinatanggap ang previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user at prompt_cache_key para tumakbo nang walang pagbabago ang kasalukuyang client code. Hindi nila binabago ang reply. Dahil walang itinatagong conversation, dala ng kasunod na request ang mga naunang turn sa input.

Mga input item

Ang input item ay alinman sa message, na may role at content, o typed na item na may dalang tool call o ang resulta nito. Ang content ay isang string o array ng mga part.

Ilagay ang mga tagubilin sa field na instructions. Sa isang id ng pamilyang Shannon 3, ilagay sa user message ang mga tagubiling dapat masunod.

Ang mga item ng output ng reply ay maaaring bumalik sa input nang buo: binabasa ang mga message at function_call item, nilalaktawan ang mga reasoning item.

Mga content part

Sa mga Shannon tier, binabasa ang mga image at file mula sa huling user item ng input. May sariling pahina ang mga laki at limitasyon. Mga image at file

Isang request na may instructions at mga opsyon

Nagpapadala ang request na ito ng instructions, isang conversation bilang mga input item, output limit, temperature at reasoning effort. Gumagamit ito ng hosted open-weight model, na ina-apply ang lahat ng ito.

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

Ang reply ng hosted open-weight model ay may id, object, model, created_at, status, output at usage. Nagdaragdag ang usage nito ng mga token na binasa mula sa cache at mga token na ginugol sa reasoning:

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

Ang response object

Nasa bawat reply ang id, object, status, output at usage. Itayo ang iyong code sa mga iyon.

Mga output item

Ang mga OpenAI SDK ang nagdurugtong ng text ng message para sa iyo sa response.output_text.

Streaming

I-set ang stream sa true para sa server-sent events. Ang bawat frame ay may event: line na may pangalan ng event at data: line na may JSON object; inuulit ng object ang pangalan sa type. Itugma ang mga delta sa item nila gamit ang output_index.

Sa OpenAI SDK, basahin ang mga event ayon sa type ng mga ito:

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

Dumarating ang mga event sa pagkakasunod na ito. Lumalabas lamang ang mga grupo para sa reasoning, message at tool call kapag mayroon ang reply.

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

Isang stream na nabibigo

Sa mga Shannon tier, ang nabigong reply ay nagtatapos sa response.failed sa halip na response.completed. Ang response.status nito ay failed at ang response.error ay may hawak na code, rate_limit_exceeded o server_error, at isang message.

Sa mga hosted open-weight model, ang pagkabigo ay isang error event na may code na api_error at isang message. Sumusunod pa rin ang response.completed.

Ituring na nabigo ang stream kapag may hawak itong response.failed o error event, at ipadala muli ang request.

Tools

Ang tool ay isang function na pinapatakbo ng iyong code. Ilarawan ito sa tools; kapag kailangan ito ng model, may function_call item ang reply bilang kapalit ng, o katabi ng, message.

Isang tool definition sa tools:

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

Ang output ng reply na tumatawag dito:

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

Patakbuhin ang function, saka ipadala muli ang request na may call at resulta nito na idinagdag sa 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\"}"
  }
]

Mga tool lang na type na function ang binabasa. Sa shannon-1.6-*, shannon-2-* at shannon-coder-1, binabawasan ang parameters schema sa mga karaniwang JSON Schema keyword: ang oneOf ay binabasa bilang anyOf, at ang mga keyword gaya ng $ref, additionalProperties, const, default at title ay hindi ipinapasa sa model.

Ina-apply ng mga hosted open-weight model ang mga value ng tool_choice na required at isang pinangalanang function.

Buong inilalarawan ang tool loop sa sarili nitong pahina. Function calling

Structured output

Isinusulat ng format na ito ang structured output bilang text.format. Ang schema ay direktang nasa format, katabi ng name at strict, hindi sa ilalim ng miyembrong json_schema tulad sa Chat Completions.

• Humihingi ang {"type": "json_object"} ng anumang JSON object.
• Humihingi ang {"type": "json_schema", "name", "schema", "strict"} ng JSON na sumusunod sa iyong schema. Ang strict ay true kapag inalis mo ito.

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

Dumarating ang JSON bilang text sa output_text part ng message; i-parse mo ito mismo. Ang hosted open-weight model na walang structured output ay nagbabalik ng 400.

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

Nakalista sa sarili nitong pahina kung aling model ang tumatanggap ng aling anyo. Structured outputs

Reasoning

Ibinabalik ng model na nag-re-reason ang reasoning nito bilang output item na type na reasoning, bago ang message. Sa isang stream, dumarating ito bilang mga event na response.reasoning_summary_text.delta.

Ina-apply ng mga hosted open-weight model ang reasoning.effort: off, low, medium o high, na high kapag wala kang ipinadala. Ang off ay walang ibinabalik na reasoning item. Ipadala ito bilang object; hindi binabasa ang payak na string sa endpoint na ito.

Inilalarawan ang mga effort sa kanilang sariling pahina. Reasoning effort

Output limit

Ang max_output_tokens ay 4,096 kapag hindi mo ito ipinadala. Ito ang bilang ng token na itinatabi mula sa iyong balance kapag nagsimula ang request; kapag kumpleto na ang reply, pinapalitan ang halagang iyon ng nagamit ng request. Ang value na hindi kasya sa natitira mong balance ay nagbabalik ng 429 Quota exceeded.

Nililimitahan nito ang haba ng reply sa shannon-1.6-*, shannon-2-* at shannon-coder-1, at ang haba ng text ng sagot sa mga hosted open-weight model.

Sa endpoint na ito, ang shannon-coder-1 ay sinisingil sa tokens mula sa iyong balance, tulad ng bawat ibang model.

Ang request body ay maaaring umabot sa 32 MiB. Mga limitasyon at balance

Mga error

Ginagamit ng mga error ang OpenAI error body: isang error object na may type at message; ang ilan ay may dala ring code at param na may value na null. Inililista ng talahanayan ang pinakamadalas na ibinabalik ng endpoint na ito. May sariling pahina ang buong listahan, kasama kung ano ang dapat i-retry. Paghawak ng Error