الانتقال إلى المحتوى الرئيسي
POST
إنشاء استجابة

استخدم أدوات الخادم

أضف أداة phaseo: إلى tools بجانب أدوات الدوال الخاصة بك، وسيشغّلها Phaseo عندما يستدعيها النموذج. تقبل /v1/responses كل أدوات الخادم، بما فيها phaseo:apply_patch التي لا تدعمها إلا نقطة النهاية هذه؛ ويسردها دليل أدوات الخادم.
يُحتسب كل استدعاء لأداة خادم في usage.server_tool_use: لا يزال النوع الأقدم gateway:datetime يعمل. مع stream: true، يشغّل Phaseo أدوار الأدوات بنفسه، ثم يبث إليك الإجابة المستكملة في بث واحد.

الاستدلال في حلقات الأدوات

على OpenAI وAzure OpenAI وxAI، يرسل Phaseo طلبات Responses إلى المزوّد مع store: false، لذا لا يستمر استدلال النموذج بين خطوات حلقة الأدوات إلا عبر عناصر الإخراج reasoning. لكل عنصر reasoning الحقول id وsummary وcontent. عندما يُرجع المزوّد حالة استدلال، يتضمن العنصر أيضًا encrypted_content، الذي يحتوي واحدًا مما يلي:
  • الاستدلال المشفّر في OpenAI وAzure OpenAI وxAI. يطلبه Phaseo باستخدام include: ["reasoning.encrypted_content"] لنماذج الاستدلال.
  • تواقيع التفكير والتفكير المحجوب في Claude.
  • تواقيع الأفكار في Gemini، بما في ذلك عنصر reasoning منفصل يوضع مباشرة قبل استدعاء الدالة الذي ينتمي إليه التوقيع.
  • مستوى الجهد الذي عمل به رد Claude، في آخر عنصر reasoning من المخرجات، وهو عنصر لا يحتوي على نص.
تحمل الاستجابات المتدفقة العناصر نفسها في response.output_item.done وresponse.completed.
أعد إرسال كل عناصر الإخراج في input دون تغيير في كل طلب، وليس في حلقات الأدوات فقط. لا تُسقط عناصر reasoning أو تعدّلها أو تغيّر ترتيبها أبدًا، سواء احتوت على encrypted_content أم لا، بما في ذلك العناصر التي لا تحتوي على نص.
encrypted_content معتم، ويسجّل المزوّد والنموذج اللذين أنتجاه. لا يرسله Phaseo إلا إلى عائلة المزوّد تلك والنموذج نفسه، لذا فإن الرجوع إلى مزوّد آخر يُسقطه بدلًا من أن يفشل. ومن دونه، يفقد Claude استدلاله بين خطوات حلقة الأدوات، ويؤدي تغيير reasoning.effort إلى إعادة تشغيل ذاكرة Claude المؤقتة للموجّهات؛ راجع غيّر جهد الاستدلال في منتصف المحادثة.

التفويضات

Authorization
string
header
مطلوب

المصادقة باستخدام رمز Bearer

الجسم

application/json

يُعامَل أي حقل اختياري في المستوى الأعلى يُرسَل بالقيمة null على أنه غير مضبوط، تمامًا كما لو حُذف.

model
string
مطلوب
input
مطلوب
models
string[]

نماذج احتياطية اختيارية ومرتبة تُجرَّب بعد model. الحقل model مطلوب وهو دائمًا النموذج الأساسي. عندما تفشل محاولة بالرمز 429 أو 500 أو 502 أو 503 أو 504، تُجرَّب الإدخالة التالية؛ وتُعاد الأخطاء الأخرى دون تغيير. يقبل ما يصل إلى 25 معرّف نموذج أو إعدادًا مسبقًا؛ وتُتجاهل الإدخالات المكررة والإدخالات المطابقة لـ model. يُتحقق من كل محاولة وتُسجَّل وتُحتسب تكلفتها كطلب مستقل، ويعرض الحقل model في الاستجابة وتتبّع التوجيه النموذج الذي خدم الطلب. لا تنتقل طلبات البث إلى نموذج احتياطي إلا قبل إرسال البايت الأول، ولا تنتقل مهام الفيديو والموسيقى إلا عند الإرسال. ترفض طلبات batch وrealtime وcouncil الحقل models. تكون الأولوية للنماذج الاحتياطية المحددة في مسار ديناميكي، ولا يمكن الجمع بين phaseo/auto وmodels.

Required array length: 1 - 25 elements
Minimum string length: 1
مثال:
prompt
object

يملأ قالب الموجّه المحفوظ في إعداد مسبق. اترك model أو اضبطه على المرجع نفسه، وأرسل محادثة فارغة أو الأدوار التي تُضاف بعد القالب.

background
boolean
include
string[]
instructions
string
max_output_tokens
integer
النطاق المطلوب: x >= 1
metadata
object
session_id
string

معرّف فريد لتجميع الطلبات المرتبطة (مثل محادثة أو سير عمل وكيل) لأغراض قابلية المراقبة.

Maximum string length: 256
parallel_tool_calls
boolean
previous_response_id
string

غير مدعوم. لا تخزّن Phaseo الردود، لذا تعيد الطلبات التي تحدد previous_response_id أو conversation الخطأ 400 unsupported_param. أرسل المحادثة كاملة في input.

reasoning
object
service_tier
enum<string> | null

يحدد مستوى توجيه أو تسعير مدعومًا. القيمة auto (أو null) لا تطلب مستوى بعينه، ويُوجَّه الطلب ويُفوتر كما لو لم يُضبط الحقل؛ وتُعامَل scale على أنها default، أي المستوى القياسي.

الخيارات المتاحة:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
scale
store
boolean
stream
boolean
temperature
number
النطاق المطلوب: 0 <= x <= 2
text
object
plugins
object[]

إضافات البوابة لهذا الطلب. تضيف web البحث على الويب وتضيف web-fetch قراءة الصفحات إلى أي نموذج، وتصلح response-healing ملفات JSON المشوّهة في الاستجابات المنظّمة غير المتدفقة. تُدمج الإعدادات الافتراضية لمساحة العمل والإعداد المسبق مع هذه القائمة. يعيد معرّف إضافة غير معروف الخطأ 400 unknown_gateway_plugin.

تضيف أداة الخادم phaseo:web_search إلى الطلب، ليتمكن أي نموذج من البحث على الويب. يعمل الطلب، وتُحتسب عمليات البحث وتُفوتر، تمامًا كما مع أداة phaseo:web_search. إذا كان الطلب يتضمن أداة بحث على الويب بالفعل، فلا تضيف الإضافة شيئًا. تُتجاهل الخيارات الأخرى.

tool_choice

استراتيجية اختيار الأدوات. تُقبل أنواع أدوات خادم Phaseo وتُحوّل إلى أهداف وظائف أو أدوات لدى المزوّد upstream. يُرسل كائن allowed_tools كما هو إلى OpenAI مع جميع الأدوات. ولا يتلقى المزوّدون الآخرون إلا الأدوات المسموح بها ووضعه (auto أو required)، أو استدعاءً إلزاميًا للأداة عندما يسمح required بأداة واحدة فقط. إذا أدرج allowed_tools أداة لا تعرّفها tools، فلا يمكن إلا لـ OpenAI معالجة الطلب؛ وإلا يُعاد خطأ 400.

الخيارات المتاحة:
auto,
none,
required,
phaseo:datetime,
phaseo:web_search,
phaseo:web_fetch,
phaseo:subagent,
phaseo:fusion,
phaseo:search_models,
gateway:datetime,
gateway:web_search,
gateway:web_fetch
tools
object[]

تعريفات الأدوات لاستدعاءات وظائف النماذج وأدوات خادم البوابة. أدوات خادم البوابة المدمجة هي gateway:datetime وgateway:web_search وgateway:web_fetch.

top_p
number
النطاق المطلوب: 0 <= x <= 1
truncation
enum<string>
الخيارات المتاحة:
auto,
disabled
user
string
prompt_cache_key
string | null

يجمع الطلبات المرتبطة لتبقى لدى المزوّد الذي يحتفظ بذاكرة المطالبات المؤقتة الخاصة بها. ترسل Phaseo إلى المزوّد تجزئة لمساحة العمل وهذا المفتاح، وليس المفتاح الخام أبدًا.

prompt_cache_retention
enum<string>

مدة الاحتفاظ بذاكرة المطالبات المؤقتة لنماذج OpenAI وAzure OpenAI السابقة لـ GPT-5.6. تتقدّم على provider_options.openai.prompt_cache_retention.

الخيارات المتاحة:
in_memory,
24h
prompt_cache_options
object

وضع ذاكرة المطالبات المؤقتة ومدة صلاحيتها لـ OpenAI وAzure OpenAI بدءًا من GPT-5.6 (ttl 30m، أو 12h في OpenAI) ولـ DeepInfra (ttl 5m أو 1h). يُحذف للمزوّدين الآخرين.

cache_control
object

التحكم في ذاكرة المطالبات المؤقتة. استخدم type ephemeral مع ttl اختياري قيمته 5m أو 1h. ولا ينطبق scope إلا على سياسة تخزين مؤقت لـ Claude على المستوى الأعلى. تخزّن Amazon Bedrock وGoogle Vertex AI نماذج Claude 3.7 Sonnet و3.5 Sonnet و3 Opus مؤقتًا لمدة 5 دقائق فقط؛ وهناك يُحذف ttl، ويُبلَغ عن قيمة 1h المحذوفة في X-Phaseo-Dropped-Params باسم cache_control.ttl.

safety_identifier
string | null
modalities
enum<string>[]
الخيارات المتاحة:
text,
image,
audio
image_config
object
provider_options
object

خيارات خاصة بالمزوّد، اختيارية.

usage
boolean
meta
boolean
echo_upstream_request
boolean
debug
object

عناصر تحكم تصحيح أخطاء البوابة. لا تُمرر هذه العلامات إلى المزوّد مطلقًا.

provider
object

تفضيلات توجيه المزوّد لاختياره عبر البوابة.

الاستجابة

استجابة

id
string
object
string
created
integer
model
string
provider
string
provider_id
string
nativeResponseId
string | null
status
enum<string>
الخيارات المتاحة:
completed,
failed,
incomplete
finish_reason
string | null
meta
object
cost_nanos
number
cost_cents
integer
currency
string
pricing_lines
object[]
output
object[]
output_items
object[]
content
object[]
role
string
stop_reason
string
type
string
usage
object
آخر تعديل في ١٢ نوفمبر ٢٠٢٦