---
url: 'https://dxpr.com/ar/hc/documentation/learn-dxpr-builder/ai/api-reference'
title: 'مرجع API للذكاء الاصطناعي | DXPR'
author:
  name: Jurriaan
  url: 'https://dxpr.com/users/jurriaan'
date: '2026-10-24T01:25:30+00:00'
updated: '2026-10-24T09:09:48+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: |-
  يكشف DXPR Builder عن ثلاثة مسارات ذكاء اصطناعي. فيستدعيها المتصفح،
  وتُمرّر المتحكمات الطلب عبر وحدة الذكاء الاصطناعي في Drupal إلى موفّر DXPR
  (ai_provider_dxpr)، فلا يصل مفتاح API أبدًا إلى
  المتصفح. والمسارات معرّفة في
  dxpr_builder.routing.yml؛ والسلوك أدناه صادر عن
  src/Controller/AiChatController.php و
  src/Controller/AiImageController.php.
tags:
  - 'Architectuur en API’s'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-24T09:09:48+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'مرجع API للذكاء الاصطناعي'
      description: |-
        يكشف DXPR Builder عن ثلاثة مسارات ذكاء اصطناعي. فيستدعيها المتصفح،
        وتُمرّر المتحكمات الطلب عبر وحدة الذكاء الاصطناعي في Drupal إلى موفّر DXPR
        (ai_provider_dxpr)، فلا يصل مفتاح API أبدًا إلى
        المتصفح. والمسارات معرّفة في
        dxpr_builder.routing.yml؛ والسلوك أدناه صادر عن
        src/Controller/AiChatController.php و
        src/Controller/AiImageController.php.
      image:
        '@type': ImageObject
        url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
        width: '1200'
        height: '630'
      datePublished: '2026-10-24T01:25:30+0000'
      dateModified: '2026-10-24T09:09:48+0000'
      author:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      mainEntityOfPage: 'https://dxpr.com/ar/hc/documentation/learn-dxpr-builder/ai/api-reference'
      articleSection: 'Architectuur en API’s'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/ar/hc/documentation/learn-dxpr-builder/ai/api-reference'
      description: |-
        يكشف DXPR Builder عن ثلاثة مسارات ذكاء اصطناعي. فيستدعيها المتصفح،
        وتُمرّر المتحكمات الطلب عبر وحدة الذكاء الاصطناعي في Drupal إلى موفّر DXPR
        (ai_provider_dxpr)، فلا يصل مفتاح API أبدًا إلى
        المتصفح. والمسارات معرّفة في
        dxpr_builder.routing.yml؛ والسلوك أدناه صادر عن
        src/Controller/AiChatController.php و
        src/Controller/AiImageController.php.
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: الرئيسية
            item: 'https://dxpr.com/ar'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: ar
---
[Help Center](/ar/hc)/[Documentation](/ar/hc/documentation) /[Learn DXPR Builder](/hc/documentation/learn-dxpr-builder) /[Extend](/hc/documentation/learn-dxpr-builder/extend) /[Architectuur en API’s](/hc/documentation/learn-dxpr-builder/extend/architecture) # مرجع API للذكاء الاصطناعي.

 Learn DXPR BuilderExtendArchitectuur en API’s

   ## In this guide

 Related guides

- [النماذج والمزوّدون](/ar/hc/documentation/learn-dxpr-builder/ai/models-and-providers)
- [إعدادات الذكاء الاصطناعي](/ar/hc/documentation/learn-dxpr-builder/ai/configuration)
- [استكشاف أخطاء الذكاء الاصطناعي وإصلاحها](/ar/hc/documentation/learn-dxpr-builder/ai/troubleshooting)

يكشف DXPR Builder عن ثلاثة مسارات ذكاء اصطناعي. فيستدعيها المتصفح، وتُمرّر المتحكمات الطلب عبر وحدة الذكاء الاصطناعي في Drupal إلى موفّر DXPR (`ai_provider_dxpr`)، فلا يصل مفتاح API أبدًا إلى المتصفح. والمسارات معرّفة في `dxpr_builder.routing.yml`؛ والسلوك أدناه صادر عن `src/Controller/AiChatController.php` و `src/Controller/AiImageController.php`.

## متطلبات الوصول (المسارات الثلاثة كلها)

| المتطلب | المصدر |
|---|---|
| طريقة HTTP `POST` | `methods: [POST]` في المسار |
| الصلاحية `edit with dxpr builder` | `_permission` |
| مستخدم مُحاسَب (مقعد ترخيص صالح) | `_dxpr_builder_billable_user`، يتحقق منه `DxprBuilderBillableUserAccessCheck` |
| رمز CSRF في `token` من معامل الاستعلام | `_csrf_token: 'TRUE'` |
| كوكي جلسة Drupal لمستخدم مسجل | تعمل فحوصات وصول Drupal لكل مستخدم |

الرمز هو رمز CSRF الخاص بمسار Drupal لمسار المسار. ويولّده DXPR Builder من جهة الخادم ويضمّنه في `drupalSettings.dxprBuilder.aiAgent`كـ `endpointUrl` و`imageEndpointUrl` و `imageEditEndpointUrl` (انظر `DxprBuilderFormatter`). اقرؤوا إحدى تلك القيم من صفحة يُحمَّل فيها المحرّر للحصول على URL يعمل. ويعيد فحص الوصول الفاشل استجابة `403` المعيارية في Drupal.

تُنشئ المتحكمات دائمًا موفّر `dxpr`؛ فالموفّر المضبوط في `/admin/config/ai/settings` لا يُستخدم.

## المحادثة

`POST /dxpr_builder/ajax/ai/chat?token=...`

تستخدمه أوامر النصوص وإنشاء الصفحات واقتراحات الأوامر. فيقرأ المتحكم متن JSON ويستدعي `$provider->chat()`.

### متن الطلب

| الحقل | النوع | مطلوب | ملاحظات |
|---|---|---|---|
| `messages` | مصفوفة من `{role, content}` | نعم | `role` هو `system` أو `user` أو `assistant` |
| `model` | سلسلة | لا | الافتراضي `kavya-m1`. ويجب أن يكون في قائمة النماذج المسموحة لدى الموفّر |
| `stream` | منطقي | لا | الافتراضي `true` |
| `prediction` | كائن | لا | يُمرَّر كما هو، مثلًا `{"type":"content","content":"<p>...</p>"}` |
| `providers` | سلسلة | لا | معرّفات موفّرين مفصولة بفواصل، مثلًا `openai,mistral` |
| `allowed_html_tags` | سلسلة | لا | يُمرَّر كما هو؛ فيرسل المنشئ `Bootstrap 5 HTML` |
| `allowed_html_classes` | سلسلة | لا | يُمرَّر كما هو؛ فيرسل المنشئ `Bootstrap 5 Classes` |
| `web_search` | منطقي | لا | تُمرَّر القيمة `false` فقط |
| `response_format` | كائن | لا | يُمرَّر كما هو، مثلًا `json_schema` ككائن |

يضيف المتحكم دائمًا `jsonrpc: false` إلى إعدادات الموفّر. وقبل الاستدعاء يدمج النطاقات من **ترشيح مخرجات الذكاء الاصطناعي &gt; النطاقات المسموحة** في مرشّح أسماء المضيفين الخاص بوحدة الذكاء الاصطناعي لمدة الطلب (`*` يحوّل المرشّح إلى ثقة كاملة).

### الاستجابة

متدفقة (`stream` بقيمة true، وهي الافتراضية): `200`، `Content-Type: text/event-stream`. فكل حدث هو `data: {json}` متبوعًا بسطر فارغ، وينتهي التدفق بـ `data: [DONE]`.

```text
data: {"choices":[{"delta":{"content":"Hello"}}],"id":"...","model":"kavya-m1","usage":{...}}

data: [DONE]

```

`id` و`object` و`created` و`model` و `original_model` و`usage` تُنسخ من القطعة الخام للموفّر عند وجودها.

غير متدفقة (`stream` بقيمة false): `200`، `application/json`:

```json
{"choices":[{"message":{"role":"assistant","content":"..."}}]}

```

### الأخطاء

| الحالة | المتن |
|---|---|
| `400` | نص عادي `Invalid request: messages required` |
| `403` | `{"error":{"code":"model_not_allowed","message":"The selected model is not allowed. Please refresh the page to update your model options."}}` عندما تكون `ai_provider_dxpr` مثبّتة و`model` ليس في قائمة النماذج المسموحة الخاصة بها |
| `500` | `{"error":{"message":"The request could not be completed."}}` (التفاصيل في قناة سجل `dxpr_builder`) |

### مثال

```js
const url = drupalSettings.dxprBuilder.aiAgent.endpointUrl;
const res = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "kavya-m1",
    stream: false,
    messages: [
      { role: "system", content: "You are a copywriter." },
      { role: "user", content: "Shorten: <p>Our team ...</p>" }
    ]
  })
});
const data = await res.json();
console.log(data.choices[0].message.content);

```

## توليد الصور

`POST /dxpr_builder/ajax/ai/image?token=...`

يستدعي `$provider->textToImage()`.

### متن الطلب

| الحقل | النوع | مطلوب | ملاحظات |
|---|---|---|---|
| `prompt` | سلسلة | نعم | وصف نصي للصورة |
| `model` | سلسلة | لا | الافتراضي `kavya-image` |
| `size` | سلسلة | لا | يرسل المنشئ `1024x1024` أو `1536x1024` أو `1024x1536`؛ ويُحذَف مع Auto |
| `quality` | سلسلة | لا | تُمرَّر إلى الموفّر دون تغيير |
| `background` | سلسلة | لا | تُمرَّر إلى الموفّر دون تغيير |

### الاستجابة

`200`، `application/json`. تُعاد الصورة الأولى فقط، مرمّزة base64. ويطلب موفّر DXPR مخرجات `webp`.

```json
{"data":[{"b64_json":"UklGRi..."}]}

```

### الأخطاء

| الحالة | المتن |
|---|---|
| `400` | `{"error":{"message":"Invalid request: prompt required"}}` |
| `500` | `{"error":{"message":"No image was generated"}}` |
| `500` | `{"error":{"message":"Image generation failed. Please try again."}}` |

### مثال

```bash
curl -X POST "https://example.com/dxpr_builder/ajax/ai/image?token=TOKEN" \
  -H "Content-Type: application/json" \
  -H "Cookie: SESSxxx=..." \
  -d '{"prompt":"Flat illustration of a rocket","size":"1536x1024"}'

```

## تحرير الصور

`POST /dxpr_builder/ajax/ai/image/edit?token=...`

يستدعي `$provider->imageToImage()` مع الصورة المرفوعة والأمر.

### متن الطلب

| الحقل | النوع | مطلوب | ملاحظات |
|---|---|---|---|
| `prompt` | سلسلة | نعم | تعليمات التحرير |
| `image` | سلسلة | نعم | بيانات الصورة base64 دون بادئة `data:`؛ وفك ترميز صارم |
| `mimeType` | سلسلة | لا | الافتراضي `image/png`؛ ويصبح النوع الفرعي امتداد الملف |
| `model` | سلسلة | لا | الافتراضي `kavya-image` |
| `size` و`quality` و`background` | سلسلة | لا | كما في توليد الصور |

### الاستجابة

الشكل نفسه كتوليد الصور: `{"data":[{"b64_json":"..."}]}`.

### الأخطاء

| الحالة | المتن |
|---|---|
| `400` | `{"error":{"message":"Invalid request: prompt and image required"}}` |
| `400` | `{"error":{"message":"Invalid image data: base64 decode failed"}}` |
| `500` | `{"error":{"message":"No image was generated"}}` |
| `500` | `{"error":{"message":"Image editing failed. Please try again."}}` |

### مثال

```js
const url = drupalSettings.dxprBuilder.aiAgent.imageEditEndpointUrl;
const res = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "Remove the background",
    image: base64String,
    mimeType: "image/jpeg"
  })
});
const { data } = await res.json();

```

## تخزين الصورة المولّدة

تعيد المسارات بايتات الصورة فقط. فيحوّل المنشئ `b64_json` إلى ملف `webp` ويرفعه إلى `POST /dxpr_builder/ajax/file_upload`(`drupalSettings.dxprBuilder.fileUploadUrl`، حقل النموذج `upload[]`)، فيرد بعنصري الملف `url` و`fid`. ويصبح الأمر اسم الملف (أول 80 حرفًا) وسمة alt.

## ما الخطوة التالية؟

- [النماذج والمزوّدون](/ar/hc/documentation/learn-dxpr-builder/ai/models-and-providers)
- [إعدادات الذكاء الاصطناعي](/ar/hc/documentation/learn-dxpr-builder/ai/configuration)
- [استكشاف أخطاء الذكاء الاصطناعي وإصلاحها](/ar/hc/documentation/learn-dxpr-builder/ai/troubleshooting)