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 میں reasoning، اگر ماڈل نے کی ہو، اور پیغام ہوتے ہیں:

{
  "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 میں لے کر آتی ہے۔

ان پٹ آئٹمز

ان پٹ آئٹم یا تو پیغام ہے، role اور content کے ساتھ، یا ٹائپ والا آئٹم جو ٹول کال یا اس کا نتیجہ رکھتا ہے۔ content سٹرنگ ہے یا حصوں کی ارے۔

ہدایات instructions فیلڈ میں رکھیں۔ Shannon 3 فیملی کے id کے ساتھ، جو ہدایات لازماً مانی جانی ہوں انہیں user پیغام میں رکھیں۔

جواب کے output کے آئٹمز جوں کے توں input میں واپس جا سکتے ہیں: message اور function_call آئٹمز پڑھے جاتے ہیں، reasoning آئٹمز چھوڑ دیے جاتے ہیں۔

مواد کے حصے

Shannon درجوں پر تصاویر اور فائلیں input کے آخری user آئٹم سے پڑھی جاتی ہیں۔ سائز اور حدود کا اپنا صفحہ ہے۔ تصاویر اور فائلیں

ہدایات اور آپشنز والی درخواست

یہ درخواست ہدایات، ان پٹ آئٹمز کی صورت میں گفتگو، آؤٹ پٹ کی حد، ٹمپریچر اور reasoning 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 کیش سے پڑھے گئے ٹوکنز اور reasoning پر خرچ ہونے والے ٹوکنز بھی بتاتا ہے:

{
  "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 SDKs پیغام کا متن آپ کے لیے 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
  }'

ایونٹس اس ترتیب میں آتے ہیں۔ reasoning، پیغام اور ٹول کالز کے گروپ صرف تب نظر آتے ہیں جب جواب میں وہ ہوں۔

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 ہوتا ہے۔

ہوسٹڈ اوپن ویٹ ماڈلز پر ناکامی error ایونٹ ہوتی ہے جس میں code کی قدر api_error اور ایک message ہوتا ہے۔ 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 کے ساتھ ہوتی ہے، json_schema رکن کے نیچے نہیں جیسا Chat Completions میں ہوتا ہے۔

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

reasoning کرنے والا ماڈل اپنی reasoning کو type reasoning کے آؤٹ پٹ آئٹم کے طور پر، پیغام سے پہلے، لوٹاتا ہے۔ سٹریم میں یہ response.reasoning_summary_text.delta ایونٹس کے طور پر آتی ہے۔

ہوسٹڈ اوپن ویٹ ماڈلز reasoning.effort لاگو کرتے ہیں: off، low، medium یا high، اور اگر آپ کچھ نہ بھیجیں تو high۔ off کوئی reasoning آئٹم نہیں لوٹاتا۔ اسے آبجیکٹ کے طور پر بھیجیں؛ اس endpoint پر سادہ سٹرنگ نہیں پڑھی جاتی۔

efforts کی وضاحت ان کے اپنے صفحے پر ہے۔ Reasoning 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 سب سے زیادہ لوٹاتا ہے۔ مکمل فہرست، اور کن پر دوبارہ کوشش کرنی ہے، اس کا اپنا صفحہ ہے۔ غلطیاں