مرجع REST API#

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

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

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

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

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

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

المصادقة#

تتطلب معظم نقاط النهاية مفتاح API. كما تقبل نقاط النهاية التي تعرض محتوى عامًا — مثل قراءة مجموعة بيانات أو مشروع أو نموذج عام، وسرد صور مجموعة بيانات عامة، وتشغيل الاستدلال على نموذج عام، أو البحث في الاستكشاف — الطلبات المجهولة أيضًا، وتعيد ببساطة مزيدًا من النتائج عند توفير مفتاح.

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

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

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

رأس التفويض#

أدرِج مفتاح API الخاص بك باعتباره رمز bearer:

Authorization: Bearer YOUR_API_KEY

مثال#

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

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

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

https://platform.ultralytics.com/api

مسارات الموارد#

تُعنون الموارد باستخدام الأسماء المقروءة بشريًا نفسها التي تظهر في عناوين URL للمنصة، وليس باستخدام معرّفات قاعدة البيانات:

• {owner} هو اسم مستخدم شخصي أو معرّف مساحة عمل لفريق: من 4 إلى 32 محرفًا، بأحرف أبجدية رقمية صغيرة مع واصلات مفردة بين المقاطع.
• تتبع {dataset} و{project} و{model} و{deployment} النمط نفسه ذي الأحرف الصغيرة والواصلات، وبحد أقصى 128 محرفًا.
• {imageId} و{exportId} معرّفان سداسيان عشريان بطول 24 محرفًا، وتُرجعهما API.
• يؤدي تغيير اسم مورد من خلال PATCH إلى تغيير name المعروض واسم URL معًا، كما يعيد الرد اسم URL الحالي حتى تتمكن من مواصلة استخدامه.

حدود معدل الطلبات#

تفرض API حدودًا ضمن نافذة منزلقة لكل مفتاح API. تندرج كل route ضمن فئة واحدة، ولكل فئة عداد مستقل، لذا لا تستهلك 20 طلبات تنبؤ حصتك الافتراضية.

لدى مسارات Platform المخصصة للمتصفح فقط، مثل الدفع عند إتمام الفوترة وإدارة الفريق، حدودها الخاصة التي لا تنطبق على حركة المرور باستخدام مفاتيح API.

عند تقييد المعدل، تُرجع API 429 مع الرأسين ونص JSON:

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

{
    "error": "Rate limit exceeded",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

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

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

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

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

الاستجابات عبارة عن كائنات JSON تحتوي على حقول خاصة بالموارد. ولا يوجد غلاف عام: إذ تعيد نقاط النهاية الخاصة بالسرد مجموعة مسماة إلى جانب أعدادها، بينما تعيد عمليات التعديل المعرّفات التي تغيّرت.

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

تتضمن الاستجابات الحاملة للبيانات أيضًا region (us أو eu أو ap)، وهي منطقة التخزين الخاصة بمساحة العمل.

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

كل استجابة خطأ هي كائن JSON يحتوي على رسالة error:

{
    "error": "Dataset not found"
}

التقسيم إلى صفحات#

يعتمد نمط ترقيم الصفحات على المجموعة:

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

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

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

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

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

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

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

الاستجابة:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

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

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

يعيد كائن مجموعة البيانات الكامل ضمن مفتاح dataset، بما في ذلك classNames وsplits وversions وsource وكائن metadata المحدد من قِبل المستخدم.

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

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

النص:

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

ترجع الاستجابة الـ slug الخاص بـ dataset الذي تم إنشاؤه بالفعل، لذا اقرأه مرة أخرى قبل التحميل ما لم تقم بتعيين requireExactSlug.

الاستجابة (201):

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

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

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

النص (تحديث جزئي):

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

الحقول المقبولة: name وdescription وvisibility وmetadata وtags وclassNames وclassColors وformat وtask وlicense وiconColor وiconLetter وstarred. أرسل كائن metadata فارغًا ({}) لمسح البيانات الوصفية المخصصة. يقتصر طول مفاتيح البيانات الوصفية على 128 محرفًا، ويقتصر الكائن المتسلسل على 500,000 محرف.

الاستجابة:

{
    "success": true,
    "dataset": "warehouse-safety"
}

يؤدي تغيير الاسم إلى تغيير اسم عنوان URL، لذا استخدم قيمة dataset المُعادة في الطلبات اللاحقة.

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

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

ينقل مجموعة البيانات إلى المهملات، حيث يمكن استردادها لمدة 30 يومًا.

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

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

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

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

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

الاستجابة (201): id وowner وdataset وname وimageCount وclassCount وregion. تُعيد مجموعات البيانات المدعومة بمصدر تخزين متصل 409 لأن ملفاتها لا تُنسخ.

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

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

يعيد عنوان URL موقّعًا لتنزيل NDJSON. احذف v لتصدير الحالة الحالية لمجموعة البيانات، مع إعادة استخدام التصدير المخزّن مؤقتًا عندما لا يكون قد حدث أي تغيير منذ إنشائه.

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

الاستجابة:

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

يؤدي طلب إصدار محدد إلى إعادة downloadUrl وversion بدلًا من cached.

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

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

ينشئ لقطة مرقمة غير قابلة للتغيير من مجموعة البيانات ويخزّن تصدير NDJSON الخاص بها. يتطلب صلاحية المحرر.

النص (اختياري):

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

الاستجابة:

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

تكون قيمة reused هي true عندما لا تتغير مجموعة البيانات منذ الإصدار السابق وتُعاد تلك اللقطة بدلًا منه.

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

PATCH /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

النص:

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

الاستجابة: {"ok": true}

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

POST /api/datasets/{owner}/{dataset}/restore

Python SDK: client.datasets.restore(owner, dataset, version=...)

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

النص:

{
    "version": 2
}

الاستجابة: {"version": 2, "imageCount": 1000}

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

GET /api/datasets/{owner}/{dataset}/class-stats

Python SDK: client.datasets.class_stats(owner, dataset)

يعيد أعداد التعليقات التوضيحية لكل فئة، ومدرجات الصور والتعليقات التوضيحية، وخرائط التمثيل الحراري. تُؤخذ عينة من مجموعات البيانات الكبيرة، وفي هذه الحالة يوضح sampleSize عدد الصور التي ساهمت.

الاستجابة (مختصرة):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "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", "forklift"],
    "cached": true,
    "sampleSize": null
}

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

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

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

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

حذف الفئات (تُحذف تعليقاتها التوضيحية وتتحرك معرّفات الفئات المتبقية إلى الأسفل):

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

تعيد العمليتان success، وclassNames وclassColors المحدّثتين، وملخصًا للتغييرات التي حدثت (mergedClassIds وtargetClassId، أو deletedClassIds وdeletedAnnotations).

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

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

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

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

الاستجابة: success، وأعداد splits الناتجة، وmodified (عدد الصور المنقولة).

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

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK: client.datasets.embeddings(owner, dataset) وclient.datasets.create_embeddings(owner, dataset) وclient.datasets.delete_embeddings(owner, dataset)

يعيد GET ملخص التحليل (analyzedAt وembeddingsCount وlatestImageAt وactiveJob). يضع POST تحليل التضمينات في قائمة الانتظار ويعيد 202 مع jobId. يلغي DELETE المهمة النشطة ويعيد معرّف المهمة الملغاة أو null.

تجميع الصور#

GET /api/datasets/{owner}/{dataset}/images/clustering

Python SDK: client.datasets.clustering(owner, dataset)

يعيد تخطيط UMAP ثنائي الأبعاد من تحليل مكتمل، مع ترقيم الصفحات باستخدام offset وlimit (الافتراضي والحد الأقصى 50,000). يحتوي كل إدخال على id وumapX وumapY وsplit وclassIds وwidth وheight وbytes وlabelCount وmissing.

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

GET /api/datasets/{owner}/{dataset}/models

Python SDK: client.datasets.models(owner, dataset)

الاستجابة:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

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

GET /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.images(owner, dataset)

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

الاستجابة:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04.jpg",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

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

POST /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

يعيد شكل الصورة نفسه لما يصل إلى 1,000 من معرّفات الصور المقدّمة، ويقبل معاملات الاستعلام نفسها الخاصة بالتصفية وعنوان URL مثل عملية القائمة.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

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

POST /api/datasets/{owner}/{dataset}/ingest

Python SDK: client.datasets.ingest(owner, dataset, body=...)

يعالج عملية رفع مكتملة، أو أرشيفًا بعيدًا، أو مصدر تخزين متصلًا، في مجموعة بيانات موجودة. قدّم مصدرًا واحدًا بالضبط:

ترتبط جلسات الرفع بمجموعة بيانات بواسطة assetId المُمرَّر إلى POST /api/upload/signed-url، ويرفض الإدخال جلسة تنتمي إلى مجموعة بيانات مختلفة.

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

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

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

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

النص (استيراد التسميات أثناء إدخال لاحق):

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

النص (إرفاق البيانات الوصفية لكل صورة):

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

يجب أن تتطابق مفاتيح البيانات الوصفية مع المسار المُطبَّع داخل الأرشيف، بما في ذلك المجلدات. في عمليات استيراد NDJSON، يمكن لكل سجل أن يحمل كائن metadata خاصًا به، وله الأولوية على إدخال imageMetadata المطابق. تقتصر مسارات الأرشيف على 1,024 محرفًا، ومفاتيح البيانات الوصفية ذات المستوى الأعلى على 128 محرفًا، وكل كائن بيانات وصفية — وكذلك خريطة imageMetadata بأكملها — على 500,000 محرف مُسلسل.

الاستجابة (201):

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/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

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
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/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

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

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

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

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

يعيد كائن metadata (مخصص، يحدده المستخدم)، ومصفوفة properties (اسم الملف، التجزئة، الأبعاد، التقسيم، الأعداد، الطوابع الزمنية)، وlabels، وclassNames الخاصة بمجموعة البيانات.

تحديث صورة#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, 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] }
    ]
}

النص (البيانات الوصفية):

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

حذف صورة#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

يحذف صورة واحدة وتعليقاتها التوضيحية نهائيًا.

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

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

يشغّل استدلال YOLO على الصورة ويعيد التعليقات التوضيحية المتوقعة. لا يحفظها — اكتب النتائج مرة أخرى باستخدام PATCH /api/images/{imageId} عندما تقتنع بها.

الاستجابة: success، وpredictions (كائنات التعليقات التوضيحية)، وmodelUsed، وinferenceTime. يعيد النموذج الذي لا تتطابق فئاته مع مجموعة البيانات 422.

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

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK: client.datasets.create_batch(owner, dataset, model_id=...)

يحفظ إصدار مجموعة بيانات، ثم يُدرج تشغيلاً في قائمة الانتظار يقوم بتسمية الصور غير المسمّاة في مجموعة البيانات باستخدام النموذج ويُرجع 202. يقبل جسم الطلب نفس حقول modelId وconfidence وiou الخاصة بنقطة نهاية الصورة الواحدة، بالإضافة إلى includeAnnotated (الافتراضي هو false) لتسمية الصور التي تحتوي بالفعل على تسميات أيضاً، ومصفوفة اختيارية classMapping تُحدد فهرس فئة مجموعة البيانات لكل فئة من فئات النموذج، أو null لتخطي ذلك. لا تُغيَّر التسميات الموجودة أبداً، ويتم فوترة التشغيل ل مقابل الصور التي يُعالجها بالفعل. يعني 402 أن الرصيد لا يغطي التقدير، ويعني 409 أن مجموعة البيانات ليست جاهزة، أو ليس لديها صور متبقية للتسمية، أو لديها بالفعل تشغيل قيد التنفيذ، ويعني 422 أن مجموعة البيانات ليس لها فئات: أنشئ الفئات باستخدام نقطة نهاية الفئات قبل استدعاء نقطة النهاية هذه، وهو ما تقوم به خطوة تعيين الفئات في التطبيق قبل بدء التشغيل.

يُرجع GET على نفس المسار (client.datasets.batch(owner, dataset)) التشغيل قيد التنفيذ وتقدمه، أو آخر تشغيل مُكتمل حتى يتم تجاهله؛ يُلغي DELETE (client.datasets.delete_batch(owner, dataset)) تشغيلاً قيد التنفيذ أو يُسوي الفواتير ويتجاهل الملخص المُكتمل.

نقل الصور دفعة واحدة#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

ينقل ما يصل إلى 1,000 صورة من مجموعة بيانات إلى تقسيم مختلف.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

تعيد تعارضات أسماء الملفات أو المحتوى 409 إلى أن تختار conflictPolicy موحّدًا على مستوى الدفعة من skip أو keep_both أو replace. وتُبلغ الاستجابة عن modifiedCount وskippedCount وtargetSplit.

حذف الصور دفعة واحدة#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

يحذف ما يصل إلى 1,000 صورة من مجموعة بيانات واحدة ويعيد deletedCount وdeletedImageIds.

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

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

يعيد عناوين URL موقعة مؤقتة لما يصل إلى 100 معرّف صورة من مجموعة بيانات واحدة.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

الاستجابة: urls وthumbnails، وكلاهما مفهرس بمعرّف الصورة.

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

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

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

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

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

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

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

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

إنشاء مشروع#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

الاستجابة (201): id وowner وproject وregion.

تحديث مشروع#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

الحقول المقبولة: name وdescription وvisibility وmetadata وtags وlicense وarchived وiconColor، وiconLetter وviewPreferences وstarred.

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

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

حذف المشروع#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

ينقل المشروع ونماذجه إلى سلة المهملات، مع إعادة cascadedModels.

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

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

ينسخ مشروعًا يمكن الوصول إليه ونماذجه المكتملة. يقبل النص الاختياري project وname وdescription، وvisibility وlicense ووجهة owner.

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

أدِر نماذج YOLO المدرَّبة — اعرض المقاييس، ونزّل الأوزان، وشغّل الاستدلال، وراقب التدريب. راجع وثائق النماذج.

سرد النماذج في مشروع#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

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

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

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

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

تتضمن الاستجابة الافتراضية كائن model — الحالة، والمهمة، والمقاييس، وtrainArgs، وtrainResults، وclassNames، وcomputeCost، وmetadata، وغير ذلك — بالإضافة إلى isOwner.

إنشاء نموذج#

POST /api/models

Python SDK: client.models.create(body=...)

ينشئ سجلًا لنموذج غير مدرَّب يمكنك إرفاق أوزان به أو تدريبه.

الاستجابة (201): id وowner وproject وmodel وregion.

تحديث نموذج#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

تشمل الحقول المقبولة name، وdescription، وcolor، وmetadata، وstatus، وlicense، وdatasetSlug، وtrainArgs، وtrainResults، وepochs، وbestEpoch، وbestFitness، وversion، وtrainingError، وstarred. تمرير projectId بمفرده ينقل النموذج إلى مشروع آخر لنفس المالك؛ وترجع الاستجابة slug الخاص بالنموذج في الوجهة، وrenamed: true عندما يكون هذا الـ slug محجوزاً هناك بالفعل، و409 بينما لا يزال النموذج قيد التدريب.

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

إن metadata المخصص منفصل عن الحقول المملوكة للتدريب مثل trainArgs وenvironment وtrainResults، ويستخدم حدود الحجم نفسها الخاصة بالبيانات الوصفية لمجموعة البيانات.

حذف النموذج#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

ينقل النموذج إلى سلة المهملات لمدة 30 يومًا.

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

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

يعيد عناوين URL موقّعة قصيرة الأجل لأوزان النموذج.

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

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

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

ينسخ نموذجًا يمكن الوصول إليه إلى مشروع موجود.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

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

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

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

نموذج متعدد الأجزاء:

وفّر إما file أو source. تقبل نماذج العمق أيضًا bits (8 أو 12 أو 16) لتحديد تكميم خريطة العمق بصيغة PNG. تُرجع الطلبات التي تتجاوز حدود الإدخال للخدمة 413.

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

الاستجابة:

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

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

التحقق من تقدم التدريب#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

تُرجع job التي تتضمن الحالة، وتقدم الحِقبة، والتوقيت، وتفاصيل الحوسبة، ووسائط التدريب، ومقاييس الحِقب، وتفاصيل الأخطاء الآمنة، أو null عندما لا يكون النموذج قد دُرّب قط. يمكن قراءة النماذج في المشاريع العامة دون مصادقة.

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

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

ينهي مثيل الحوسبة قيد التشغيل ويضع علامة على المهمة باعتبارها ملغاة. تُرجع 409 عندما لا يعود التدريب نشطًا.

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

شغّل تدريب YOLO على وحدات GPU السحابية وراقب التقدم في الوقت الفعلي. راجع وثائق التدريب السحابي.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../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

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

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

تُرجع حالة المخزون الحالية مرتبة حسب معرّف GPU. وهي عامة ولا تتطلب مصادقة؛ مرّر managed=true لتضمين سعة التدريب المُدارة، التي تتطلب مفتاح API.

بدء التدريب#

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

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

الاستجابة:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

يُرجع التدريب 402 عندما يكون رصيدك من الاعتمادات منخفضًا جدًا، و503 عندما لا تتوفر سعة لوحدة GPU المطلوبة.

واجهة برمجة تطبيقات التصدير#

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

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

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

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

إنشاء عملية تصدير#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

الاستجابة (201): id وformat وstatus (queued أو running) وgpuType وregion. تُرجع عملية تصدير مكافئة قيد التنفيذ بالفعل 409.

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

استخدم الوسيط format من جدول التصدير المشترك أدناه. يُعد PyTorch تنسيق المصدر، وليس هدفًا لتصدير API.

يفترض nms=None المخرجات الخام لـ NMS الخارجي. قم بتعيين nms=False لتحديد رأس متاح خالٍ من NMS؛ وتتراجع التنسيقات غير المدعومة إلى مسار إخراجها الأصلي. وتحدد مُدخلات nms أعلاه التنسيقات التي يمكنها تضمين NMS باستخدام nms=True.

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

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

تُرجع الكائن export الذي يتضمن status وformat وargs وgpuType والطوابع الزمنية، وبمجرد الاكتمال، كائن file الذي يتضمن size وdownloadUrl وdownloadFilename.

إلغاء عملية التصدير أو حذفها#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

يلغي عملية تصدير نشطة أو يحذف عملية مكتملة وملفها. تُبلغ الاستجابة بما حدث:

{
    "success": true,
    "action": "cancelled"
}

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

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

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action 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/{owner}

Python SDK: client.deployments.list(owner)

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

يجب على المتصلين المجهولين التصفية حسب نموذج عام واحد؛ ويتطلب سرد مساحة عمل كاملة المصادقة.

إنشاء عملية نشر#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

النص:

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

الاستجابة (201): id وdeployment وstatus (creating) وmessage وregion.

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

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

تُرجع الكائن deployment الذي يتضمن status وstatusMessage وregion وserviceUrl وresources.

بدء عملية نشر أو إيقافها أو استبدالها#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

يحدد حقل action واحد العملية:

{ "action": "start" }

يؤدي الاستبدال إلى نشر مراجعة جديدة مع الحفاظ على معرّف النشر والمنطقة وعنوان URL لنقطة النهاية؛ وتظل المراجعة الحالية قيد التشغيل إذا فشل النشر. يجب أن يكون النموذج البديل نموذجًا مكتملًا بأوزان يمكن لمفتاحك الوصول إليها. تُرجع العمليات المكتملة 200 مع status وready أو stopped؛ أما العمليات التي لا تزال قيد النشر فتُرجع 202 مع deploying أو stopping.

حذف عملية نشر#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

يزيل نقطة نهاية الاستدلال نهائيًا.

فحص الحالة#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

يرسل إشارات اختبارية إلى نقطة النهاية ويهيئها، ويُرجع healthy وlatencyMs ورمز status من المنبع.

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

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

يوجّه صورة أو فيديو عبر نقطة النهاية المخصصة. تتطابق عقود الطلب والاستجابة مع استدلال النموذج.

نموذج متعدد الأجزاء:

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

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

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

تتضمن الاستجابة الكاملة summary (إجماليات الطلبات، ومعدل الأخطاء، ومتوسط زمن الاستجابة وp50/p95/p99) وtimeSeries (الطلبات، والأخطاء، وزمن الاستجابة، ووحدة CPU، والذاكرة، وعدد المثيلات). وتُرجع استجابة المخطط المصغر requests24h وtotalRequests وerrorRate وavgLatencyMs.

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

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

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

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

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

سرد محتويات سلة المهملات#

GET /api/trash

Python SDK: client.lifecycle.trash()

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

تتضمن الاستجابة items (وكل منها يتضمن daysRemaining) وtotal وpage وlimit وtotalPages، بالإضافة إلى summary الذي يتضمن الإجماليات حسب النوع.

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

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

تؤدي استعادة مشروع أيضًا إلى استعادة النماذج التي نُقلت إلى سلة المحذوفات معه، ويُبلغ عنها باعتبارها restoredModels.

الحذف النهائي#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

احذف عنصرًا واحدًا:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

أو أفرغ سلة المحذوفات بأكملها:

{
    "all": true
}

تُبلغ الاستجابة عن deletedCount، بالإضافة إلى cascadedModels وsurvivingDeployments عند الاقتضاء.

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

حمّل الملفات مباشرةً إلى التخزين السحابي باستخدام عناوين URL موقعة. يؤدي إكمال تحميل نموذج إلى إرفاق أوزانه؛ أما إكمال تحميل أرشيف مجموعة بيانات فيسجل الجلسة، ثم تمررها إلى إدخال مجموعة البيانات. راجع وثائق البيانات.

الحصول على عنوان URL موقّع للتحميل#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

النص:

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

الاستجابة:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z",
    "headers": { "x-goog-if-generation-match": "0" }
}

قم بتحميل الملف بطلب PUT إلى uploadUrl، باستخدام نفس Content-Type الذي أعلنته وكل ترويسة يتم إرجاعها في headers. عناوين URL لتحميل مجموعة البيانات صالحة لمدة 12 ساعة ومخصصة للإنشاء فقط: طلب PUT ثانٍ إلى نفس عنوان URL يرجع 412، وطلب PUT بدون الترويسات المُرجَعة يرجع 400.

إكمال التحميل#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

الاستجابة: success وكائن file مع size وcontentType. بالنسبة إلى النماذج، يؤدي ذلك إلى إرفاق الأوزان؛ وبالنسبة إلى أرشيفات مجموعات البيانات، استدعِ ingest بعد ذلك لبدء المعالجة.

عند توفير md5، يتم التحقق منه مقابل الكائن المخزن. عدم التطابق يرجع 400؛ في جلسة لم تكتمل بعد، يؤدي ذلك أيضاً إلى حذف الملف المُحمَّل وترك الجلسة غير مكتملة، لذا اطلب عنوان URL موقّعاً جديداً وقم بالتحميل مرة أخرى. يمكن إكمال جلسة مجموعة البيانات المكتملة مرة أخرى طالما أن أرشيفها موجود، لكن عمليات الإكمال المتنافسة ذات الملخصات المختلفة ترجع 409؛ تتم إزالة جلسات النماذج عند الاكتمال. يتم تخزين checksum كبيانات وصفية لملف النموذج ولا يتم التحقق منه.

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

اربط حسابات Google Cloud Storage أو Amazon S3 أو Azure Blob Storage للقراءة فقط، وتصفّحها باعتبارها مصادر لمجموعات البيانات. راجع وثائق التكاملات.

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

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

يعيد integrations، ويحتوي كل عنصر منها على id وprovider وcredentialIdentity وtargets وcreatedAt. لا تُعاد بيانات الاعتماد مطلقًا.

اكتشاف المواقع#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

يسرد الحاويات أو المستودعات القابلة للقراءة باستخدام بيانات الاعتماد المقدمة، من دون حفظها.

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

الاستجابة: {"targets": ["my-bucket", "another-bucket"]}

توصيل وحدة التخزين#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

نفس أشكال بيانات الاعتماد المستخدمة في الاكتشاف، بالإضافة إلى مصفوفة targets مطلوبة تضم من 1 إلى 50 اسمًا للمستودعات أو الحاويات. يعيد 201 مع التكامل المحفوظ. تُرفض بيانات اعتماد S3 المؤقتة (مفاتيح الوصول ASIA).

استعراض العناصر#

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

Python SDK: client.storage_integrations.objects(id, target=...)

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

يعيد entries (كل kind هو folder أو file) وcursor اختياريًا للصفحة التالية.

فصل وحدة التخزين#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

يزيل بيانات الاعتماد المحفوظة من دون حذف بيانات الموفر. تظل مجموعات البيانات المتصلة ظاهرة، لكن تظل ملفاتها غير متاحة حتى إعادة توصيل حساب التخزين نفسه. يتطلب الوصول بصفة مسؤول مساحة العمل.

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

استورد مجموعات البيانات من خدمات خارجية. راجع تكامل Roboflow.

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

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

تحوّل مفتاح API الخاص بـ Roboflow إلى خطة استيراد تتضمن تفاصيل مساحة العمل، وnewDatasets التي ستُستورد، وأعداد المشاريع التي جرى تخطيها أو عدم دعمها أو تعذر حلها، وbytesTotal، والسعة المتبقية storage. يُقرأ مفتاح API الخاص بـ Roboflow من النص ولا يُحفظ.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

الاستيراد من Roboflow#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

يضع مهام الإدخال في قائمة الانتظار لما يصل إلى 500 إصدارًا محددًا من إصدارات مشاريع Roboflow، باستخدام العناصر التي أعادتها المعاينة.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

الاستجابة (201): مصفوفتا imported وfailed ومصفوفة skipped. تتطلب عمليات الاستيراد سعة تخزين كافية، ويجب أن تلتزم كل مجموعة بيانات بحد حجم الاستيراد لكل عملية وفق خطتك.

واجهة برمجة تطبيقات الحساب#

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

ملخص الحساب#

GET /api/account/summary

Python SDK: client.account.summary()

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

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

سرد مفاتيح API#

GET /api/api-keys

Python SDK: client.account.api_keys()

يعيد keys مع keyId وname وkeyPrefix وcreatedAt لمساحة عمل المفتاح. تتلقى الطلبات الموثقة بمفتاح API البيانات الوصفية فقط؛ وتظهر قيم المفاتيح الكاملة لمالك مساحة العمل في الإعدادات > مفاتيح API في واجهة Platform، وهي المكان الذي تُنشأ فيه المفاتيح وتُلغى أيضًا.

التحقق من استخدام التخزين#

GET /api/storage

Python SDK: client.account.storage()

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

الاستجابة:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

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

GET /api/users

Python SDK: client.account.profile(username=...)

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

يعيد ملف المستخدم العام user مع followerCount، وللمتصلين الذين تمت مصادقتهم، isFollowed.

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

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

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

الاستجابة: followed وfollowerCount المحدّث.

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

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

عرض الخطة والاستخدام#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

يعيد plan (المعرّف والحالة ودورة الفوترة ونهاية الفترة)، وmetrics (حد التخزين والاستخدام)، وtrainingCredit وfeatures وcreditsCents، وأعداد المقاعد.

عرض المعاملات#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

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

تتضمن كل معاملة id وtype (مثل purchase أو training أو monthly_grant أو refund) وamountCents وbalanceAfter وcreatedAt، وreceiptUrl اختياريًا، وسياق النموذج لرسوم التدريب. لا تُعاد تفاصيل الفوترة الداخلية مطلقًا.

استكشاف API#

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

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

GET /api/explore/search

Python SDK: client.explore.search()

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

الاستجابة: projects وdatasets وhasMore.

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

Python SDK#

ultralytics-platform هو عميل Python مكتوب الأنواع ومولّد من عقد OpenAPI، مع طريقة واحدة لكل نقطة نهاية (client.datasets.list وclient.models.predict وclient.exports.create ...). تقبل كل طريقة معلمات المسار موضعيًا، والمدخلات الأخرى كوسائط مسماة، وtimeout وextra_headers اختياريًا لكل طلب.

pip install "ultralytics-platform>=0.1.32" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY or the key saved by yolo login
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

يتيح AsyncPlatform شجرة الموارد نفسها لرمز async/await، وترفع الاستجابات غير الناجحة استثناء APIError مع status_code وbody وjson المحلّل، بينما ترفع حالات فشل الاتصال APIConnectionError. راجع مستودع SDK للاطلاع على README الكامل.

تكامل Python#

بالنسبة إلى عمليات التدريب والاستدلال، استخدم حزمة Python من Ultralytics، التي تتولى المصادقة والتحميل وبث المقاييس في الوقت الفعلي تلقائيًا.

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

تستلزم تكامل المنصة استخدام Python>=3.11 و ultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

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

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:

الدفع إلى Platform#

أرسل النتائج إلى مشروع في Platform:

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#

تحميل نموذج من Platform:

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

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