> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # واجهة برمجة تطبيقات AI Chat v2 - تعليمات الدمج > AI Dialogue API guide - Ace Data Cloud واجهة برمجة تطبيقات AI Chat v2 (`/aichat2/conversations`) هي واجهة محادثة من الجيل الجديد، وهي نسخة محدثة بالكامل من [واجهة برمجة تطبيقات AI Chat](https://platform.acedata.cloud/documents/aichat-conversations). لقد توسعت على أساس v1 البسيط، الذي يدعم المحادثات المتعددة، لتشمل: * **إدخال مستخدم متعدد الوسائط**: من خلال حقل `message` المنظم، يمكن إرسال نص + صورة + ملفات مباشرة، دون الحاجة إلى إرفاقها بشكل غير مباشر باستخدام `references`. * **استدعاء أدوات على شكل وكيل**: تحتوي على مجموعة من الأدوات مثل البحث عبر الإنترنت، واستخراج صفحات الويب، وقراءة الملفات، ويمكن ربطها بخادم 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.8، Claude Sonnet 4.6، Gemini 3.1 Pro، GLM 5.1، DeepSeek V4، Kimi K3 وغيرها من النماذج المعاصرة. كما أنها **متوافقة تمامًا مع v1** على مستوى جسم الطلب: يكفي إرسال `model` + `question` (+ `stateful` / `id` / `references` / `preset` الاختيارية) للحصول على استجابة JSON معادلة لـ v1 `{answer, id}`، لذا لا تحتاج إلى إعادة كتابة العميل عند الانتقال من `/aichat/conversations`، يكفي تغيير المسار إلى `/aichat2/conversations`. > إذا كنت تستخدم حاليًا `/aichat/conversations`، ستظل الواجهة القديمة متاحة، ويمكنك الانتقال بالوتيرة التي تناسبك. ## عملية التقديم لاستخدام واجهة برمجة تطبيقات AI Chat v2، يجب أولاً الذهاب إلى [وحدة التحكم في Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا. ![](https://cdn.acedata.cloud/5hmkdg.jpg) إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. **رمز API واحد يكفي لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلبات منفصلة لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [وحدة التحكم](https://platform.acedata.cloud/console/coin). > 📘 الوثائق الكاملة: [واجهة برمجة تطبيقات AI Chat v2 →](https://platform.acedata.cloud/documents/aichat2-conversations) ## الاستخدام الأساسي أبسط طريقة للاستخدام هي نفسها تمامًا كما في v1: أرسل `model` + `question`، واحصل على `{answer, id}`. مثال CURL: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "question": "استخدم جملة واحدة لتعريف AceDataCloud." }' ``` نتيجة العودة: ```json theme={null} { "answer": "AceDataCloud هو منصة موحدة لواجهة برمجة التطبيقات تجمع بين نماذج الذكاء الاصطناعي الرئيسية والخدمات متعددة الوسائط، حيث يمكن للمطورين استدعاء خدمات مثل GPT وClaude وGemini وMidjourney وSuno وVeo باستخدام مفتاح واحد.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` مثال Python: ```python theme={null} import requests url = "https://api.acedata.cloud/aichat2/conversations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "question": "استخدم جملة واحدة لتعريف AceDataCloud.", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` يمكن رؤية القيم المتاحة لـ `model` مباشرة في القائمة المنسدلة في لوحة التجربة على اليمين، وتشمل الفئات الشائعة: * 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-8`، `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`، إلخ. * DeepSeek: `deepseek-v4-flash`، `deepseek-v3.2-exp`، `deepseek-r1-0528`، إلخ. * Moonshot: `kimi-k3`، `kimi-k2.6`، `kimi-k2.5`، إلخ. * Zhipu: `glm-5.1`، `glm-5`، `glm-5-turbo`، `glm-4.7`، `glm-4.5v`، إلخ. يمكن الاطلاع على قواعد التسعير المحددة في بطاقة التسعير على صفحة الخدمة. ## المحادثات المتعددة كما في v1، أرسل `stateful: true` لتمكين حفظ الجلسة، وستعيد واجهة برمجة التطبيقات `id`؛ في الطلبات اللاحقة، يمكنك إحضار `id` للمتابعة في المحادثة، دون الحاجة إلى إدارة تاريخ الرسائل بنفسك. الطلب الأول: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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 ثم اكتب ملخصًا" → يستدعي النموذج file\_read → يكتب الملخص. * المستخدم قد منح إذنًا في [Connections](https://platform.acedata.cloud/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`) يمكنك فرض إجابة واحدة، وعدم السماح بأي استدعاء للأدوات. ## التنفيذ غير المتزامن والتفويض بدون إشراف إذا كان استدعاؤك يأتي من Webhook تنبيه، CI/CD، نظام مراقبة أو مهام خلفية أخرى، يمكنك تعيين `async: true` لجعل الواجهة ترجع على الفور معرف المهمة، وتستمر الخلفية في التنفيذ: ```json theme={null} { "model": "gpt-5.5", "async": true, "question": "خدمتي أصدرت إنذارًا، استخدم WeChat الشخصي لإخطار مجموعة WeChat 'فريق AceDataCloud'..." } ``` مثال على الرد: ```json theme={null} { "task_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "conversation_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "status": "queued" } ``` يمكنك بعد ذلك استخدام `action: retrieve` + `id` للاستعلام عن نتائج المحادثة؛ يمكنك أيضًا تقديم `callback_url`، بعد الانتهاء من المهمة، ستقوم المنصة بإرسال `{ status, answer, usage, error }` عبر POST إلى عنوان رد الاتصال الخاص بك. يجب أن يستخدم `callback_url` `http` / `https`، ولا يمكن كتابة عنوان `localhost` أو عنوان IP خاص بشكل مباشر. عادةً ما لا يمكن لأحد تأكيد المهام الخلفية. إذا كنت ترغب في أن تقوم بعض المهارات أو خادم MCP بتنفيذ إجراءات مثل الإرسال، النشر، الكتابة، وما إلى ذلك في وضع عدم الإشراف، يرجى تضمين قائمة التفويض المسبق بشكل صريح في جسم الطلب: ```json theme={null} { "model": "gpt-5.5", "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "question": "خدمتي أصدرت إنذارًا، استخدم WeChat الشخصي لإخطار مجموعة WeChat 'فريق AceDataCloud'..." } ``` القيم في `allowed_skills` هي slug للمهارات المتصلة؛ والقيم في `allowed_mcp_servers` هي slug لخوادم MCP المتصلة. المهارات / خوادم MCP غير المدرجة في التفويض المسبق ستظل قادرة على المعاينة، أو التشغيل التجريبي، أو رفض تنفيذ عمليات الكتابة في وضع عدم الإشراف. إذا كنت بحاجة إلى تحكم أكثر دقة، يمكنك أيضًا استخدام كائن `unattended_policy` المعادل: ```json theme={null} { "unattended_policy": { "mode": "allow_selected", "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "expires_at": 1790000000 } } ``` ملاحظة: التفويض المسبق يمثل فقط "يسمح لهذه القدرات بتجاوز التأكيد البشري في وضع عدم الإشراف". يجب أن تدعم المهارة المحددة `--unattended-confirm` أو آلية الأمان المقابلة؛ وإلا ستستمر في التشغيل التجريبي، ولن يتم تنفيذ عمليات الكتابة مباشرة. ## استعادة المحادثات المعلقة بعض الأدوات ستجعل النموذج "يسأل المستخدم"، وفي هذه الحالة سيصدر النموذج حدث `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.acedata.cloud/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.acedata.cloud/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://platform.acedata.cloud/documents/aichat-conversations)، فإن الانتقال إلى v2 لا يتطلب تقريبًا أي تعديل على الكود: 1. قم بتغيير عنوان URL من `https://api.acedata.cloud/aichat/conversations` إلى `https://api.acedata.cloud/aichat2/conversations`. 2. إذا كنت قد قمت بتمرير أسماء نماذج v1 (مثل `gpt-3.5`، `gpt-4-browsing`، إلخ)، يُنصح بالترقية إلى النماذج المعاصرة عند الانتقال إلى v2 (مثل `gpt-5.4`، `claude-opus-4-8`، `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": "returned an error from upstream LLM" }, "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":"..."}`، وبعد ذلك ستنتهي التدفق. ## الخاتمة تقوم واجهة برمجة تطبيقات AI Chat v2 بالاحتفاظ بالتوافق مع v1 بينما تقوم بترقية المحادثات من "أسئلة وأجوبة أحادية / متعددة" إلى "محادثات قابلة للملاحظة على شكل وكيل": إدخال متعدد الوسائط، استدعاء الأدوات، إمكانية الإيقاف / الاستئناف، أحداث هيكلية متدفقة، CRUD مدمج. يُنصح باستخدام v2 مباشرة عند الاتصال الجديد؛ يمكن للاندماج القائم على v1 الانتقال بسلاسة على مراحل. إذا كانت لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.