> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # تعليمات دمج واجهة برمجة التطبيقات AI Chat v2 > AI Dialogue 集成指南 - XHuoAPI واجهة برمجة التطبيقات AI Chat v2 (`/aichat2/conversations`) هي الجيل الجديد من واجهات المحادثة، وهي نسخة مطورة بالكامل من [AI Chat API](https://api.xhuoapi.ai/documents/59fb1199-6694-4afb-a222-3554d7f7d05a). تعتمد على بساطة الإصدار v1 وإدارة المحادثات متعددة الجولات، مع التوسعات التالية: * **إدخال متعدد الوسائط**: من خلال حقل `message` المهيكل يمكن إرسال نص + صورة + ملفات مباشرة، دون الحاجة لاستخدام `references` كمرفقات غير مباشرة. * **استدعاء الأدوات بنمط الوكيل (Agent)**: تضم مجموعة أدوات مدمجة للبحث عبر الإنترنت، واستخلاص صفحات الويب، وقراءة الملفات، ويمكن ربط خوادم MCP المصرح بها من المستخدم (مثل Google Drive، Notion، Slack، GitHub)، حيث يمكن للنموذج استدعاء الأدوات ذاتيًا في جولات متعددة ضمن طلب واحد لإتمام مهام معقدة. * **أحداث متدفقة مهيكلة**: عبر `accept: text/event-stream` أو `application/x-ndjson` يمكن الحصول على أحداث مثل `text_delta`، `tool_use`، `tool_result`، `thinking`، `citation`، `card`، `artifact` بشكل متتابع حسب الرموز، مما يسهل العرض في الواجهة الأمامية حسب نوع الحدث. * **قابلية الإيقاف والاستئناف**: عندما يحتاج النموذج لمعلومات إضافية من المستخدم يرسل حدث `ask_user_question` ويتوقف، ويمكن الاستمرار في الطلب التالي بإعادة ملء الإجابات عبر `tool_results`. * **إجراءات CRUD جديدة**: يمكن تنفيذ `retrieve` / `retrieve_batch` / `update` / `delete` عبر نفس نقطة النهاية باستخدام حقل `action`، دون الحاجة لواجهة إدارة جلسات منفصلة. * **قائمة نماذج محدثة باستمرار**: تشمل النماذج الافتراضية GPT-5.4، Claude Opus 4.7، Claude Sonnet 4.6، Gemini 3.1 Pro، GLM 5.1، DeepSeek V4، Kimi K2.5 وغيرها من النماذج المعاصرة. كما أن واجهة الطلب متوافقة تمامًا مع الإصدار v1: فقط إرسال `model` + `question` (+ اختياري `stateful` / `id` / `references` / `preset`) يعيد استجابة JSON `{answer, id}` مكافئة لـ v1، لذلك لا حاجة لإعادة كتابة العميل عند الانتقال من `/aichat/conversations` إلى `/aichat2/conversations`. > إذا كنت تستخدم حاليًا `/aichat/conversations`، ستظل الواجهة القديمة متاحة، ويمكنك الترحيل بوتيرتك الخاصة. ## إجراءات التقديم لاستخدام API، يجب التقديم أولاً عبر صفحة [AI Chat v2 API](https://api.xhuoapi.ai/documents/e4a7c2b9-3f1d-4e8a-9b6c-a5d2f8e1b4c7)، بعد الدخول اضغط زر "Acquire" للحصول على بيانات الاعتماد اللازمة للطلبات. إذا لم تكن مسجلاً أو مسجلاً دخولك، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول، وبعد التسجيل والدخول ستعود تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، ستحصل على رصيد مجاني لاستخدام API. ## الاستخدام الأساسي أسهل طريقة استخدام مماثلة تمامًا لـ v1: إرسال `model` + `question` والحصول على `{answer, id}`. مثال CURL: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "question": "用一句话介绍下 XHuoAPI。" }' ``` الاستجابة: ```json theme={null} { "answer": "XHuoAPI هو منصة API موحدة تجمع نماذج AI السائدة وخدمات الوسائط المتعددة، يمكن للمطورين استدعاء خدمات مثل GPT، Claude، Gemini، Midjourney، Suno، Veo وغيرها باستخدام مفتاح واحد.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` مثال Python: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/aichat2/conversations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "question": "用一句话介绍下 XHuoAPI。", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` نماذج `model` المتاحة يمكن رؤيتها مباشرة في لوحة Try على الجانب الأيمن، الفئات الشائعة تشمل: * OpenAI: `gpt-5.4-mini`، `gpt-5.4-nano`، `gpt-5.2-pro`، `gpt-5.1-all`، `gpt-5-all`، `gpt-4.1`، `gpt-4o`، `gpt-4o-image`، `o3`، `o4-mini` وغيرها * Anthropic: `claude-opus-4-7`، `claude-opus-4-6`، `claude-opus-4-5-20251101`، `claude-sonnet-4-6`، `claude-sonnet-4-5-20250929`، `claude-haiku-4-5-20251001` وغيرها * Google: `gemini-3.1-pro`، `gemini-3.1-pro-preview`، `gemini-3.1-flash-image-preview`، `gemini-3-pro-preview`، `gemini-2.5-flash-lite` وغيرها * xAI: `grok-4`، `grok-4-1-fast`، `grok-4-1-fast-reasoning`، `grok-3-mini-fast` وغيرها * DeepSeek: `deepseek-v4-flash`، `deepseek-v3.2-exp`، `deepseek-r1-0528` وغيرها * Moonshot: `kimi-k2.5`، `kimi-k2-thinking`، `kimi-k2-thinking-turbo` وغيرها * Zhipu: `glm-5.1`، `glm-5`، `glm-5-turbo`، `glm-4.7`، `glm-4.5v` وغيرها يرجى مراجعة بطاقة التسعير في صفحة الخدمة لمعرفة قواعد الفوترة التفصيلية. ## المحادثات متعددة الجولات كما في v1، إرسال `stateful: true` يفعل حفظ الجلسة، وستعيد API معرف `id`؛ في الطلبات التالية ترسل نفس `id` لاستكمال المحادثة دون الحاجة لإدارة تاريخ الرسائل بنفسك. الطلب الأول: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "question": "记住一个数字：42。" }' ``` الاستجابة: ```json theme={null} { "answer": "حسنًا، لقد حفظت الرقم 42. هل تريد مني استخدامه في شيء ما؟", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` الطلب الثاني مع نفس `id`: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "question": "我刚才让你记住的数字是多少？" }' ``` الاستجابة: ```json theme={null} { "answer": "الرقم الذي طلبت مني حفظه هو 42.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > القيمة الافتراضية لـ `stateful` هي `true`، حذفها أو إرسالها صراحة كـ `true` متساويان. إذا كنت لا تريد حفظ المحادثة على الخادم، يمكنك تعيين `stateful: false` صراحة. ## الاستجابة المتدفقة يدعم الإصدار v2 نوعي تدفق حسب رأس `accept`: | السيناريو | `accept` | شكل البيانات | | :----------------------------- | :--------------------------- | :-------------------------------------------------- | | واجهة الويب / EventSource | `text/event-stream` | `data: {json}\n\n`، السطر الأخير `data: [DONE]\n\n` | | الخادم / CLI / تحليل تدفق Node | `application/x-ndjson` | كل سطر كائن JSON مستقل | | بدون تدفق | `application/json` (افتراضي) | استجابة كاملة `{answer, id}` دفعة واحدة | ### مثال NDJSON ```python theme={null} import json import requests url = "https://api.xhuoapi.ai/v1/aichat2/conversations" headers = { "accept": "application/x-ndjson", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "stateful": True, "question": "用三句话介绍杭州。", } with requests.post(url, json=payload, headers=headers, stream=True) as resp: answer = "" for line in resp.iter_lines(): if not line: continue event = json.loads(line) if event.get("type") == "text_delta": # متوافق مع v1: جزء الزيادة متوفر أيضًا في حقل delta_answer answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("usage =", event.get("usage")) ``` كل سطر NDJSON هو حدث مهيكل، الأكثر شيوعًا هو `text_delta`: ```json theme={null} {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} {"type":"text_delta","content":"州","delta_answer":"州","id":"f2f4b3e8-..."} {"type":"text_delta","content":"是","delta_answer":"是","id":"f2f4b3e8-..."} ... {"type":"done","conversation_id":"f2f4b3e8-...","usage":{"prompt_tokens":21,"completion_tokens":58,"total_tokens":79},"terminal_reason":"natural_stop"} ``` ### مثال SSE متصفحات الويب تستخدم `EventSource` التي لا تدعم جسم طلب مخصص، يُنصح باستخدام `fetch` مع تحليل يدوي حسب `\n\n`: ```javascript theme={null} const resp = await fetch("https://api.xhuoapi.ai/v1/aichat2/conversations", { method: "POST", headers: { accept: "text/event-stream", authorization: "Bearer {token}", "content-type": "application/json", }, body: JSON.stringify({ model: "gpt-5.4", stateful: true, question: "用三句话介绍杭州。", }), }); const reader = resp.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; while (true) { const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const blocks = buffer.split("\n\n"); buffer = blocks.pop() ?? ""; for (const block of blocks) { const dataLine = block.split("\n").find((l) => l.startsWith("data: ")); if (!dataLine) continue; const payload = dataLine.slice(6); if (payload === "[DONE]") return; const event = JSON.parse(payload); if (event.type === "text_delta") process.stdout.write(event.content); } } ``` ### أنواع أحداث التدفق | `type` | الوصف | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- | | `text_delta` | جزء نصي متزايد من رد المساعد. `content` هو المحتوى الجديد؛ وللتوافق مع v1، يحتوي الحدث نفسه على `delta_answer` (مطابق لـ `content`) و `id`. | | `thinking` | عملية تفكير النموذج (تظهر فقط إذا كان النموذج المختار يدعم reasoning). | | `tool_use` | النموذج قرر استدعاء أداة، الحدث يحتوي على `tool_id`، `tool_name`، و `input`. | | `tool_result` | نتيجة تنفيذ الأداة، مرتبطة بحدث `tool_use` السابق عبر `tool_id`، و `is_error` تشير إذا حدث خطأ. | | `card` | بطاقة مهيكلة ناتجة عن الأداة (مثل صورة، معاينة رابط)، مناسبة للعرض المباشر. | | `citation` | مصدر URL يرفق لجزء نصي معين كمصدر. | | `ask_user_question` | النموذج يحتاج معلومات إضافية من المستخدم، يدخل الحوار في حالة `awaiting_user_input`، انظر [استئناف المحادثة الموقوفة](#استئناف-المحادثة-الموقوفة). | | `artifact` | ناتج مستقل من النموذج (مثل كود، وثائق)، يمكن حفظه أو تنزيله. | | `system_message` | رسالة نظام (ليست من المستخدم أو المساعد)، للاستخدام في واجهة المستخدم فقط. | | `compact` | حدث لضغط السياق الداخلي، لا يحتاج معالجة خاصة. | | `error` | حدث خطأ في هذه الجولة، `message` يصف الخطأ. | | `done` | نهاية الاستجابة المتدفقة، يحتوي على `usage` (بما في ذلك `prompt_tokens` / `completion_tokens` / `total_tokens`) و `terminal_reason`. | لعملاء يهتمون فقط بالنتيجة النهائية، يمكن تجميع كل `content` من أحداث `text_delta` ليكون مكافئًا لـ `answer` في وضع `application/json`. ## الإدخال متعدد الوسائط إذا كان إدخال المستخدم يحتوي على صور أو ملفات، استخدم `message` (مصفوفة) بدلاً من `question`. كل عنصر في المصفوفة هو كتلة محتوى: ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "这张图片里有几只猫？" }, { "type": "image_url", "image_url": { "url": "https://cdn.xhuoapi.ai/cats.jpg" } } ] } ``` أنواع الكتل المدعومة: * `text` — نص عادي، الحقل الإلزامي `text`. * `image_url` — صورة، الحقل الإلزامي `image_url.url`. * `file_url` — ملف (PDF، CSV، TXT، إلخ)، الحقل الإلزامي `file_url.url`. ### العلاقة مع `references` في v1 للتوافق مع العملاء القدامى، v2 لا تزال تدعم حقل `references: ["https://...", ...]`: * إذا كان امتداد URL من `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`، يتحول تلقائيًا إلى كتلة `image_url`. * الامتدادات الأخرى تتحول إلى كتلة `file_url`. * إذا تم توفير `question` أيضًا، يتم إضافته ككتلة `text` في البداية. لذلك، إذا كنت تريد الترحيل من v1 دون تعديل جسم الطلب، فقط غيّر المسار إلى `/aichat2/conversations` وسيعمل `references` كما هو. للسيطرة الدقيقة (مثلاً وضع عدة صور بين نصوص أو ترتيب معين)، استخدم مصفوفة `message` مباشرة. ## استدعاء الأدوات و MCP أحد التحسينات الأساسية في v2 هو قدرة النموذج على استدعاء الأدوات ذاتيًا لإتمام مهام متعددة الخطوات، **وهو مفعل افتراضيًا**، ولا يحتاج العميل لأي إعداد إضافي في الطلب. السيناريوهات الشائعة: * المستخدم يسأل: "ساعدني في البحث عن المعارض الجديدة في شنغهاي" → النموذج يستدعي أداة البحث على الويب → ينظم النتائج ويرد. * المستخدم يطلب: "اقرأ هذا PDF ثم اكتب ملخصًا" → النموذج يستدعي أداة قراءة الملفات → يكتب الملخص. * المستخدم ربط حساباته في [Connections](https://api.xhuoapi.ai/connections) مثل Google Drive / GitHub / Notion → النموذج يستدعي أدوات MCP المقابلة لقراءة وكتابة البيانات. في تدفقات NDJSON / SSE، تظهر استدعاءات الأدوات عبر أحداث `tool_use` و `tool_result`، مثال: ```json theme={null} {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} {"type":"text_delta","content":"目前","delta_answer":"目前","id":"f2f4b3e8-..."} {"type":"text_delta","content":"上海","delta_answer":"上海","id":"f2f4b3e8-..."} ... ``` إذا كنت لا تريد عرض تفاصيل استدعاء الأدوات في الواجهة، يمكنك تجاهل أحداث `tool_use` / `tool_result` / `card` / `citation`، وسيظل المخرج النهائي للنموذج عبر `text_delta`. يمكن تحديد `max_turns` للحد من عدد جولات استدعاء الأدوات ضمن الطلب، والحد الأقصى الافتراضي تحدده المنصة. تعيين قيمة صغيرة (مثلاً `max_turns: 1`) يجبر الرد على أن يكون مرة واحدة بدون استدعاء أدوات. ## استئناف المحادثة الموقوفة بعض الأدوات قد تجعل النموذج "يسأل المستخدم" لاستكمال المعلومات، حينها يرسل النموذج حدث `ask_user_question` ويتجمد الحوار في حالة `awaiting_user_input`: ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "هل تفضل التقرير باللغة الصينية أم الإنجليزية؟", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` في الواجهة، يتم عرض هذا الحدث كبطاقة للاختيار، ثم ترسل الطلب التالي بنفس `id` مع ملء الإجابة في `tool_results`: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: text/event-stream' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "tool_results": [ { "tool_use_id": "toolu_01XYZW", "output": "中文" } ] }' ``` يجب أن يكون `tool_use_id` في الطلب مطابقًا تمامًا لـ `tool_id` في حالة الإيقاف؛ عدم التطابق يعيد خطأ 400. عند وجود `tool_results` في الطلب، يتم تجاهل `question` / `message` / `references`. إذا قرر المستخدم تخطي السؤال، يمكن إرسال `question` أو `message` جديد، وستعتبر المنصة استدعاء الأداة الموقوفة "تخطي المستخدم". ## إدارة المحادثات (CRUD) v2 توفر إدارة جلسات خفيفة عبر نفس نقطة النهاية باستخدام حقل `action`، دون الحاجة لواجهة API منفصلة. ### `action: retrieve` — استرجاع محادثة واحدة ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" }' ``` تعيد وثيقة المحادثة كاملة (بما في ذلك تاريخ `messages`، `model`، `title`، `tools_used`، وغيرها). ### `action: retrieve_batch` — قائمة ملخصات المحادثات ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` تعيد `{ items: [...], total }`. **الملخصات لا تحتوي على `messages`**، مناسبة لقائمة جانبية؛ عند اختيار محادثة يتم استدعاء `action: retrieve` لاسترجاع تفاصيلها. معايير التصفية الاختيارية: `user_id`، `application_id`، `model_group`، `model`. ### `action: update` — تعديل العنوان أو إعادة كتابة التاريخ ```json theme={null} { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "title": "خطة سفر هانغتشو" } ``` يمكن أيضًا إرسال `messages`، لكن الخادم يقوم بفحص صارم للهيكل (يجب أن يكون في شكل `ToolUseContent` مطوي)، وإلا يعيد خطأ 400. عادة يُنصح باستخدامه فقط لتعديل `title`. ### `action: delete` — حذف محادثة ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` تعيد `{ id, success: true }`. الحذف نهائي ولا يمكن التراجع عنه، يرجى التأكد قبل التنفيذ. ## الترحيل السلس من v1 إذا كنت تستخدم [`/aichat/conversations`](https://api.xhuoapi.ai/documents/59fb1199-6694-4afb-a222-3554d7f7d05a)، الترحيل إلى v2 لا يتطلب تعديل كبير: 1. غيّر عنوان URL من `https://api.xhuoapi.ai/v1/aichat/conversations` إلى `https://api.xhuoapi.ai/v1/aichat2/conversations`. 2. إذا كنت تستخدم أسماء نماذج v1 (مثل `gpt-3.5`، `gpt-4-browsing`)، يُنصح بالترقية إلى نماذج معاصرة في v2 (مثل `gpt-5.4`، `claude-opus-4-7`، `gemini-3.1-pro`). 3. تدفق NDJSON يحتفظ بالتوافق الخلفي: كل حدث `text_delta` لا يزال يحمل `delta_answer` و `id`، لذا لا حاجة لتعديل عملاء تحليل `delta_answer`. بعد الترحيل يمكن تفعيل ميزات v2 الجديدة حسب الحاجة (إدخال متعدد الوسائط `message`، SSE، استدعاء الأدوات، CRUD عبر `action`) تدريجيًا. ## معالجة الأخطاء استجابة الخطأ موحدة: ```json theme={null} { "error": { "code": "chat_error", "message": "upstream LLM returned an error" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` الأخطاء الشائعة: * `400 bad_request`: نقص حقول إلزامية، عدم تطابق `tool_use_id`، بنية `messages` غير صحيحة، إلخ. * `401 invalid_token`: رأس `authorization` غير صحيح. * `404 not_found`: عند `action: retrieve / update / delete`، المعرف `id` غير موجود. * `429 too_many_requests`: تجاوز حد المعدل. * `500 chat_error`: خطأ في LLM الأعلى أو `completion_tokens=0` (يعتبر عدم استهلاك ولا يتم فرض رسوم). في الاستجابات المتدفقة، يتم إرسال الخطأ كحدث `{"type":"error","message":"..."}` يليها انتهاء التدفق. ## الخلاصة واجهة API AI Chat v2 تحافظ على التوافق مع v1، وترتقي بالمحادثات من "سؤال وجواب في جولة واحدة / متعددة" إلى "محادثات قابلة للمراقبة بنمط الوكيل": إدخال متعدد الوسائط، استدعاء أدوات، إمكانية الإيقاف والاستئناف، أحداث متدفقة مهيكلة، وإدارة CRUD مدمجة. نوصي باستخدام v2 مباشرة للمشاريع الجديدة؛ وللمشاريع القائمة يمكن الترحيل تدريجيًا بسلاسة. لأي استفسارات، يرجى التواصل مع فريق الدعم الفني لدينا.