تخطَّ إلى المحتوى
Responses API

Responses API

جديد

يقبل POST /v1/responses تعليمات وقائمة من عناصر الإدخال، ويعيد كائن استجابة مكوَّناً من عناصر مخرجات، بصيغة OpenAI Responses. استخدمه مع واجهة responses في OpenAI SDK ومع الأدوات المبنية عليها، مثل Codex CLI. لا تحتفظ نقطة النهاية بأي حالة: أرسل المحادثة كاملة مع كل طلب.

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

أصغر طلب هو معرّف نموذج ونص. والرد لا يُبث ما لم تطلب ذلك.

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)

الرد كائن استجابة. ويحتوي output فيه على الاستدلال، إن كان النموذج قد استدل، وعلى الرسالة:

200 JSON
{
  "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. ويسمّي العمود يطبّقه النماذج التي يغيّر فيها الحقل الرد. والنماذج المفتوحة الأوزان المستضافة هي المعرّفات الاثنا عشر في قائمة النماذج؛ وعائلة Shannon 3 هي shannon-3 وshannon-3-pro وshannon-3.1 وshannon-3.1-pro. النماذج والأسعار

الحقل النوع الافتراضي الوصف يطبّقه
model string مطلوب. معرّف من قائمة النماذج. المطابقة غير حساسة لحالة الأحرف. والمعرّف المفقود أو غير المنشور يعيد 400 مع unknown model. كل النماذج
input string | array سلسلة نصية تُقرأ كرسالة مستخدم واحدة، أو مصفوفة من عناصر الإدخال. انظر عناصر الإدخال أدناه. كل النماذج
instructions string تعليمات للنموذج، وهي توجيهات النظام (system prompt) في هذه الصيغة. النماذج المفتوحة الأوزان المستضافة، وshannon-1.6-*، وshannon-2-*، وshannon-coder-1
stream boolean false true يرسل الرد كأحداث يرسلها الخادم (server-sent events). انظر البث أدناه. كل النماذج
max_output_tokens integer 4096 الحد الأعلى للرد، بالـ tokens. القيمة خارج المدى من 1 إلى 65,536 تُنقل إلى هذا المدى. وهي أيضاً المقدار الذي يُحجز من رصيدك أثناء تشغيل الطلب. انظر حد المخرجات أدناه. النماذج المفتوحة الأوزان المستضافة، وshannon-1.6-*، وshannon-2-*، وshannon-coder-1
temperature number درجة حرارة أخذ العيّنات. في النماذج المفتوحة الأوزان المستضافة تبقى القيم بين 0 و2. النماذج المفتوحة الأوزان المستضافة؛ وshannon-1.6-* وshannon-2-* وshannon-coder-1 في الردود غير المبثوثة
top_p number أخذ العيّنات بالنواة (nucleus sampling). تبقى القيم بين 0 و1. النماذج المفتوحة الأوزان المستضافة
tools array الدوال التي يجوز للنموذج استدعاؤها، بالشكل المسطح لهذه الصيغة: {"type": "function", "name", "description", "parameters"}. انظر الأدوات أدناه. كل النماذج
tool_choice string | object auto "auto" يترك القرار للنموذج. و"required" يجعله يستدعي أداة. و{"type": "function", "name": "…"} يجعله يستدعي تلك الأداة. النماذج المفتوحة الأوزان المستضافة
reasoning object {"effort": "…"} مع off أو low أو medium أو high. وأي قيمة أخرى تعيد 400. النماذج المفتوحة الأوزان المستضافة
text object {"format": {…}} يطلب إجابة JSON. انظر المخرجات المنظمة أدناه. كل شرائح Shannon؛ والنماذج المفتوحة الأوزان المستضافة كما هو مبيّن لكل معرّف

تُقبل previous_response_id وstore وmetadata وparallel_tool_calls وtruncation وinclude وuser وprompt_cache_key ليعمل كود العميل الحالي دون تغيير. وهي لا تغيّر الرد. ولأن أي محادثة لا تُخزَّن، فإن الطلب اللاحق يحمل الأدوار السابقة في input.

عناصر الإدخال

عنصر الإدخال إما رسالة، بها role وcontent، وإما عنصر مصنَّف يحمل استدعاء أداة أو نتيجته. وcontent سلسلة نصية أو مصفوفة أجزاء.

العنصر الوصف يطبّقه
{"role": "user", "content": …} ما تسأل عنه. content سلسلة نصية، أو أجزاء input_text وinput_image. كل النماذج
{"role": "assistant", "content": …} رد سابق للنموذج. content سلسلة نصية، أو أجزاء output_text. كل النماذج
{"role": "system", "content": …}
{"role": "developer", "content": …}
تعليمات داخل المحادثة. النماذج المفتوحة الأوزان المستضافة
{"type": "function_call", "call_id": "…", "name": "…", "arguments": "…"} استدعاء أداة أجراه النموذج في رد سابق. arguments سلسلة JSON. كل النماذج
{"type": "function_call_output", "call_id": "…", "output": "…"} نتيجة ذلك الاستدعاء. call_id هو معرّف الاستدعاء وoutput النتيجة كسلسلة نصية. كل النماذج

ضع التعليمات في الحقل instructions. ومع معرّف من عائلة Shannon 3، ضع التعليمات التي يجب التقيد بها في رسالة user.

يمكن إعادة عناصر output في الرد إلى input كما هي: تُقرأ عناصر message وfunction_call، وتُتخطى عناصر reasoning.

أجزاء المحتوى

الجزء الوصف متاح في
{"type": "input_text", "text": "…"} نص رسالة المستخدم. كل النماذج
{"type": "output_text", "text": "…"} نص رسالة المساعد. كل النماذج
{"type": "input_image", "image_url": "…"} صورة، كعنوان data: URL بمحتوى base64 أو كعنوان http(s) URL. عائلة Shannon 3، وshannon-1.6-lite، وshannon-1.6-pro، والنماذج المفتوحة الأوزان المستضافة التي تذكر مدخلات الصور
{"type": "input_file", "file_data": "data:application/pdf;base64,…"} مستند (PDF أو Word أو PowerPoint أو Excel): يحمل file_data عنوان data: URL، أو يحمل file_url عنوان http(s) URL. عائلة Shannon 3

في شرائح Shannon تُقرأ الصور والملفات من آخر عنصر user في input. وللأحجام والحدود صفحتها الخاصة. الصور والملفات

طلب مع تعليمات وخيارات

يرسل هذا الطلب تعليمات، ومحادثة كعناصر إدخال، وحداً للمخرجات، ودرجة حرارة، وجهد استدلال. ويستخدم نموذجاً مفتوح الأوزان مستضافاً، يطبّق كل ذلك.

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)

في رد النموذج المفتوح الأوزان المستضاف الحقول id وobject وmodel وcreated_at وstatus وoutput وusage. ويضيف usage فيه الـ tokens المقروءة من الذاكرة المؤقتة والـ tokens المنفقة على الاستدلال:

200 JSON
{
  "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 موجودة في كل رد. ابنِ كودك عليها.

الحقل النوع الوصف يرسله
id string resp_ متبوعاً بـ 32 رمزاً سداسياً عشرياً. كل النماذج
object string دائماً response. كل النماذج
status string completed. وفي البث تكون in_progress أولاً، وfailed في حدث response.failed. كل النماذج
output array عناصر المخرجات بالترتيب الذي أنتجها به النموذج: reasoning وmessage وfunction_call. كل النماذج
usage object input_tokens وoutput_tokens وtotal_tokens. كل النماذج
usage.input_tokens_details object cached_tokens: tokens المدخلات المقروءة من ذاكرة المطالبات المؤقتة. النماذج المفتوحة الأوزان المستضافة
usage.output_tokens_details object reasoning_tokens: tokens المخرجات المنفقة على الاستدلال. النماذج المفتوحة الأوزان المستضافة
model string المعرّف الأساسي للنموذج الذي أجاب. عائلة Shannon 3، والنماذج المفتوحة الأوزان المستضافة
created_at integer وقت الرد، بثواني Unix. عائلة Shannon 3، والنماذج المفتوحة الأوزان المستضافة
instructions, tools, temperature, … تكرر instructions وtools وtemperature ما في الطلب. وقيمتا error وincomplete_details هما null، وmetadata هي {}، وparallel_tool_calls هي true، وtool_choice هي auto، وtop_p هي null. عائلة Shannon 3

عناصر المخرجات

العنصر الوصف
{"id": "rs_…", "type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} استدلال النموذج كجزء summary_text واحد. يوجد فقط عندما يكون النموذج قد استدل.
{"id": "msg_…", "type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "…"}]} الإجابة: جزء output_text واحد فيه النص.
{"id": "fc_…", "type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"} استدعاء أداة. arguments سلسلة JSON. أعد النتيجة مع call_id نفسه.

تجمع OpenAI SDKs نص الرسالة نيابة عنك في response.output_text.

البث

اضبط stream على true للحصول على أحداث يرسلها الخادم (server-sent events). لكل إطار سطر event: فيه اسم الحدث وسطر data: فيه كائن JSON؛ ويكرر الكائن الاسم في 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")

تصل الأحداث بهذا الترتيب. ولا تظهر مجموعات الاستدلال والرسالة واستدعاءات الأدوات إلا عندما يحتويها الرد.

الحدث الحمولة متى
response.created response دائماً الأول. قيمة response.status هي in_progress وresponse.output فارغ.
response.in_progress response دائماً الثاني، مع الكائن نفسه.
response.output_item.added output_index, item يبدأ الاستدلال: عنصر reasoning مع summary فارغ.
response.reasoning_summary_text.delta output_index, summary_index, delta قطعة من الاستدلال.
response.reasoning_summary_text.done output_index, summary_index, text اكتمل الاستدلال: text كاملاً.
response.output_item.done output_index, item عنصر reasoning المكتمل.
response.output_item.added output_index, item تبدأ الإجابة: عنصر message بالحالة in_progress ودون محتوى.
response.content_part.added output_index, content_index, part يُفتح جزء output_text فارغ.
response.output_text.delta output_index, content_index, delta قطعة من الإجابة.
response.output_text.done output_index, content_index, text اكتملت الإجابة: text كاملاً.
response.content_part.done output_index, content_index, part جزء output_text المكتمل.
response.output_item.done output_index, item عنصر message المكتمل، بالحالة completed.
response.output_item.added output_index, item يبدأ استدعاء أداة: عنصر function_call فيه call_id وname وarguments فارغة.
response.function_call_arguments.delta output_index, delta وسائط الاستدعاء، كاملة في دلتا واحدة.
response.function_call_arguments.done output_index, arguments الوسائط نفسها، في arguments.
response.output_item.done output_index, item عنصر function_call المكتمل.
response.completed response دائماً الأخير عند النجاح: كائن الاستجابة كاملاً مع output وusage.
200 text/event-stream
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.failed بدلاً من response.completed. وقيمة 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:

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

حقل output في رد يستدعيها:

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

شغّل الدالة، ثم أعد إرسال الطلب مع إضافة الاستدعاء ونتيجته إلى input:

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 عند إهماله.
POST /v1/responses
{
  "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.

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

أي نموذج يقبل أي شكل مبيّن في صفحته الخاصة. مخرجات منظمة

الاستدلال

النموذج الذي يستدل يعيد استدلاله كعنصر مخرجات من النوع reasoning، قبل الرسالة. وفي البث يصل كأحداث response.reasoning_summary_text.delta.

تطبّق النماذج المفتوحة الأوزان المستضافة reasoning.effort: ‏off أو low أو medium أو high، مع high عندما لا ترسل شيئاً. ولا يعيد off عنصر استدلال. أرسله ككائن؛ فالسلسلة المجردة لا تُقرأ على نقطة النهاية هذه.

مستويات الجهد موصوفة في صفحتها الخاصة. جهد الاستدلال

حد المخرجات

قيمة max_output_tokens هي 4,096 عند عدم إرساله. وهو عدد الـ tokens المحجوزة من رصيدك عند بدء الطلب؛ وعند اكتمال الرد يُستبدل هذا المقدار بما استخدمه الطلب. والقيمة التي لا تتسع في رصيدك المتبقي تعيد 429 Quota exceeded.

يحدّ من طول الرد في shannon-1.6-* وshannon-2-* وshannon-coder-1، ومن طول نص الإجابة في النماذج المفتوحة الأوزان المستضافة.

على نقطة النهاية هذه يُحاسَب shannon-coder-1 بالـ tokens من رصيدك، مثل كل نموذج آخر.

يمكن أن يبلغ نص الطلب 32 MiB. الحدود والرصيد

الأخطاء

تستخدم الأخطاء نص الخطأ في OpenAI: كائن error فيه type وmessage؛ وبعضها يحمل أيضاً code وparam بالقيمة null. يسرد الجدول ما تعيده نقطة النهاية هذه في أغلب الأحيان. أما القائمة الكاملة، مع ما ينبغي إعادة محاولته، فلها صفحتها الخاصة. معالجة الأخطاء

الحالة النوع الرسالة متى
401 authentication_error Missing authentication
Invalid API key
لم يُرسل مفتاح API، أو أن المفتاح غير معروف أو ملغى.
400 invalid_request_error unknown model: <id> model مفقود أو ليس معرّفاً منشوراً.
400 invalid_request_error No user message provided. شرائح Shannon: لا يحتوي input على نص من المستخدم.
400 invalid_request_error <id> does not accept image input أُرسلت صورة إلى نموذج مفتوح الأوزان مستضاف لا يقبل مدخلات الصور.
400 invalid_request_error <id> does not accept response_format أُرسل text.format إلى نموذج مفتوح الأوزان مستضاف لا يدعم المخرجات المنظمة.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high reasoning.effort يحمل قيمة خارج القائمة.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … النص JSON صالح لكن نوع أحد الحقول خاطئ.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_output_tokens أكبر مما تبقى من رصيدك.
429 rate_limit_error Too many requests. Retry in <n>s. الحماية من الإغراق: أكثر من 120 طلباً في دقيقة واحدة على حسابك.
500 api_error The model backend failed to answer. Please retry. لم ينتج النموذج رداً. أعد إرسال الطلب.
502 api_error The model backend failed to answer. Please retry. الشيء نفسه، في النماذج المفتوحة الأوزان المستضافة.
504 api_error upstream timed out استغرق نموذج مفتوح الأوزان مستضاف وقتاً أطول من الحد الزمني للرد غير المبثوث. أرسله مع ضبط stream على true.