> ## Documentation Index
> Fetch the complete documentation index at: https://aimp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> شكل الطلب العام، ترويسات المصادقة، وأمثلة تنفيذ النماذج.

# REST API

استخدم REST API عندما تحتاج خدمتك الخلفية أو worker أو script إلى تشغيل نموذج
منشور. المستهلكون يستدعون Gateway العام فقط. لا تستدعِ الخدمات الداخلية مباشرة.

## Base URL

استخدم رابط Gateway الخاص ببيئتك:

```text theme={null}
<GATEWAY_URL>/api
```

في التطوير المحلي يكون Gateway غالباً:

```text theme={null}
http://localhost:8080/api
```

## المصادقة

طلبات server-to-server تستخدم API key:

```http theme={null}
X-API-Key: <your_api_key>
```

طلبات المتصفح داخل تطبيق المنتج تستخدم access token للمستخدم:

```http theme={null}
Authorization: Bearer <access_token>
```

لا تضع API keys طويلة العمر داخل JavaScript في المتصفح.

لا ترسل API key كـ bearer token. ترويسة `Authorization: Bearer <access_token>`
خاصة بجلسات المتصفح المسجلة الدخول؛ تكاملات المطورين تستخدم `X-API-Key`.

## تنفيذ نموذج

```bash theme={null}
curl -X POST "$AIMP_GATEWAY_URL/api/runs" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "demo-model",
    "mode": "execute",
    "scope": "playground",
    "input": {
      "text": "Hello"
    },
    "params": {}
  }'
```

## حقول الطلب

| الحقل     | مطلوب   | المعنى                                                                        |
| --------- | ------- | ----------------------------------------------------------------------------- |
| `model`   | نعم     | slug أو معرف النموذج المنشور.                                                 |
| `mode`    | لا      | العملية المطلوب تشغيلها. الافتراضي `execute`.                                 |
| `scope`   | أحياناً | مطلوب للعمليات المعتمدة على vector. هو namespace يفصل البيانات المفهرسة.      |
| `input`   | نعم     | مدخل النموذج. شكله يعتمد على عقد النموذج.                                     |
| `params`  | لا      | معاملات النموذج. يجب أن تكون JSON object.                                     |
| `options` | لا      | خيارات تنفيذ مسموحة. لا ترسل `hardware_tier`؛ العتاد يحدد من الإصدار المنشور. |

استخدم `params` وليس `parameters`. حقول vector مثل `resources` و`alias`
و`collection` و`namespace` تديرها المنصة ولا يجب على العميل إرسالها.

في عمليات `index` و`search` المعتمدة على vector، استخدم نفس `scope` للبيانات
التي تريد البحث فيها. إذا فهرست صوراً بـ `scope: "test"`، يجب أن تبحث أيضاً
بـ `scope: "test"`. صفحة Knowledge Bases تعرض البيانات حسب النموذج والكولكشن
والـ scope.

الـ scope الصحيح يبدأ بحرف أو رقم، ويسمح بالحروف والأرقام و`.` و`_` و`-`،
والحد الأقصى 64 حرفاً.

## رفع media لمدخلات النماذج

النماذج التي تقبل صوراً أو صوتاً أو فيديو أو ملفات تستعمل `media_ref` داخل
`input`. ارفع الملف أولاً عبر public media API:

```bash theme={null}
curl -X POST "$AIMP_GATEWAY_URL/api/media/upload/init" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "image.png",
    "content_type": "image/png",
    "media_type": "image",
    "size_bytes": 12345
  }'
```

ارفع bytes الملف إلى `upload_url` الراجع، ثم أكمل الرفع:

```bash theme={null}
curl -X POST "$AIMP_GATEWAY_URL/api/media/upload/complete" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "studio_upload_..."
  }'
```

استعمل `media_ref` الراجع داخل `POST /api/runs`.

## واجهات مرتبطة

* `GET /api/marketplace/models` تعرض نماذج Marketplace المنشورة.
* `GET /api/marketplace/models/{slug}` تعرض تفاصيل نموذج واحد.
* `POST /api/media/upload/init` يبدأ رفع media للمطورين.
* `POST /api/media/upload/complete` يرجع `media_ref` بعد اكتمال الرفع.
* `GET /api/billing/wallet` تعرض محفظة مساحة العمل الحالية.
* `GET /api/billing/usage/summary` تعرض ملخص الاستخدام لمساحة العمل.