Link to this sectionمرجع REST API#

توفر Ultralytics Platform واجهة REST API شاملة للوصول البرمجي إلى مجموعات البيانات والنماذج والتدريب وعمليات النشر.

# List your datasets
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets

Link to this sectionنظرة عامة على API#

تم تنظيم API حول موارد المنصة الأساسية:

graph LR
    A[API Key] --> B[Datasets]
    A --> C[Projects]
    A --> D[Models]
    A --> E[Deployments]
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]
    B -->|auto-annotate| B

Link to this sectionالمصادقة#

تستخدم واجهات برمجة تطبيقات الموارد مثل مجموعات البيانات والمشاريع والنماذج والتدريب والتصدير والتنبؤات مصادقة مفتاح API. تدعم نقاط النهاية العامة (عرض مجموعات البيانات والمشاريع والنماذج العامة) وصول القراءة المجهول بدون مفتاح. تتطلب المسارات الموجهة للحساب - بما في ذلك النشاط والإعدادات والفرق والفواتير وتدفقات GDPR - حاليًا جلسة متصفح مصادق عليها وليست متاحة عبر مفتاح API.

Link to this sectionالحصول على مفتاح API#

1. انتقل إلى Settings > API Keys
2. انقر على Create Key
3. انسخ المفتاح الذي تم إنشاؤه

راجع API Keys للحصول على تعليمات مفصلة.

Link to this sectionرأس التفويض#

قم بتضمين مفتاح API الخاص بك في جميع الطلبات:

Authorization: Bearer YOUR_API_KEY

Link to this sectionمثال#

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets

Link to this sectionعنوان URL الأساسي#

تستخدم جميع نقاط نهاية API:

Link to this sectionحدود المعدل#

يفرض API حدود معدل لكل مفتاح API (نافذة منزلقة، مدعومة بـ Upstash Redis) للحماية من إساءة الاستخدام مع الحفاظ على الاستخدام المشروع دون قيود. يتم حماية حركة المرور المجهولة بالإضافة إلى ذلك من خلال ضوابط إساءة الاستخدام على مستوى منصة Vercel.

عند تقييد السرعة، يعيد API رمز 429 مع بيانات تعريف إعادة المحاولة:

Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z

Link to this sectionحدود كل مفتاح API#

يتم تطبيق حدود المعدل تلقائيًا بناءً على نقطة النهاية التي يتم استدعاؤها. تحتوي العمليات المكلفة على حدود أكثر صرامة لمنع إساءة الاستخدام، بينما تشترك عمليات CRUD القياسية في حد افتراضي سخي:

كل فئة لديها عداد مستقل لكل مفتاح API. على سبيل المثال، إجراء 20 طلب تنبؤ لا يؤثر على مخصصاتك الافتراضية البالغة 100 طلب/دقيقة.

Link to this sectionنقاط النهاية المخصصة (غير محدودة)#

Dedicated endpoints لا تخضع لحدود معدل مفتاح API. عند نشر نموذج في نقطة نهاية مخصصة، تذهب الطلبات إلى عنوان URL لنقطة النهاية تلك (على سبيل المثال، https://predict-abc123.run.app/predict) مباشرة إلى خدمتك المخصصة دون أي تحديد للمعدل من المنصة. أنت تدفع مقابل الحوسبة، لذا تحصل على إنتاجية من تكوين خدمتك المخصصة بدلاً من حدود API المشتركة.

Link to this sectionتنسيق الاستجابة#

Link to this sectionاستجابات النجاح#

تعيد الاستجابات JSON مع حقول خاصة بالمورد:

{
    "datasets": [...],
    "total": 100
}

Link to this sectionاستجابات الخطأ#

{
    "error": "Dataset not found"
}

Link to this sectionAPI مجموعات البيانات#

إنشاء وتصفح وإدارة مجموعات بيانات الصور المصنفة لتدريب نماذج YOLO. راجع وثائق مجموعات البيانات.

Link to this sectionسرد مجموعات البيانات#

GET /api/datasets

معلمات الاستعلام:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"

الاستجابة:

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Link to this sectionالحصول على مجموعة بيانات#

GET /api/datasets/{datasetId}

إرجاع تفاصيل مجموعة البيانات الكاملة بما في ذلك البيانات الوصفية، وأسماء الفئات، وأعداد التقسيمات.

Link to this sectionإنشاء مجموعة بيانات#

POST /api/datasets

الجسم (Body):

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "visibility": "private",
    "classNames": ["person", "car"]
}

Link to this sectionتحديث مجموعة بيانات#

PATCH /api/datasets/{datasetId}

الجسم (تحديث جزئي):

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

Link to this sectionأيقونة مجموعة البيانات#

تحميل أيقونة مجموعة البيانات (نموذج متعدد الأجزاء مع ملف صورة):

POST /api/datasets/{datasetId}/icon

إزالة أيقونة مجموعة البيانات:

DELETE /api/datasets/{datasetId}/icon

كلاهما يتطلب جلسة متصفح نشطة على المنصة — غير متاح عبر مفتاح API.

Link to this sectionحذف مجموعة بيانات#

DELETE /api/datasets/{datasetId}

حذف ناعم لمجموعة البيانات (تُنقل إلى سلة المهملات، ويمكن استردادها خلال 30 يومًا).

Link to this sectionاستنساخ مجموعة البيانات#

POST /api/datasets/{datasetId}/clone

ينشئ نسخة من مجموعة البيانات مع جميع الصور والتسميات. لا يمكن استنساخ سوى مجموعات البيانات العامة أو المملوكة أو القابلة للتعديل في مساحة العمل. يتطلب جلسة متصفح نشطة للمنصة — غير متاح عبر مفتاح API.

الجسم (جميع الحقول اختيارية):

{
    "name": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "owner": "team-username"
}

Link to this sectionتصدير مجموعة البيانات#

GET /api/datasets/{datasetId}/export

إرجاع استجابة JSON مع رابط تنزيل موقع لأحدث تصدير لمجموعة البيانات.

معلمات الاستعلام:

الاستجابة:

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": true
}

Link to this sectionإنشاء إصدار مجموعة بيانات#

POST /api/datasets/{datasetId}/export

إنشاء لقطة إصدار مرقمة جديدة لمجموعة البيانات. للمالك فقط. يسجل الإصدار عدد الصور الحالي، وعدد الفئات، وعدد التعليقات التوضيحية، وتوزيع التقسيم، ثم يقوم بإنشاء وتخزين تصدير NDJSON غير قابل للتغيير.

جسم الطلب:

{
    "description": "Added 500 training images"
}

جميع الحقول اختيارية. حقل description هو تسمية يوفرها المستخدم للإصدار.

الاستجابة:

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

Link to this sectionتحديث وصف الإصدار#

PATCH /api/datasets/{datasetId}/export

تحديث وصف إصدار موجود. للمالك فقط.

جسم الطلب:

{
    "version": 2,
    "description": "Fixed mislabeled classes"
}

الاستجابة:

{
    "ok": true
}

Link to this sectionالحصول على إحصائيات الفئة#

GET /api/datasets/{datasetId}/class-stats

إرجاع توزيع الفئات، وخريطة الحرارة للموقع، وإحصائيات الأبعاد. يتم تخزين النتائج مؤقتًا لمدة تصل إلى 5 دقائق.

الاستجابة:

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

Link to this sectionإدارة الفئات#

دمج الفئات (إعادة تعيين التعليقات التوضيحية من الفئات المصدر إلى فئة مستهدفة، ثم إزالة المصادر):

POST /api/datasets/{datasetId}/classes/merge

حذف الفئات:

POST /api/datasets/{datasetId}/classes/delete

Link to this sectionإعادة توزيع التقسيمات#

POST /api/datasets/{datasetId}/splits/redistribute

إعادة تعيين الصور عبر تقسيمات التدريب/التحقق/الاختبار (train/val/test). تتطلب جميعها جلسة متصفح نشطة للمنصة — غير متاح عبر مفتاح API.

Link to this sectionتضمينات (Embeddings) مجموعة البيانات#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

يقوم GET بإرجاع ملخص تحليل UMAP الحالي وحالة الوظيفة النشطة؛ ويقوم POST بوضع وظيفة تحليل التضمينات في قائمة الانتظار؛ ويقوم DELETE بإلغاء الوظيفة النشطة.

Link to this sectionتجميع الصور#

GET /api/datasets/{datasetId}/images/clustering

إرجاع تخطيط UMAP ثنائي الأبعاد والبيانات الوصفية لكل صورة لعرض التشتت المجمع (مقسم إلى صفحات ومحدد المعدل).

Link to this sectionالحصول على النماذج المدربة على مجموعة البيانات#

GET /api/datasets/{datasetId}/models

إرجاع النماذج التي تم تدريبها باستخدام مجموعة البيانات هذه.

الاستجابة:

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

Link to this sectionالتصنيف التلقائي لمجموعة البيانات#

POST /api/datasets/{datasetId}/predict

تشغيل استدلال YOLO على صور مجموعة البيانات لإنشاء التعليقات التوضيحية تلقائيًا. يستخدم نموذجًا محددًا للتنبؤ بالملصقات للصور غير المعلقة.

الجسم (Body):

Link to this sectionاستيعاب مجموعة البيانات#

POST /api/datasets/ingest

إنشاء وظيفة استيعاب لمجموعة البيانات لمعالجة ملفات ZIP أو TAR المرفوعة، بما في ذلك .tar.gz و .tgz، التي تحتوي على صور وملصقات.

يأخذ نص الطلب واحداً فقط من sessionId (جلسة تحميل لأرشيف مرفوع) أو sourceUrl (رابط ZIP أو TAR أو TAR.GZ أو TGZ أو NDJSON عن بُعد)، بالإضافة إلى targetSplit اختياري (train أو val أو test) لتجاوز هيكل تقسيم الأرشيف.

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

Link to this sectionصور مجموعة البيانات#

Link to this sectionسرد الصور#

GET /api/datasets/{datasetId}/images

معلمات الاستعلام:

Link to this sectionالحصول على روابط الصور الموقعة#

POST /api/datasets/{datasetId}/images/urls

الحصول على روابط موقعة لمجموعة من تجزئات الصور (للعرض في المتصفح).

Link to this sectionحذف صورة#

DELETE /api/datasets/{datasetId}/images/{hash}

Link to this sectionالحصول على ملصقات الصور#

GET /api/datasets/{datasetId}/images/{hash}/labels

إرجاع التعليقات التوضيحية وأسماء الفئات لصورة معينة.

Link to this sectionتحديث ملصقات الصور#

PUT /api/datasets/{datasetId}/images/{hash}/labels

الجسم (Body):

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Link to this sectionعمليات الصور الجماعية#

نقل الصور بين التقسيمات (train/val/test) داخل مجموعة البيانات:

PATCH /api/datasets/{datasetId}/images/bulk

حذف الصور بشكل جماعي:

DELETE /api/datasets/{datasetId}/images/bulk

Link to this sectionAPI المشاريع#

نظم نماذجك في مشاريع. ينتمي كل نموذج إلى مشروع واحد. راجع وثائق المشاريع.

Link to this sectionسرد المشاريع#

GET /api/projects

معلمات الاستعلام:

Link to this sectionالحصول على مشروع#

GET /api/projects/{projectId}

Link to this sectionإنشاء مشروع#

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

Link to this sectionتحديث مشروع#

PATCH /api/projects/{projectId}

Link to this sectionحذف مشروع#

DELETE /api/projects/{projectId}

حذف ناعم للمشروع (تم نقله إلى سلة المهملات).

Link to this sectionاستنساخ مشروع#

POST /api/projects/{projectId}/clone

استنساخ مشروع عام (مع جميع نماذجه) إلى مساحة عملك. يتطلب جلسة متصفح منصة نشطة - غير متاح عبر مفتاح API.

Link to this sectionأيقونة المشروع#

رفع أيقونة مشروع (نموذج متعدد الأجزاء مع ملف صورة):

POST /api/projects/{projectId}/icon

إزالة أيقونة المشروع:

DELETE /api/projects/{projectId}/icon

كلاهما يتطلب جلسة متصفح نشطة على المنصة — غير متاح عبر مفتاح API.

Link to this sectionAPI النماذج#

إدارة نماذج YOLO المدربة — عرض المقاييس، وتنزيل الأوزان، وتشغيل الاستدلال، والتصدير إلى تنسيقات أخرى. انظر توثيق النماذج.

Link to this sectionسرد النماذج#

GET /api/models

معلمات الاستعلام:

Link to this sectionسرد النماذج المكتملة#

GET /api/models/completed

إرجاع النماذج التي أنهت التدريب (للاستخدام في محددات النماذج والنشر).

Link to this sectionالحصول على نموذج#

GET /api/models/{modelId}

Link to this sectionإنشاء نموذج#

POST /api/models

جسم JSON:

Link to this sectionتحديث نموذج#

PATCH /api/models/{modelId}

Link to this sectionحذف نموذج#

DELETE /api/models/{modelId}

Link to this sectionتنزيل ملفات النموذج#

GET /api/models/{modelId}/files

إرجاع روابط تنزيل موقعة لملفات النموذج.

Link to this sectionاستنساخ نموذج#

POST /api/models/{modelId}/clone

استنساخ نموذج عام إلى أحد مشاريعك. يتطلب جلسة متصفح نشطة على المنصة — غير متاح عبر مفتاح API.

الجسم (Body):

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

Link to this sectionتتبع التنزيل#

POST /api/models/{modelId}/track-download

تتبع تحليلات تنزيل النموذج.

Link to this sectionتشغيل الاستنتاج#

POST /api/models/{modelId}/predict

نموذج Multipart:

الحد الأقصى لحجم التحميل هو 100 ميجابايت.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

الاستجابة:

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

Link to this sectionالحصول على رمز الاستدلال (Predict Token)#

POST /api/models/{modelId}/predict/token

Link to this sectionتسخين النموذج (Warmup)#

POST /api/models/{modelId}/predict/warmup

Link to this sectionAPI التدريب#

بدء تدريب YOLO على GPUs سحابية (24 نوعاً من GPU من RTX 2000 Ada إلى B300) ومراقبة التقدم في الوقت الفعلي. انظر توثيق التدريب السحابي.

graph LR
    A[POST /training/start] --> B[Job Created]
    B --> C{Training}
    C -->|progress| D[GET /models/id/training]
    C -->|cancel| E[DELETE /models/id/training]
    C -->|complete| F[Model Ready]
    F --> G[Deploy or Export]

Link to this sectionبدء التدريب#

POST /api/training/start

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

Link to this sectionالحصول على توفر GPU#

GET /api/training/gpu-availability

إرجاع حالة مخزون GPU الحالية (High أو Medium أو Low أو null) مصنفة حسب معرف نوع GPU. عام، لا يتطلب مصادقة؛ مؤقت لمدة 5 دقائق.

Link to this sectionالحصول على حالة التدريب#

GET /api/models/{modelId}/training

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

Link to this sectionإلغاء التدريب#

DELETE /api/models/{modelId}/training

إنهاء مثيل الحوسبة قيد التشغيل ووسم المهمة كملغاة. يتطلب جلسة متصفح نشطة على المنصة — غير متاح عبر مفتاح API.

Link to this sectionAPI النشر#

نشر النماذج على نقاط نهاية استدلال مخصصة مع فحص الصحة والمراقبة. عمليات النشر الجديدة تستخدم التوسع إلى الصفر (scale-to-zero) بشكل افتراضي، ويقبل الـ API كائن resources اختياري. انظر توثيق نقاط النهاية.

graph LR
    A[Create] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

Link to this sectionسرد عمليات النشر#

GET /api/deployments

معلمات الاستعلام:

Link to this sectionإنشاء نشر#

POST /api/deployments

الجسم (Body):

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

إنشاء نقطة نهاية استدلال مخصصة في المنطقة المحددة. نقطة النهاية متاحة عالمياً عبر رابط URL فريد.

Link to this sectionالحصول على نشر#

GET /api/deployments/{deploymentId}

Link to this sectionحذف نشر#

DELETE /api/deployments/{deploymentId}

Link to this sectionبدء نشر#

POST /api/deployments/{deploymentId}/start

استئناف عملية نشر متوقفة.

Link to this sectionإيقاف نشر#

POST /api/deployments/{deploymentId}/stop

إيقاف مؤقت لعملية نشر قيد التشغيل (يوقف الفوترة).

Link to this sectionفحص الصحة#

GET /api/deployments/{deploymentId}/health

إرجاع حالة صحة نقطة نهاية النشر.

Link to this sectionتشغيل الاستدلال على النشر#

POST /api/deployments/{deploymentId}/predict

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

نموذج Multipart:

Link to this sectionالحصول على المقاييس#

GET /api/deployments/{deploymentId}/metrics

إرجاع مقاييس عدد الطلبات، وزمن الانتقال، ومعدل الخطأ مع بيانات الرسوم البيانية المصغرة (sparkline).

معلمات الاستعلام:

Link to this sectionالحصول على السجلات#

GET /api/deployments/{deploymentId}/logs

معلمات الاستعلام:

Link to this sectionAPI المراقبة#

Link to this sectionالمقاييس المجمعة#

GET /api/monitoring

إرجاع المقاييس المجمعة عبر جميع عمليات نشر المستخدم: إجمالي الطلبات، عمليات النشر النشطة، معدل الخطأ، ومتوسط زمن الاستجابة.

Link to this sectionAPI التصدير#

تحويل النماذج إلى تنسيقات محسنة مثل ONNX وTensorRT وCoreML وTFLite من أجل النشر على الحافة. راجع وثائق النشر.

Link to this sectionسرد عمليات التصدير#

GET /api/exports

معلمات الاستعلام:

Link to this sectionإنشاء تصدير#

POST /api/exports

الجسم (Body):

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

التنسيقات المدعومة:

Link to this sectionالحصول على حالة التصدير#

GET /api/exports/{exportId}

Link to this sectionإلغاء التصدير#

DELETE /api/exports/{exportId}

Link to this sectionتتبع تنزيل التصدير#

POST /api/exports/{exportId}/track-download

Link to this sectionAPI النشاط#

عرض موجز للإجراءات الأخيرة على حسابك — عمليات التدريب، عمليات الرفع، والمزيد. راجع وثائق النشاط.

Link to this sectionسرد النشاط#

GET /api/activity

معلمات الاستعلام:

Link to this sectionتحديد الأحداث كمقروءة#

POST /api/activity/mark-seen

الجسم (Body):

{
    "all": true
}

أو قم بتمرير معرفات محددة:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

Link to this sectionأرشفة الأحداث#

POST /api/activity/archive

الجسم (Body):

{
    "all": true,
    "archive": true
}

أو قم بتمرير معرفات محددة:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

Link to this sectionAPI سلة المهملات#

عرض واستعادة العناصر المحذوفة. يتم حذف العناصر نهائياً بعد 30 يوماً. راجع وثائق سلة المهملات.

Link to this sectionسرد سلة المهملات#

GET /api/trash

معلمات الاستعلام:

Link to this sectionاستعادة العنصر#

POST /api/trash

الجسم (Body):

{
    "id": "item_abc123",
    "type": "dataset"
}

Link to this sectionحذف العنصر نهائياً#

DELETE /api/trash

الجسم (Body):

{
    "id": "item_abc123",
    "type": "dataset"
}

Link to this sectionإفراغ سلة المهملات#

DELETE /api/trash/empty

حذف جميع العناصر في سلة المهملات نهائياً.

Link to this sectionAPI الفوترة#

تحقق من رصيد نقاطك، واشترِ نقاطاً، واعرض سجل المعاملات، وقم بتهيئة إعادة التعبئة التلقائية. راجع وثائق الفوترة.

Link to this sectionالحصول على الرصيد#

GET /api/billing/balance

معلمات الاستعلام:

الاستجابة:

{
    "creditsCents": 2500,
    "plan": "free"
}

Link to this sectionالحصول على ملخص الاستخدام#

GET /api/billing/usage-summary

إرجاع تفاصيل الخطة والحدود ومقاييس الاستخدام.

Link to this sectionالحصول على المعاملات#

GET /api/billing/transactions

إرجاع سجل المعاملات (الأحدث أولاً).

معلمات الاستعلام:

Link to this sectionإنشاء جلسة دفع#

POST /api/billing/checkout-session

الجسم (Body):

{
    "amount": 25,
    "owner": "team-username"
}

إنشاء جلسة دفع لشراء النقاط.

Link to this sectionإنشاء دفع اشتراك#

POST /api/billing/subscription-checkout

إنشاء جلسة دفع لترقية اشتراك Pro.

الجسم (Body):

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Link to this sectionإلغاء أو استئناف الاشتراك#

DELETE /api/billing/subscription-checkout

إلغاء اشتراك Pro في نهاية الفترة افتراضياً. أرسل {"resume": true} لاستئناف عملية إلغاء مجدولة بالفعل قبل انتهاء فترة الفوترة.

الجسم (Body):

{
    "resume": true
}

Link to this sectionإعادة التعبئة التلقائية#

إضافة الرصيد تلقائياً عندما ينخفض الرصيد عن حد معين.

Link to this sectionالحصول على إعدادات التعبئة التلقائية للرصيد#

GET /api/billing/auto-topup

معلمات الاستعلام:

Link to this sectionتحديث إعدادات التعبئة التلقائية للرصيد#

PATCH /api/billing/auto-topup

الجسم (Body):

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Link to this sectionطرق الدفع#

Link to this sectionسرد طرق الدفع#

GET /api/billing/payment-methods

Link to this sectionإنشاء نية الإعداد#

POST /api/billing/payment-methods/setup

إرجاع سر العميل لإضافة طريقة دفع جديدة.

Link to this sectionتعيين طريقة الدفع الافتراضية#

POST /api/billing/payment-methods/default

الجسم (Body):

{
    "paymentMethodId": "pm_123"
}

Link to this sectionتحديث معلومات الفواتير#

PATCH /api/billing/payment-methods

الجسم (Body):

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Link to this sectionحذف طريقة الدفع#

DELETE /api/billing/payment-methods/{id}

Link to this sectionواجهة برمجة تطبيقات التخزين#

تحقق من تفاصيل استخدام التخزين حسب الفئة (مجموعات البيانات، النماذج، الصادرات) واطلع على أكبر عناصرك.

Link to this sectionالحصول على معلومات التخزين#

GET /api/storage

معلمات الاستعلام:

الاستجابة:

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

Link to this sectionواجهة برمجة تطبيقات الرفع#

رفع الملفات مباشرة إلى التخزين السحابي باستخدام عناوين URL موقعة لعمليات نقل سريعة وموثوقة. يستخدم تدفقاً من خطوتين: الحصول على عنوان URL موقع، ثم رفع الملف. راجع وثائق البيانات.

Link to this sectionالحصول على عنوان URL موقع للرفع#

POST /api/upload/signed-url

طلب عنوان URL موقع لرفع ملف مباشرة إلى التخزين السحابي. يتجاوز عنوان URL الموقع خادم API لعمليات نقل الملفات الكبيرة.

الجسم (Body):

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

الاستجابة:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "gcsPath": "gs://bucket/users/user123/images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Link to this sectionإكمال الرفع#

POST /api/upload/complete

إخطار المنصة بأن رفع الملف قد اكتمل لتبدأ في معالجته.

الجسم (Body):

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

Link to this sectionواجهة برمجة تطبيقات عمليات التكامل (Integrations API)#

استيراد مجموعات البيانات من خدمات طرف ثالث. راجع وثائق عمليات التكامل.

Link to this sectionمعاينة استيراد Roboflow#

POST /api/integrations/roboflow/preview

تحويل مفتاح Roboflow API إلى خطة استيراد مجمعة: معلومات مساحة العمل، والمشاريع التي سيتم استيرادها حديثاً، وعدد الإصدارات التي تم استيرادها بالفعل (تم تخطيها)، وأنواع المشاريع غير المدعومة. يتم تمرير مفتاح Roboflow API في النص ولا يتم حفظه.

Link to this sectionاستيراد من Roboflow#

POST /api/integrations/roboflow/import

وضع وظائف استيعاب مجموعة البيانات في قائمة الانتظار لاستيراد مشاريع Roboflow المحددة إلى مساحة العمل الخاصة بك. يتطلب مساحة تخزين كافية، ويجب أن تتناسب كل مجموعة بيانات مع حد الحجم لكل استيراد في خطتك.

Link to this sectionواجهة برمجة تطبيقات مفاتيح API#

إدارة مفاتيح API الخاصة بك للوصول البرمجي. راجع وثائق مفاتيح API.

Link to this sectionسرد مفاتيح API#

GET /api/api-keys

Link to this sectionإنشاء مفتاح API#

POST /api/api-keys

الجسم (Body):

{
    "name": "training-server"
}

Link to this sectionحذف مفتاح API#

DELETE /api/api-keys

معلمات الاستعلام:

مثال:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

Link to this sectionواجهة برمجة تطبيقات الفرق والأعضاء#

إنشاء مساحات عمل الفريق، ودعوة الأعضاء، وإدارة الأدوار للتعاون. راجع وثائق الفرق.

Link to this sectionسرد الفرق#

GET /api/teams

Link to this sectionإنشاء فريق#

POST /api/teams/create

الجسم (Body):

{
    "username": "my-team",
    "fullName": "My Team"
}

Link to this sectionسرد الأعضاء#

GET /api/members

إرجاع أعضاء مساحة العمل الحالية.

Link to this sectionدعوة عضو#

POST /api/members

الجسم (Body):

{
    "email": "user@example.com",
    "role": "editor"
}

Link to this sectionتحديث دور العضو#

PATCH /api/members/{userId}

Link to this sectionإزالة عضو#

DELETE /api/members/{userId}

Link to this sectionنقل الملكية#

POST /api/members/transfer-ownership

Link to this sectionالدعوات#

Link to this sectionقبول الدعوة#

POST /api/invites/accept

Link to this sectionالحصول على معلومات الدعوة#

GET /api/invites/info

معلمات الاستعلام:

Link to this sectionإلغاء الدعوة#

DELETE /api/invites/{inviteId}

Link to this sectionإعادة إرسال الدعوة#

POST /api/invites/{inviteId}/resend

Link to this sectionواجهة برمجة تطبيقات الاستكشاف#

البحث وتصفح مجموعات البيانات والمشاريع العامة التي يشاركها المجتمع. راجع وثائق الاستكشاف.

Link to this sectionالبحث في المحتوى العام#

GET /api/explore/search

معلمات الاستعلام:

Link to this sectionبيانات الشريط الجانبي#

GET /api/explore/sidebar

إرجاع محتوى منسق للشريط الجانبي للاستكشاف.

Link to this sectionواجهات برمجة تطبيقات المستخدم والإعدادات#

إدارة ملفك الشخصي، مفاتيح API، استخدام التخزين، وإعدادات خصوصية البيانات. راجع وثائق الإعدادات.

Link to this sectionالحصول على مستخدم بواسطة اسم المستخدم#

GET /api/users

معلمات الاستعلام:

Link to this sectionمتابعة أو إلغاء متابعة مستخدم#

PATCH /api/users

الجسم (Body):

{
    "username": "target-user",
    "followed": true
}

Link to this sectionالتحقق من توفر اسم المستخدم#

GET /api/username/check

معلمات الاستعلام:

Link to this sectionالإعدادات#

GET /api/settings
POST /api/settings

الحصول على إعدادات ملف تعريف المستخدم أو تحديثها (اسم العرض، السيرة الذاتية، روابط التواصل الاجتماعي، إلخ).

Link to this sectionأيقونة الملف الشخصي#

POST /api/settings/icon
DELETE /api/settings/icon

رفع أو إزالة صورة الملف الشخصي.

Link to this sectionالتهيئة#

POST /api/onboarding

إكمال عملية التهيئة (تعيين منطقة البيانات، اسم المستخدم).

Link to this sectionواجهة برمجة تطبيقات GDPR#

طلب تصدير لجميع بياناتك أو حذف حسابك نهائياً. راجع وثائق الإعدادات.

Link to this sectionالحصول على حالة وظيفة GDPR#

GET /api/gdpr

معلمات الاستعلام:

إرجاع حالة الوظيفة. بالنسبة لوظائف التصدير المكتملة، تتضمن الاستجابة downloadUrl.

Link to this sectionبدء تدفق التصدير أو الحذف#

POST /api/gdpr

الجسم (Body):

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

اختياري لمساحات عمل الفريق:

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Link to this sectionرموز الخطأ#

Link to this sectionالتكامل مع Python#

للتكامل بشكل أسهل، استخدم حزمة Ultralytics Python التي تتعامل مع المصادقة، والتحميلات، وبث المقاييس في الوقت الفعلي تلقائياً.

Link to this sectionالتثبيت والإعداد#

pip install ultralytics

التحقق من التثبيت:

yolo check

Link to this sectionالمصادقة#

yolo settings api_key=YOUR_API_KEY

Link to this sectionاستخدام مجموعات بيانات المنصة#

الإشارة إلى مجموعات البيانات باستخدام معرفات الموارد الموحدة (URIs) ul://:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

تنسيق URI:

Link to this sectionالنشر إلى المنصة#

إرسال النتائج إلى مشروع على المنصة:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

ما الذي تتم مزامنته:

• مقاييس التدريب (في الوقت الفعلي)
• أوزان النموذج النهائية
• مخططات التحقق
• مخرجات وحدة التحكم
• مقاييس النظام

Link to this sectionأمثلة API#

تحميل نموذج من المنصة:

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

تشغيل الاستدلال:

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

تصدير النموذج:

# Export to ONNX
model.export(format="onnx", imgsz=640, half=True)

# Export to TensorRT
model.export(format="engine", imgsz=640, half=True)

# Export to CoreML
model.export(format="coreml", imgsz=640)

التحقق:

metrics = model.val(data="ul://username/datasets/my-dataset")

print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")

Link to this sectionخطافات الويب (Webhooks)#

تستخدم المنصة خطافات ويب داخلية لبث مقاييس التدريب في الوقت الفعلي من حزمة ultralytics Python SDK (التي تعمل على وحدات معالجة الرسومات السحابية أو الأجهزة البعيدة/المحلية) إلى المنصة — مثل الخسارة لكل دورة (epoch)، وmAP، وإحصائيات النظام، وحالة الإكمال. تتم مصادقة خطافات الويب هذه عبر webhookSecret الخاص بـ HMAC والذي يتم توفيره لكل مهمة تدريب، وهي غير مخصصة للاستهلاك من قبل تطبيقات المستخدم.

Link to this sectionالأسئلة الشائعة#

Link to this sectionكيف يمكنني استخدام الترقيم للصفحات (pagination) للنتائج الكبيرة؟#

تستخدم معظم نقاط النهاية معامل limit للتحكم في عدد النتائج التي يتم إرجاعها لكل طلب:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=50"

تدعم نقاط نهاية النشاط (Activity) والمهملات (Trash) أيضاً معامل page للترقيم المستند إلى الصفحات:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

تستخدم نقطة نهاية البحث (Explore Search) معامل offset بدلاً من page، مع حجم صفحة ثابت قدره 20:

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&sort=stars"

Link to this sectionهل يمكنني استخدام API بدون SDK؟#

نعم، جميع الوظائف متاحة عبر REST. تُعد حزمة Python SDK غلافاً مريحاً يضيف ميزات مثل بث المقاييس في الوقت الفعلي والتحميل التلقائي للنماذج. يمكنك أيضاً استكشاف جميع نقاط النهاية بشكل تفاعلي على platform.ultralytics.com/api/docs.

Link to this sectionهل توجد مكتبات عميل لـ API؟#

حالياً، استخدم حزمة Ultralytics Python أو قم بإجراء طلبات HTTP مباشرة. من المخطط توفير مكتبات عميل رسمية للغات أخرى.

Link to this sectionكيف أتعامل مع حدود المعدل (rate limits)؟#

استخدم ترويسة Retry-After من استجابة 429 لانتظار القدر المناسب من الوقت:

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded")

Link to this sectionكيف أجد معرف النموذج أو مجموعة البيانات الخاص بي؟#

يتم إرجاع معرفات الموارد عند إنشاء الموارد عبر API. يمكنك أيضاً العثور عليها في URL الخاص بالمنصة:

https://platform.ultralytics.com/username/project/model-name
                                  ^^^^^^^^ ^^^^^^^ ^^^^^^^^^^
                                  username project   model

استخدم نقاط نهاية القائمة للبحث بالاسم أو التصفية حسب المشروع.