واجهة برمجة تطبيقات AI Chat v2 - تعليمات الدمج

واجهة برمجة تطبيقات AI Chat v2 (/aichat2/conversations) هي واجهة محادثة من الجيل الجديد، وهي نسخة محدثة بالكامل من واجهة برمجة تطبيقات AI Chat. لقد توسعت على أساس 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 للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. رمز API واحد يكفي لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلبات منفصلة لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.

📘 الوثائق الكاملة: واجهة برمجة تطبيقات AI Chat v2 →

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

أبسط طريقة للاستخدام هي نفسها تمامًا كما في v1: أرسل model + question، واحصل على {answer, id}. مثال CURL:

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

نتيجة العودة:

{
  "answer": "AceDataCloud هو منصة API موحدة تجمع بين نماذج الذكاء الاصطناعي الرئيسية والخدمات متعددة الوسائط، حيث يمكن للمطورين استدعاء خدمات مثل GPT وClaude وGemini وMidjourney وSuno وVeo باستخدام مفتاح واحد.",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

مثال Python:

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 للمتابعة في المحادثة، دون الحاجة للحفاظ على تاريخ الرسائل بنفسك. الطلب الأول:

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

العودة:

{
  "answer": "حسنًا، لقد تذكرت 42. ماذا تريدني أن أفعل بها؟",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

الطلب الثاني، مع نفس id:

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": "ما هو الرقم الذي طلبت منك تذكره للتو؟"
  }'

{
  "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

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:

{"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:

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`.

بالنسبة للعملاء الذين يهتمون فقط بالإجابة النهائية، فإن تجميع كل text_delta من content يعادل answer في وضع application/json.

إدخال متعدد الوسائط

إذا كان إدخال المستخدم يحتوي على صور أو ملفات، تمرير message (مصفوفة) بدلاً من question. كل عنصر في المصفوفة هو كتلة محتوى:

{
  "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 لـ Google Drive / GitHub / Notion وما إلى ذلك → يمكن للنموذج استدعاء أدوات MCP المقابلة لقراءة وكتابة بياناته.

في تدفق NDJSON / SSE، يتم تقديم استدعاء الأدوات من خلال نوعي الأحداث tool_use و tool_result، على سبيل المثال:

{"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 لجعل الواجهة ترجع على الفور معرف المهمة، وتستمر الخلفية في التنفيذ:

{
  "model": "gpt-5.5",
  "async": true,
  "question": "خدمتي أصدرت إنذارًا، استخدم WeChat الشخصي لإخطار مجموعة WeChat 'فريق AceDataCloud'..."
}

مثال على الرد:

{
  "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 بتنفيذ إجراءات مثل الإرسال، النشر، الكتابة، وما إلى ذلك في وضع عدم الإشراف، يرجى تضمين قائمة التفويض المسبق بشكل صريح في جسم الطلب:

{
  "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 المعادل:

{
  "unattended_policy": {
    "allowed_skills": ["acedatacloud/personal-wechat"],
    "allowed_mcp_servers": [],
    "expires_at": 1790000000
  }
}

التفويض المسبق هو هذان القائمتان فقط: القائمة الفارغة تعني عدم تفويض أي قدرات، ولا حاجة إلى حقل مفتاح إضافي. ملاحظة: التفويض المسبق يمثل فقط “هذا الطلب يسمح لهذه القدرات بتجاوز التأكيد البشري في وضع عدم الإشراف”. يجب أن تدعم المهارة المحددة --unattended-confirm أو آلية الأمان المقابلة؛ وإلا ستستمر في التشغيل التجريبي، ولن يتم تنفيذ عمليات الكتابة مباشرة.

استعادة المحادثة المعلقة

بعض الأدوات ستجعل النموذج “يسأل المستخدم”، وفي هذه الحالة سيصدر النموذج حدث ask_user_question، وستتجمد المحادثة في حالة awaiting_user_input:

{
  "type": "ask_user_question",
  "tool_id": "toolu_01XYZW",
  "tool_name": "ask_user_question",
  "question": "هل ترغب في أن يكون التقرير باللغة الصينية أم الإنجليزية؟",
  "options": ["中文", "英文"],
  "id": "f2f4b3e8-..."
}

في الواجهة الأمامية، يتم عرض هذا الحدث كبطاقة ليختار المستخدم الإجابة، ثم باستخدام نفس id، يتم إرسال طلب جديد، ويتم ملء الإجابة عبر tool_results:

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` —— سحب جلسة واحدة

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` —— قائمة ملخص المحادثات

{
  "action": "retrieve_batch",
  "model_group": "chatgpt",
  "limit": 20,
  "offset": 0
}

إرجاع { items: [...], total }. الملخص لا يحتوي على messages، مناسب لقائمة الشريط الجانبي؛ إذا نقر المستخدم على محادثة معينة، استخدم action: retrieve لجلب رسائلها الكاملة بشكل منفصل. معلمات التصفية الاختيارية: user_id، application_id، model_group، model.

`action: update` —— تغيير العنوان أو إعادة كتابة التاريخ

{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "خطة السفر إلى هانغتشو"
}

يمكن أيضًا تمرير messages، لكن الخادم سيقوم بإجراء تحقق صارم من المخطط (يجب أن يكون في شكل ToolUseContent المطوي)، وإذا لم يتوافق، سيعيد 400. بشكل عام، يُنصح باستخدامه فقط لتغيير title.

`action: delete` —— حذف محادثة

{
  "action": "delete",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

إرجاع { id, success: true }. لا يمكن استعادة المحادثة بعد الحذف، يرجى التأكد قبل الاستدعاء.

الانتقال السلس من v1

إذا كنت تستخدم بالفعل /aichat/conversations، فإن الانتقال إلى v2 لا يتطلب تقريبًا أي تعديل على الكود:

قم بتغيير عنوان URL من https://api.acedata.cloud/aichat/conversations إلى https://api.acedata.cloud/aichat2/conversations.
إذا كنت قد قمت بتمرير أسماء نماذج v1 (مثل gpt-3.5، gpt-4-browsing، إلخ)، يُنصح بالترقية إلى النماذج المعاصرة عند الانتقال إلى v2 (مثل gpt-5.4، claude-opus-4-8، gemini-3.1-pro، إلخ).
تبقى حقول تدفق NDJSON متوافقة مع الإصدارات السابقة: لا يزال كل حدث text_delta يحمل delta_answer و id، لذلك لا يحتاج العميل الذي كان يحلل delta_answer سطرًا بسطر إلى إجراء أي تغييرات.

بعد الانتقال، يمكنك تفعيل قدرات v2 الجديدة حسب الحاجة (مثل message متعددة الوسائط، SSE، استدعاء الأدوات، CRUD action)، واتباع الإيقاع المناسب.

معالجة الأخطاء

تكون استجابة الخطأ موحدة كالتالي:

{
  "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 الانتقال بسلاسة على مراحل. إذا كانت لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

واجهة برمجة تطبيقات AI Chat v2 - تعليمات الدمج

عملية التقديم

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

المحادثات المتعددة

استجابة متدفقة

مثال NDJSON

مثال SSE

أنواع الأحداث المتدفقة

إدخال متعدد الوسائط

العلاقة مع `references` في v1

استدعاء الأدوات و MCP

التنفيذ غير المتزامن والتفويض بدون إشراف

استعادة المحادثة المعلقة

إدارة الجلسات (CRUD)

`action: retrieve` —— سحب جلسة واحدة

`action: retrieve_batch` —— قائمة ملخص المحادثات

`action: update` —— تغيير العنوان أو إعادة كتابة التاريخ

`action: delete` —— حذف محادثة

الانتقال السلس من v1

معالجة الأخطاء

الخاتمة

​عملية التقديم

​الاستخدام الأساسي

​المحادثات المتعددة

​استجابة متدفقة

​مثال NDJSON

​مثال SSE

​أنواع الأحداث المتدفقة

​إدخال متعدد الوسائط

​العلاقة مع references في v1

​استدعاء الأدوات و MCP

​التنفيذ غير المتزامن والتفويض بدون إشراف

​استعادة المحادثة المعلقة

​إدارة الجلسات (CRUD)

​action: retrieve —— سحب جلسة واحدة

​action: retrieve_batch —— قائمة ملخص المحادثات

​action: update —— تغيير العنوان أو إعادة كتابة التاريخ

​action: delete —— حذف محادثة

​الانتقال السلس من v1

​معالجة الأخطاء

​الخاتمة

عملية التقديم

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

المحادثات المتعددة

استجابة متدفقة

مثال NDJSON

مثال SSE

أنواع الأحداث المتدفقة

إدخال متعدد الوسائط

العلاقة مع `references` في v1

استدعاء الأدوات و MCP

التنفيذ غير المتزامن والتفويض بدون إشراف

استعادة المحادثة المعلقة

إدارة الجلسات (CRUD)

`action: retrieve` —— سحب جلسة واحدة

`action: retrieve_batch` —— قائمة ملخص المحادثات

`action: update` —— تغيير العنوان أو إعادة كتابة التاريخ

`action: delete` —— حذف محادثة

الانتقال السلس من v1

معالجة الأخطاء

الخاتمة