Responses API

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

کوچک‌ترین درخواست یک شناسه مدل و یک متن است. پاسخ stream نمی‌شود مگر اینکه آن را بخواهید.

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 چیزهایی هستند که یک درخواست لازم دارد. ستون اعمال‌شده توسط مدل‌هایی را نام می‌برد که یک فیلد روی آن‌ها پاسخ را تغییر می‌دهد. مدل‌های open-weight میزبانی‌شده دوازده شناسه فهرست مدل‌ها هستند؛ خانواده 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، دستورالعمل‌هایی را که باید رعایت شوند در پیام user بگذارید.

آیتم‌های output یک پاسخ را می‌توان همان‌طور که هستند به input برگرداند: آیتم‌های message و function_call خوانده می‌شوند و آیتم‌های reasoning نادیده گرفته می‌شوند.

بخش‌های محتوا

در سطوح Shannon، تصاویر و فایل‌ها از آخرین آیتم user در input خوانده می‌شوند. اندازه‌ها و محدودیت‌ها صفحه خودشان را دارند. تصاویر و فایل‌ها

درخواست با دستورالعمل‌ها و گزینه‌ها

این درخواست دستورالعمل‌ها، یک گفتگو به‌صورت آیتم‌های ورودی، حد خروجی، temperature و میزان تلاش استدلال را می‌فرستد. از یک مدل open-weight میزبانی‌شده استفاده می‌کند که همه آن‌ها را اعمال می‌کند.

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

پاسخ مدل open-weight میزبانی‌شده 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 در هر پاسخ هستند. کد خود را روی آن‌ها بسازید.

آیتم‌های خروجی

SDKهای OpenAI متن پیام را برای شما در response.output_text به هم می‌چسبانند.

Streaming

برای server-sent events مقدار stream را true بگذارید. هر فریم یک خط event: با نام رویداد و یک خط data: با یک شیء JSON دارد؛ شیء نام را در type تکرار می‌کند. deltaها را با output_index به آیتمشان وصل کنید.

با SDK مربوط به OpenAI، رویدادها را از روی 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}, …}}

streamی که با خطا مواجه می‌شود

در سطوح Shannon، پاسخ ناموفق به‌جای response.completed با response.failed پایان می‌یابد. response.status آن failed است و response.error یک code، rate_limit_exceeded یا server_error، و یک message دارد.

در مدل‌های open-weight میزبانی‌شده، شکست یک رویداد error با code برابر api_error و یک message است. response.completed همچنان بعد از آن می‌آید.

stream را وقتی ناموفق در نظر بگیرید که 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 schema مربوط به parameters به کلیدواژه‌های مشترک JSON Schema کاهش می‌یابد: oneOf مانند anyOf خوانده می‌شود و کلیدواژه‌هایی مانند $ref، additionalProperties، const، default و title به مدل داده نمی‌شوند.

مقادیر required و تابع نام‌برده برای tool_choice را مدل‌های open-weight میزبانی‌شده اعمال می‌کنند.

حلقه ابزار به‌طور کامل در صفحه خودش توضیح داده شده است. فراخوانی توابع

خروجی ساختاریافته

این فرمت خروجی ساختاریافته را به شکل text.format می‌نویسد. schema مستقیماً در format، کنار name و strict، قرار می‌گیرد، نه زیر عضو json_schema مانند Chat Completions.

• {"type": "json_object"} هر شیء JSON را می‌خواهد.
• {"type": "json_schema", "name", "schema", "strict"} JSONای را می‌خواهد که از schema شما پیروی کند. 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 پیام می‌رسد؛ خودتان آن را parse کنید. مدل open-weight میزبانی‌شده بدون خروجی ساختاریافته 400 برمی‌گرداند.

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

اینکه کدام مدل کدام شکل را می‌پذیرد در صفحه خودش فهرست شده است. خروجی‌های ساختاریافته

استدلال

مدلی که استدلال می‌کند استدلال خود را به‌صورت یک آیتم خروجی از نوع reasoning پیش از پیام برمی‌گرداند. در stream به‌صورت رویدادهای response.reasoning_summary_text.delta می‌رسد.

مدل‌های open-weight میزبانی‌شده reasoning.effort را اعمال می‌کنند: off، low، medium یا high، و وقتی چیزی نفرستید high. off هیچ آیتم استدلالی برنمی‌گرداند. آن را به‌صورت شیء بفرستید؛ رشته ساده در این endpoint خوانده نمی‌شود.

میزان‌های تلاش در صفحه خودشان توضیح داده شده‌اند. میزان تلاش استدلال

حد خروجی

max_output_tokens وقتی آن را نفرستید 4,096 است. تعداد توکن‌هایی است که هنگام شروع درخواست از موجودی شما کنار گذاشته می‌شود؛ وقتی پاسخ کامل شود، این مقدار با آنچه درخواست مصرف کرده جایگزین می‌شود. مقداری که در موجودی باقی‌مانده شما جا نشود 429 Quota exceeded برمی‌گرداند.

طول پاسخ را روی shannon-1.6-*، shannon-2-* و shannon-coder-1 و طول متن پاسخ را روی مدل‌های open-weight میزبانی‌شده محدود می‌کند.

روی این endpoint، shannon-coder-1 مثل هر مدل دیگر بر حسب توکن از موجودی شما محاسبه می‌شود.

بدنه درخواست می‌تواند تا 32 MiB باشد. محدودیت‌ها و موجودی

خطاها

خطاها از بدنه خطای OpenAI استفاده می‌کنند: یک شیء error با type و message؛ برخی code و param را هم با مقدار null دارند. جدول رایج‌ترین مواردی را که این endpoint برمی‌گرداند فهرست می‌کند. فهرست کامل، همراه با اینکه کدام را دوباره امتحان کنید، صفحه خودش را دارد. مدیریت خطا