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

उत्तर एक रिस्पॉन्स ऑब्जेक्ट है। उसके 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 चाहिए। Applied by कॉलम उन मॉडल के नाम बताता है जिन पर कोई फ़ील्ड उत्तर बदलता है। होस्टेड ओपन-वेट मॉडल मॉडल सूची के बारह id हैं; 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 में ले जाता है।

इनपुट आइटम

इनपुट आइटम या तो role और content वाला संदेश होता है, या टाइप किया हुआ आइटम जो टूल कॉल या उसका परिणाम ले जाता है। content एक स्ट्रिंग या भागों का ऐरे है।

निर्देश instructions फ़ील्ड में रखें। Shannon 3 परिवार के id के साथ, जो निर्देश ज़रूर माने जाने चाहिए उन्हें user संदेश में रखें।

उत्तर के output के आइटम जैसे हैं वैसे input में वापस जा सकते हैं: message और function_call आइटम पढ़े जाते हैं, reasoning आइटम छोड़ दिए जाते हैं।

कंटेंट भाग

Shannon टियर पर इमेज और फ़ाइलें input के आख़िरी user आइटम से पढ़ी जाती हैं। आकार और सीमाओं का अपना पेज है। इमेज और फ़ाइलें

निर्देशों और विकल्पों वाला अनुरोध

यह अनुरोध निर्देश, इनपुट आइटम के रूप में बातचीत, आउटपुट सीमा, तापमान और रीज़निंग effort भेजता है। यह होस्टेड ओपन-वेट मॉडल इस्तेमाल करता है, जो इन सबको लागू करता है।

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 कैश से पढ़े गए टोकन और रीज़निंग पर खर्च हुए टोकन जोड़ता है:

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

रिस्पॉन्स ऑब्जेक्ट

id, object, status, output और usage हर उत्तर में होते हैं। अपना कोड इन्हीं पर बनाएँ।

आउटपुट आइटम

OpenAI SDK संदेश का टेक्स्ट आपके लिए response.output_text में जोड़ देते हैं।

स्ट्रीमिंग

सर्वर-सेंट इवेंट के लिए 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 में बताएँ; जब मॉडल उसे चाहता है, तो उत्तर में संदेश की जगह, या उसके साथ, 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 कोई रीज़निंग आइटम नहीं लौटाता। इसे ऑब्जेक्ट के रूप में भेजें; इस endpoint पर सीधी स्ट्रिंग नहीं पढ़ी जाती।

effort का वर्णन उनके अपने पेज पर है। रीज़निंग effort

आउटपुट सीमा

न भेजने पर max_output_tokens 4,096 होता है। अनुरोध शुरू होते समय यही संख्या आपके बैलेंस से अलग रखी जाती है; उत्तर पूरा होने पर उस राशि की जगह वह आ जाता है जो अनुरोध ने इस्तेमाल किया। जो मान आपके बचे बैलेंस में नहीं समाता वह 429 Quota exceeded लौटाता है।

यह shannon-1.6-*, shannon-2-* और shannon-coder-1 पर उत्तर की लंबाई को सीमित करता है, और होस्टेड ओपन-वेट मॉडल पर उत्तर के टेक्स्ट की लंबाई को।

इस endpoint पर shannon-coder-1 का शुल्क आपके बैलेंस से टोकन में लगता है, हर दूसरे मॉडल की तरह।

अनुरोध की बॉडी 32 MiB तक हो सकती है। सीमाएँ और बैलेंस

एरर

एरर OpenAI की एरर बॉडी इस्तेमाल करते हैं: type और message वाला error ऑब्जेक्ट; कुछ में code और param भी होते हैं, जिनका मान null है। तालिका वह बताती है जो यह endpoint सबसे ज़्यादा लौटाता है। पूरी सूची, और क्या दोबारा आज़माना है, उसका अपना पेज है। त्रुटि प्रबंधन