مرجع REST API#

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

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

نظرة عامة على API#

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

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

المصادقة#

تستخدم واجهات برمجة تطبيقات الموارد (Resource APIs) المصادقة عبر مفتاح API، بما في ذلك إدارة فئات مجموعات البيانات وتقسيمها، والنسخ، والتدريب، والتصدير، والنشر، وعمليات قراءة الحساب المدعومة. تدعم نقاط النهاية العامة الوصول المجهول حيثما أشير إلى ذلك. تُستثنى مسارات التطبيق المخصصة للمتصفح فقط.

الحصول على مفتاح API#

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

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

رأس التفويض#

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

Authorization: Bearer YOUR_API_KEY

مثال#

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

عنوان URL الأساسي#

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

https://platform.ultralytics.com/api

حدود المعدل#

تفرض واجهة برمجة التطبيقات (API) حدوداً تعتمد على نافذة منزلقة مدعومة بـ Upstash Redis لكل مفتاح API. تستخدم كل مسار الفئة المطابقة أدناه.

عند تجاوز الحد المسموح به، ترجع واجهة برمجة التطبيقات 429 مع بيانات التعريف الخاصة بإعادة المحاولة:

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

حدود كل مفتاح API#

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

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

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

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

تنسيق الاستجابة#

استجابات النجاح#

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

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

استجابات الخطأ#

{
    "error": "Dataset not found"
}

API مجموعات البيانات#

إنشاء، تصفح، وإدارة مجموعات بيانات الصور المصنفة لتدريب نماذج YOLO. راجع Datasets documentation.

سرد مجموعات البيانات#

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

الحصول على مجموعة بيانات#

GET /api/datasets/{datasetId}

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

مرر username عندما يكون {datasetId} اسماً مختصراً لمجموعة بيانات بدلاً من المعرّف.

إنشاء مجموعة بيانات#

POST /api/datasets

الجسم (Body):

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

الاستجابة:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

تحديث مجموعة بيانات#

PATCH /api/datasets/{datasetId}

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

{
    "name": "Updated Name",
    "description": "New description",
    "metadata": { "location": "factory-2", "reviewed": true },
    "visibility": "public"
}

أرسل كائن metadata فارغاً ({}) لمسح البيانات الوصفية المخصصة. يقتصر كائن البيانات الوصفية المُسلسل على 500,000 حرف، ويقتصر كل مفتاح في المستوى العلوي على 128 حرفاً.

الحصول على البيانات الوصفية لمجموعة البيانات#

GET /api/datasets/{datasetId}/metadata

يعيد كائن البيانات الوصفية المخصصة ومجموعة منسقة من أزواج الحقول/القيم المُدارة بواسطة Ultralytics وقراءة فقط. يتم استبعاد البيانات الوصفية المخصصة عمداً من حمولات مجموعة البيانات العادية. المصادقة والوصول إلى مساحة عمل مجموعة البيانات مطلوبان.

أيقونة مجموعة البيانات#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

قم بتحميل أيقونة WebP بحجم يصل إلى 5 ميغابايت كحقل نموذج متعدد الأجزاء image، أو قم بإزالة الأيقونة الحالية.

حذف مجموعة بيانات#

DELETE /api/datasets/{datasetId}

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

استنساخ مجموعة البيانات#

POST /api/datasets/{datasetId}/clone

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

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

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

تصدير مجموعة البيانات#

GET /api/datasets/{datasetId}/export

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

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

الاستجابة:

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

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

POST /api/datasets/{datasetId}/export

إنشاء لقطة إصدار مرقمة جديدة لمجموعة البيانات. يتطلب هذا صلاحيات محرر (Editor) أو أعلى. يلتقط الإصدار عدد الصور الحالي، وعدد الفئات، وعدد التعليقات التوضيحية، وتوزيع التقسيم، ثم ينشئ ويخزن تصدير NDJSON غير قابل للتغيير.

جسم الطلب:

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

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

الاستجابة:

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

تحديث وصف الإصدار#

PATCH /api/datasets/{datasetId}/export

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

جسم الطلب:

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

الاستجابة:

{
    "ok": true
}

استعادة إصدار مجموعة البيانات#

POST /api/datasets/{datasetId}/restore

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

{
    "version": 2
}

الحصول على إحصائيات الفئة#

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
}

إدارة الفئات#

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

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

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

معرفات الفئات (Class IDs) مرتبطة بالموضع، لذا فإن الدمج ليس متماثلاً (idempotent). أعد جلب مجموعة البيانات قبل المحاولة مرة أخرى.

حذف الفئات:

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

{
    "classIds": [2, 4]
}

إعادة توزيع التقسيمات#

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

إعادة تعيين الصور عشوائياً عبر تقسيمات التدريب، والتحقق، والاختبار. يجب أن يبلغ مجموع النسب المئوية 100.

{
    "train": 80,
    "val": 20,
    "test": 0
}

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

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

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

تجميع الصور#

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

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

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

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
}

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

POST /api/datasets/{datasetId}/predict

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

الجسم (Body):

استيعاب مجموعة البيانات#

POST /api/datasets/ingest

إنشاء مهمة استيعاب مجموعة بيانات لمجموعة بيانات موجودة. يتم تمرير مجموعة بيانات الهدف دائماً كـ datasetId في جسم JSON، وليس في مسار عنوان URL.

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

بالنسبة للأرشيفات المُحَمَّلة، تكون جلسة التحميل مرتبطة مسبقاً بمجموعة البيانات بواسطة assetId المُمرَّر إلى POST /api/upload/signed-url؛ يتحقق الاستيعاب من أن assetId يتطابق مع جسم datasetId. تقوم إدخالات classMapping الاختيارية بربط كل اسم فئة وارد بفهرس فئة حالي يبدأ من الصفر، أو اسم فئة لإعادة استخدامه أو إنشائه، أو null لتخطي الفئة. بالنسبة لعمليات الاستيراد البعيدة لـ sourceUrl، أنشئ مجموعة البيانات أولاً، ثم مرر datasetId الخاص بها للاستيعاب.

النص (أرشيف مرفوع):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

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

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

تستخدم الصور المحلية تدفق تحميل الأرشيف الحالي، بغض النظر عما إذا كان الأرشيف يحتوي على صورة واحدة أو صور متعددة. يجب أن يتطابق المفتاح مع المسار المُطَبَّع داخل الأرشيف، بما في ذلك المجلدات. بالنسبة لعمليات استيراد NDJSON، يمكن أن يحتوي سجل كل صورة بدلاً من ذلك على كائن metadata الخاص به. يحظى metadata الخاص بسجل معين بالأولوية على إدخال imageMetadata المتطابق.

البيانات الوصفية هي بتنسيق JSON وتدعم القيم المتداخلة. تقتصر مسارات الأرشيف على 1,024 حرفاً، ومفاتيح البيانات الوصفية ذات المستوى الأعلى على 128 حرفاً، وكل كائن بيانات وصفية على 500,000 حرف متسلسل. يقتصر خريطة imageMetadata الكاملة، أو البيانات الوصفية الفعالة المدمجة عبر استيراد NDJSON، أيضاً على 500,000 حرف متسلسل. يتم تضمين هذه القيود في interactive OpenAPI schema.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

النص (أرشيف عن بُعد أو NDJSON):

{
    "datasetId": "dataset_abc123",
    "sourceUrl": "https://example.com/my-dataset.zip"
}

النص البرمجي (للإدخال اللاحق، استيراد التسميات):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

الاستجابة:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

صور مجموعة البيانات#

سرد الصور#

GET /api/datasets/{datasetId}/images

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

الحصول على الصور المحددة#

POST /api/datasets/{datasetId}/images

يعيد نفس شكل الصورة لما يصل إلى 1000 معرف صورة مقدم. يقبل نفس عناصر التحكم في الرابط والاستعلام عن التصنيفات كما في عملية القائمة.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

الحصول على روابط الصور الموقعة#

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

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

حذف صورة#

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

الحصول على ملصقات الصور#

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

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

تحديث ملصقات الصور#

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] }
    ]
}

عمليات الصور الجماعية#

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

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

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

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

API المشاريع#

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

سرد المشاريع#

GET /api/projects

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

الحصول على مشروع#

GET /api/projects/{projectId}

إنشاء مشروع#

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",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

تحديث مشروع#

PATCH /api/projects/{projectId}

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

{
    "metadata": { "department": "research", "program": "inspection" }
}

أرسل كائن metadata فارغاً ({}) لمسحه. تستخدم البيانات الوصفية للمشروع نفس حدود مفتاح المستوى العلوي البالغة 128 حرفاً وحدود الكائن المُسلسل البالغة 500,000 حرف مثل بيانات مجموعة البيانات الوصفية.

الحصول على البيانات الوصفية للمشروع#

GET /api/projects/{projectId}/metadata

يعيد كائن البيانات الوصفية المخصصة وأزواج الحقول/القيم المُدارة بواسطة Ultralytics ذات القراءة فقط. المصادقة والوصول إلى مساحة عمل المشروع مطلوبان.

حذف مشروع#

DELETE /api/projects/{projectId}

يحذف المشروع حذفاً ناعماً (يُنقل إلى trash).

استنساخ مشروع#

POST /api/projects/{projectId}/clone

يقوم بنسخ مشروع مساحة عمل عام، مملوك، أو قابل للتعديل ونماذجه إلى حسابك أو مساحة عملك. يقبل جسم JSON اختياري تجاوزات name، slug، description، visibility، license، ووجهة owner.

أيقونة المشروع#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

قم بتحميل أيقونة WebP بحجم يصل إلى 5 ميغابايت كحقل نموذج متعدد الأجزاء image، أو قم بإزالة الأيقونة الحالية.

API النماذج#

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

سرد النماذج#

GET /api/models

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

سرد النماذج المكتملة#

GET /api/models/completed

يعيد ما يصل إلى 1,000 نموذج بأوزان قابلة للاستخدام عبر جميع المشاريع للتدريب والنشر. مرر owner لمساحة عمل.

الحصول على نموذج#

GET /api/models/{modelId}

إنشاء نموذج#

POST /api/models

جسم JSON:

تحديث نموذج#

PATCH /api/models/{modelId}

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

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

أرسل كائن metadata فارغاً ({}) لمسحه. بيانات النموذج الوصفية المخصصة منفصلة عن معلومات النموذج المملوكة للتدريب، وتفاصيل البيئة، ووسائط التدريب، وتستخدم نفس حدود الكائن المُسلسل ومفاتيح المستوى العلوي مثل بيانات مجموعة البيانات الوصفية.

الحصول على البيانات الوصفية للنموذج#

GET /api/models/{modelId}/metadata

يعيد كائن البيانات الوصفية المخصصة وأزواج الحقول/القيم المُدارة بواسطة Ultralytics ذات القراءة فقط. المصادقة والوصول إلى مساحة عمل النموذج مطلوبان.

حذف نموذج#

DELETE /api/models/{modelId}

تنزيل ملفات النموذج#

GET /api/models/{modelId}/files

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

استنساخ نموذج#

POST /api/models/{modelId}/clone

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

الجسم (Body):

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

تتبع التنزيل#

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

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

تشغيل الاستنتاج#

POST /api/models/{modelId}/predict

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

نموذج Multipart:

قم بتوفير إما file أو source. الحد الأقصى لحجم التحميل هو 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

الاستجابة:

تحتوي الاستجابات على shape لكل صورة، speed، results، وبيانات خريطة بكسل كثيفة اختيارية (خريطة فئة دلالية، أو خريطة عمق حيث يكون depth = pixel × max / divisor — مقسوم 255 لخريطة 8 بت الافتراضية، 65535 مع bits=12|16)، بالإضافة إلى metadata مع عدد الصور، توقيت الوظيفة، المهمة، وإصدارات الخدمة. لا يتم إرجاع مسارات النموذج الداخلية أبداً.

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

API التدريب#

أطلق تدريب YOLO على وحدات معالجة الرسوميات السحابية (26 نوع وحدة معالجة رسوميات من RTX 2000 Ada إلى B300) وراقب التقدم في الوقت الفعلي. راجع Cloud Training documentation.

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

بدء التدريب#

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

الحصول على توفر GPU#

GET /api/training/gpu-availability

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

الحصول على حالة التدريب#

GET /api/models/{modelId}/training

يعيد حالة وظيفة التدريب الحالية، والمقاييس، والتقدم، والتوقيت، وتفاصيل GPU، والأخطاء. يمكن الوصول إلى المشاريع العامة بدون مصادقة؛ وتتطلب المشاريع الخاصة والمشتركة مفتاح API مع صلاحية الوصول.

إلغاء التدريب#

DELETE /api/models/{modelId}/training

ينهي مثيل الحوسبة قيد التشغيل ويضع علامة على الوظيفة كملغاة.

API النشر#

انشر النماذج على نقاط نهاية استدلال مخصصة مع عمليات فحص الحالة والمراقبة. تستخدم عمليات النشر الجديدة التحجيم إلى الصفر افتراضياً، وتقبل واجهة برمجة التطبيقات كائن resources اختيارياً. راجع Endpoints documentation.

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

سرد عمليات النشر#

GET /api/deployments

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

إنشاء نشر#

POST /api/deployments

الجسم (Body):

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

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

الحصول على نشر#

GET /api/deployments/{deploymentId}

حذف نشر#

DELETE /api/deployments/{deploymentId}

بدء نشر#

POST /api/deployments/{deploymentId}/start

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

إيقاف نشر#

POST /api/deployments/{deploymentId}/stop

إيقاف تلبية الطلبات عن طريق تعيين الحد الأدنى والحد الأقصى لنسخ الخدمة إلى الصفر.

فحص الصحة#

GET /api/deployments/{deploymentId}/health

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

تشغيل الاستدلال على النشر#

POST /api/deployments/{deploymentId}/predict

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

نموذج Multipart:

قم بتوفير إما file أو source. تستخدم الاستجابة نفس عقد الصورة والبيانات الوصفية كتنبؤ النموذج ولا ترجع أبداً مسار النموذج الداخلي.

الحصول على المقاييس#

GET /api/deployments/{deploymentId}/metrics

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

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

الحصول على السجلات#

GET /api/deployments/{deploymentId}/logs

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

API التصدير#

تحويل النماذج إلى تنسيقات مُحَسَّنة مثل ONNX، TensorRT، CoreML، و LiteRT لنشر الحافة. راجع Deploy documentation.

سرد عمليات التصدير#

GET /api/exports

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

إنشاء تصدير#

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

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

استخدم وسيط format من جدول التصدير المشترك أدناه. PyTorch هو تنسيق المصدر وليس هدف تصصدير لواجهة برمجة التطبيقات.

الحصول على حالة التصدير#

GET /api/exports/{exportId}

إلغاء التصدير#

DELETE /api/exports/{exportId}

تتبع تنزيل التصدير#

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

API النشاط#

عرض موجز للإجراءات الحديثة على حسابك — عمليات التشغيل، التحميلات، والمزيد. راجع Activity documentation.

سرد النشاط#

GET /api/activity

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

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

POST /api/activity/mark-seen

الجسم (Body):

{
    "all": true
}

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

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

مرر وسيط الاستعلام الاختياري owner لتحديد الأحداث في مساحة عمل.

أرشفة الأحداث#

POST /api/activity/archive

الجسم (Body):

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

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

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

مرر وسيط الاستعلام الاختياري owner لأرشفة أو استعادة أحداث مساحة العمل.

API سلة المهملات#

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

سرد سلة المهملات#

GET /api/trash

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

استعادة العنصر#

POST /api/trash

الجسم (Body):

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

حذف العنصر نهائياً#

DELETE /api/trash

الجسم (Body):

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

إفراغ سلة المهملات#

DELETE /api/trash/empty

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

API الفوترة#

تحقق من رصيد رصيدك، استخدام الخطة، وسجل المعاملات. راجع Billing documentation.

تقبل نقاط نهاية الرصيد والمعاملات وسيط استعلام اختياري owner مع اسم مستخدم مالك مساحة العمل.

الحصول على الرصيد#

GET /api/billing/balance

الاستجابة:

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

الحصول على ملخص الاستخدام#

GET /api/billing/usage-summary

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

الحصول على المعاملات#

GET /api/billing/transactions

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

تتضمن المعاملات حقول دفتر الأستاذ الموجهة للعملاء مثل المبلغ، والرصيد الناتج، والتاريخ، وسياق النموذج الاختياري، ورابط الإيصال. لا يتم إرجاع الملاحظات الداخلية، أو معرفات الدفع/الاسترداد الخاصة بـ Stripe، أو مفاتيح التماثل (idempotency keys).

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

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

الحصول على معلومات التخزين#

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"
            }
        ]
    }
}

تكاملات التخزين السحابي#

اتصل وتصفح تكاملات تخزين GCS، أو S3، أو Azure Blob للقراءة فقط:

GET /api/integrations/buckets
POST /api/integrations/buckets
POST /api/integrations/buckets/discover
GET /api/integrations/buckets/{id}/objects

تقبل جميع العمليات الأربع وسيط الاستعلام الاختياري owner لمساحة عمل. يقبل تصفح الكائنات أيضاً target المطلوب بالإضافة إلى وسائط الاستعلام الاختيارية prefix ومزود الخدمة cursor. تستخدم أجسام طلبات الاتصال والاكتشاف مخططات بيانات اعتماد المزود في مرجع OpenAPI التفاعلي؛ لا يتم إرجاع بيانات الاعتماد أبداً.

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

قم بتحميل الملفات مباشرة إلى التخزين السحابي باستخدام عناوين URL الموقعة لنقل سريع وموثوق. يؤدي إكمال تحميل النموذج إلى إرفاق أوزانه. يؤدي إكمال تحميل أرشيف مجموعة البيانات إلى تسجيل الجلسة؛ مرر هذا sessionId إلى POST /api/datasets/ingest لبدء المعالجة. راجع Data documentation.

الحصول على عنوان URL موقع للرفع#

POST /api/upload/signed-url

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

الجسم (Body):

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

الاستجابة:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

إكمال الرفع#

POST /api/upload/complete

أبلغ المنصة بأن تحميل الملف قد اكتمل. بالنسبة للنماذج، يؤدي هذا إلى إرفاق الأوزان المُحَمَّلة. بالنسبة لأرشيفات مجموعات البيانات، يتحقق هذا من جلسة التحميل ويسجلها؛ استدعِ POST /api/datasets/ingest بعد ذلك لبدء معالجة مجموعة البيانات.

الجسم (Body):

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

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

استيراد مجموعات البيانات من خدمات الطرف الثالث. راجع Integrations documentation.

معاينة استيراد Roboflow#

POST /api/integrations/roboflow/preview

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

استيراد من Roboflow#

POST /api/integrations/roboflow/import

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

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

إدارة مفاتيح واجهة برمجة التطبيقات الخاصة بك للوصول البرمجي. راجع API Keys documentation.

سرد مفاتيح API#

GET /api/api-keys

تتلقى العميلات المصادقة بمفتاح واجهة برمجة التطبيقات بيانات التعريف للمفتاح، ولا تتلقى أبداً قيم المفاتيح الحالية مفكوكة التشفير. يتم إرجاع المفتاح المُنشأ حديثاً مرة واحدة بواسطة POST /api/api-keys.

مرر وسيط الاستعلام الاختياري owner لإدارة المفاتيح لمساحة عمل تتمتع فيها بحق الوصول كمحرر.

إنشاء مفتاح API#

POST /api/api-keys

الجسم (Body):

{
    "name": "training-server"
}

حذف مفتاح API#

DELETE /api/api-keys

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

مثال:

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

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

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

سرد الفرق#

GET /api/teams

إنشاء فريق#

POST /api/teams/create

الجسم (Body):

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

سرد الأعضاء#

GET /api/members

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

دعوة عضو#

POST /api/members

الجسم (Body):

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

تحديث دور العضو#

PATCH /api/members/{userId}

إزالة عضو#

DELETE /api/members/{userId}

نقل الملكية#

POST /api/members/transfer-ownership

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

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

البحث في المحتوى العام#

GET /api/explore/search

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

بيانات الشريط الجانبي#

GET /api/explore/sidebar

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

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

إدارة ملفك الشخصي، مفاتيح واجهة برمجة التطبيقات، استخدام التخزين، ومساحات عمل الفريق. راجع Settings documentation.

ملخص الحساب#

GET /api/account/summary

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

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

GET /api/users

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

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

PATCH /api/users

الجسم (Body):

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

التحقق من توفر اسم المستخدم#

GET /api/username/check

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

الإعدادات#

GET /api/settings
POST /api/settings

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

أيقونة مساحة العمل#

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

قم بتحميل أيقونة ملف شخصي/مساحة عمل WebP بحجم يصل إلى 5 ميغابايت كحقل نموذج متعدد الأجزاء image، أو قم بإزالتها. مرر owner الاختياري لمساحة عمل فريق.

التكامل مع Python#

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

التثبيت والإعداد#

pip install "ultralytics>=8.4.104"

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

yolo check

المصادقة#

yolo login YOUR_API_KEY

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

الإشارة إلى مجموعات البيانات بمعرّفات URI من نوع 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:

النشر إلى المنصة#

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

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",
)

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

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

أمثلة 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, quantize=16)

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

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

التحقق:

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

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

الأسئلة الشائعة#

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

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

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

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

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

تستخدم نقطة نهاية البحث واستكشاف البيانات offset بدلاً من page، مع حجم صفحة ثابت يبلغ 20:

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

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

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

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

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

كيف أتعامل مع حدود المعدل (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 RuntimeError("Rate limit exceeded")

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

يتم إرجاع معرفات الموارد (Resource IDs) بواسطة استجابات واجهة برمجة التطبيقات للإنشاء والقرد والعرض. تستخدم عناوين URL لصفحات المنصة أسماءً قابلة للقراءة للبشر وليست معرفات قاعدة بيانات:

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

استخدم نقاط نهاية القائمة للبحث عن _id المقابل لنموذج، أو مجموعة بيانات، أو مشروع، أو نشر، أو مورد آخر.