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

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

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

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

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

الاستجابة:

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

مثال Python:

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

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

الاستجابة:

{
  "answer": "حسنًا، لقد حفظت الرقم 42. هل تريد مني استخدامه في شيء ما؟",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

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

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": "我刚才让你记住的数字是多少？"
  }'

الاستجابة:

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

{"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.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. كل عنصر في المصفوفة هو كتلة محتوى:

{
  "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 مثل 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) يجبر الرد على أن يكون مرة واحدة بدون استدعاء أدوات.

استئناف المحادثة الموقوفة

بعض الأدوات قد تجعل النموذج “يسأل المستخدم” لاستكمال المعلومات، حينها يرسل النموذج حدث 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.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` — استرجاع محادثة واحدة

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

{
  "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.xhuoapi.ai/v1/aichat/conversations إلى https://api.xhuoapi.ai/v1/aichat2/conversations.
إذا كنت تستخدم أسماء نماذج v1 (مثل gpt-3.5، gpt-4-browsing)، يُنصح بالترقية إلى نماذج معاصرة في v2 (مثل gpt-5.4، claude-opus-4-7، gemini-3.1-pro).
تدفق NDJSON يحتفظ بالتوافق الخلفي: كل حدث text_delta لا يزال يحمل delta_answer و id، لذا لا حاجة لتعديل عملاء تحليل delta_answer.

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

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

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

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

Documentation Index

​إجراءات التقديم

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

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

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

​مثال 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

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

الخلاصة