Responses API

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

అతి చిన్న రిక్వెస్ట్ ఒక మోడల్ id మరియు ఒక టెక్స్ట్. మీరు అడిగితే తప్ప సమాధానం స్ట్రీమ్ కాదు.

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

సమాధానం ఒక response ఆబ్జెక్ట్. దాని output లో, మోడల్ రీజనింగ్ చేసి ఉంటే ఆ రీజనింగ్, మరియు మెసేజ్ ఉంటాయి:

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

రిక్వెస్ట్ ఫీల్డ్స్

రిక్వెస్ట్‌కు model మరియు input అవసరం. వర్తింపజేసేవి కాలమ్ ఒక ఫీల్డ్ సమాధానాన్ని మార్చే మోడల్స్‌ను పేర్కొంటుంది. హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్ అంటే మోడల్ జాబితాలోని పన్నెండు ids; Shannon 3 ఫ్యామిలీ అంటే shannon-3, shannon-3-pro, shannon-3.1 మరియు shannon-3.1-pro. మోడల్స్ & ధరలు

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user మరియు prompt_cache_key అంగీకరించబడతాయి, తద్వారా ఇప్పటికే ఉన్న క్లయింట్ కోడ్ మార్పు లేకుండా నడుస్తుంది. అవి సమాధానాన్ని మార్చవు. సంభాషణ నిల్వ చేయబడదు కాబట్టి, తదుపరి రిక్వెస్ట్ మునుపటి టర్న్‌లను input లో తీసుకువస్తుంది.

Input items

ఇన్‌పుట్ ఐటెమ్ అంటే role మరియు content ఉన్న మెసేజ్, లేదా టూల్ కాల్ లేదా దాని ఫలితాన్ని తీసుకువెళ్లే టైప్ చేసిన ఐటెమ్. content ఒక string లేదా భాగాల array.

సూచనలను instructions ఫీల్డ్‌లో ఉంచండి. Shannon 3 ఫ్యామిలీ id తో, తప్పక పాటించాల్సిన సూచనలను user మెసేజ్‌లో ఉంచండి.

సమాధానం యొక్క output ఐటెమ్‌లను అలాగే input లోకి తిరిగి పంపవచ్చు: message మరియు function_call ఐటెమ్‌లు చదవబడతాయి, reasoning ఐటెమ్‌లు విస్మరించబడతాయి.

కంటెంట్ భాగాలు

Shannon టియర్‌లలో చిత్రాలు మరియు ఫైళ్లు input లోని చివరి user ఐటెమ్ నుండి చదవబడతాయి. పరిమాణాలు మరియు పరిమితులకు ప్రత్యేక పేజీ ఉంది. చిత్రాలు మరియు ఫైళ్లు

instructions మరియు ఎంపికలతో ఒక రిక్వెస్ట్

ఈ రిక్వెస్ట్ ఇన్‌స్ట్రక్షన్స్, ఇన్‌పుట్ ఐటమ్స్‌గా ఒక సంభాషణ, అవుట్‌పుట్ పరిమితి, temperature, రీజనింగ్ ఎఫర్ట్ పంపుతుంది. ఇది హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్‌ను ఉపయోగిస్తుంది, అది వీటన్నింటినీ అమలు చేస్తుంది.

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

హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్ సమాధానంలో id, object, model, created_at, status, output, usage ఉంటాయి. దాని usage లో క్యాష్ నుండి చదివిన tokens, రీజనింగ్ కోసం ఖర్చయిన tokens అదనంగా ఉంటాయి:

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

response ఆబ్జెక్ట్

id, object, status, output, usage ప్రతి సమాధానంలో ఉంటాయి. మీ కోడ్‌ను వీటి ఆధారంగా రాయండి.

అవుట్‌పుట్ ఐటమ్స్

OpenAI SDKలు మెసేజ్ టెక్స్ట్‌ను మీ కోసం response.output_text లో కలిపి ఇస్తాయి.

స్ట్రీమింగ్

server-sent events కోసం stream ను true కి సెట్ చేయండి. ప్రతి ఫ్రేమ్‌లో ఈవెంట్ పేరుతో event: లైన్, JSON ఆబ్జెక్ట్‌తో data: లైన్ ఉంటాయి; ఆ ఆబ్జెక్ట్ type లో పేరును మళ్ళీ చెబుతుంది. డెల్టాలను వాటి ఐటమ్‌తో output_index ద్వారా జతచేయండి.

OpenAI SDK తో ఈవెంట్‌లను వాటి 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
  }'

ఈవెంట్‌లు ఈ క్రమంలో వస్తాయి. రీజనింగ్, మెసేజ్, టూల్ కాల్స్ గ్రూపులు సమాధానంలో అవి ఉన్నప్పుడు మాత్రమే కనిపిస్తాయి.

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

విఫలమయ్యే స్ట్రీమ్

Shannon టియర్స్‌లో విఫలమైన సమాధానం response.completed బదులు response.failed తో ముగుస్తుంది. దాని response.status విలువ failed, మరియు response.error లో code (rate_limit_exceeded లేదా server_error) మరియు message ఉంటాయి.

హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్‌లో వైఫల్యం అంటే code విలువ api_error మరియు ఒక message ఉన్న error ఈవెంట్. దాని తర్వాత కూడా response.completed వస్తుంది.

స్ట్రీమ్‌లో response.failed లేదా error ఈవెంట్ ఉంటే దాన్ని విఫలమైనదిగా పరిగణించండి, మరియు రిక్వెస్ట్‌ను మళ్ళీ పంపండి.

Tools

టూల్ అంటే మీ కోడ్ నడిపే ఫంక్షన్. దాన్ని tools లో వివరించండి; మోడల్‌కు అది కావాలనుకున్నప్పుడు, సమాధానంలో మెసేజ్ బదులుగా లేదా దాని పక్కన function_call ఐటమ్ ఉంటుంది.

tools లో ఒక టూల్ డెఫినిషన్:

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

దాన్ని కాల్ చేసే సమాధానం యొక్క output:

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

ఫంక్షన్‌ను నడపండి, ఆపై కాల్‌ను మరియు దాని ఫలితాన్ని 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\"}"
  }
]

function రకం టూల్స్‌ను మాత్రమే చదువుతారు. shannon-1.6-*, shannon-2-* మరియు shannon-coder-1 లో parameters స్కీమా సాధారణ JSON Schema కీవర్డ్స్‌కు కుదించబడుతుంది: oneOf ను anyOf గా చదువుతారు, మరియు $ref, additionalProperties, const, default, title వంటి కీవర్డ్స్ మోడల్‌కు పంపబడవు.

tool_choice విలువలు required మరియు పేరు పెట్టిన ఫంక్షన్‌ను హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్ అమలు చేస్తాయి.

టూల్ లూప్ పూర్తిగా దాని స్వంత పేజీలో వివరించబడింది. ఫంక్షన్ కాలింగ్

నిర్మిత అవుట్‌పుట్

ఈ ఫార్మాట్ స్ట్రక్చర్డ్ అవుట్‌పుట్‌ను text.format గా రాస్తుంది. స్కీమా నేరుగా format లో, name మరియు strict పక్కన ఉంటుంది; Chat Completions లో లాగా json_schema సభ్యుని కింద ఉండదు.

• {"type": "json_object"} ఏదైనా JSON ఆబ్జెక్ట్‌ను అడుగుతుంది.
• {"type": "json_schema", "name", "schema", "strict"} మీ స్కీమాను అనుసరించే JSON ను అడుగుతుంది. మీరు strict ను వదిలేస్తే అది true.

{
  "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 మెసేజ్‌లోని output_text భాగంలో టెక్స్ట్‌గా వస్తుంది; దాన్ని మీరే పార్స్ చేయండి. స్ట్రక్చర్డ్ అవుట్‌పుట్ లేని హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్ 400 ఇస్తుంది.

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

ఏ మోడల్ ఏ రూపాన్ని తీసుకుంటుందో దాని స్వంత పేజీలో ఉంది. నిర్మిత అవుట్‌పుట్‌లు

రీజనింగ్

రీజనింగ్ చేసే మోడల్ తన రీజనింగ్‌ను reasoning రకం అవుట్‌పుట్ ఐటమ్‌గా, మెసేజ్ కంటే ముందు ఇస్తుంది. స్ట్రీమ్‌లో అది response.reasoning_summary_text.delta ఈవెంట్‌లుగా వస్తుంది.

హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్ reasoning.effort ను అమలు చేస్తాయి: off, low, medium లేదా high; మీరు ఏమీ పంపకపోతే high. off అయితే రీజనింగ్ ఐటమ్ రాదు. దీన్ని ఆబ్జెక్ట్‌గా పంపండి; ఈ ఎండ్‌పాయింట్‌లో కేవలం string ను చదవరు.

ఎఫర్ట్ స్థాయిలు వాటి స్వంత పేజీలో వివరించబడ్డాయి. రీజనింగ్ effort

అవుట్‌పుట్ పరిమితి

మీరు పంపకపోతే max_output_tokens 4,096. రిక్వెస్ట్ ప్రారంభమైనప్పుడు మీ బ్యాలెన్స్ నుండి పక్కన పెట్టే tokens సంఖ్య ఇదే; సమాధానం పూర్తయినప్పుడు, ఆ మొత్తం రిక్వెస్ట్ ఉపయోగించిన దానితో భర్తీ అవుతుంది. మీ మిగిలిన బ్యాలెన్స్‌లో సరిపోని విలువకు 429 Quota exceeded వస్తుంది.

ఇది shannon-1.6-*, shannon-2-* మరియు shannon-coder-1 లో సమాధానం పొడవును, మరియు హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్‌లో సమాధాన టెక్స్ట్ పొడవును పరిమితం చేస్తుంది.

ఈ ఎండ్‌పాయింట్‌లో shannon-coder-1 ఇతర ప్రతి మోడల్ లాగే మీ బ్యాలెన్స్ నుండి tokens లో ఛార్జ్ చేయబడుతుంది.

రిక్వెస్ట్ బాడీ 32 MiB వరకు ఉండవచ్చు. పరిమితులు మరియు బ్యాలెన్స్

ఎరర్‌లు

ఎరర్‌లు OpenAI ఎరర్ బాడీని ఉపయోగిస్తాయి: type మరియు message ఉన్న error ఆబ్జెక్ట్; కొన్నింటిలో null విలువతో code మరియు param కూడా ఉంటాయి. ఈ ఎండ్‌పాయింట్ ఎక్కువగా తిరిగి ఇచ్చేవి పట్టికలో ఉన్నాయి. పూర్తి జాబితా, దేనిని మళ్ళీ ప్రయత్నించాలో అనే వివరంతో, ప్రత్యేక పేజీలో ఉంది. ఎరర్ హ్యాండ్లింగ్