مرجع REST API#

يوفر Ultralytics Platform واجهة برمجة تطبيقات (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#

تم تنظيم واجهة برمجة التطبيقات حول موارد المنصة الأساسية:

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

المصادقة#

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

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

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

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

رأس التفويض#

قم بتضمين مفتاح واجهة برمجة التطبيقات الخاص بك كرمز مصادقة (bearer token):

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

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

يتم عنونة الموارد بنفس الأسماء المقروءة بشرياً التي تظهر في عناوين (URLs) الخاصة بالمنصة، وليس بواسطة معرفات قاعدة البيانات:

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

حدود المعدل#

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

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

عند تقييد السرعة، تُرجع واجهة برمجة التطبيقات 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"
}

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

نقاط النهاية المخصصة لا تخضع لحدود معدل مفتاح واجهة برمجة تطبيقات المنصة عندما تتصل بـ 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"
}

الترقيم#

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

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

إنشاء مجموعات البيانات المصورة للتدريب على نماذج 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=...)

الجسم (Body):

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

الاستجابة (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 حرفاً والكائن المسلسل على 500000 حرف.

الاستجابة:

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

يُرجع رابط تنزيل 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=...)

الجسم (Body):

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

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

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

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

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

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

الجسم (Body):

{
    "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 (عدد الصور المنقولة).

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

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.

نقل الصور بالجملة#

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.

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

POST /api/images/urls

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

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

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

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

API المشاريع#

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

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

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.

API النماذج#

إدارة نماذج 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.

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

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

حذف نموذج#

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

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

يقوم بنقل النموذج إلى trash لمدة 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 مع صلاحية الوصول إلى المشروع الأصل.

نموذج Multipart:

قم بتوفير إما 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 عندما لا يكون التدريب نشطًا بعد الآن.

API التدريب#

قم بإطلاق تدريب YOLO على وحدات معالجة الرسوميات السحابية ومراقبة التقدم في الوقت الفعلي. راجع وثائق التدريب السحابي.

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()

يعيد حالة المخزون الحالية مصنفة بواسطة معرف وحدة معالجة الرسوميات. عامة وبدون مصادقة؛ قم تمرير 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 عندما لا تتوفر سعة لوحدة معالجة الرسوميات المطلوبة.

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

تحويل النماذج إلى تنسيقات محسنة مثل 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 هو تنسيق المصدر وليس هدف تصدير لواجهة برمجة التطبيقات.

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

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

API النشر#

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

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=...)

الجسم (Body):

{
    "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=...)

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

نموذج Multipart:

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

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

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

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

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

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

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

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

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

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

عرض واستعادة وحذف المشاريع ومجموعات البيانات والنماذج المحذوفة مؤقتًا بشكل دائم. يتم مسح العناصر تلقائيًا بعد 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=...)

الجسم (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"
}

قم بتحميل الملف بطلب PUT إلى uploadUrl، باستخدام نفس Content-Type الذي أعلنته.

إكمال الرفع#

POST /api/upload/complete

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

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

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

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

قم بتوصيل حسابات 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=...)

يحول مفتاح واجهة برمجة تطبيقات Roboflow إلى خطة استيراد: تفاصيل مساحة العمل، وnewDatasets الذي سيتم استيراده، وإعدادات المشاريع التي تم تخطيها أو غير المدعومة أو التي لم يتم حلها، وbytesTotal، والمساحة المتاحة لديك من storage. تتم قراءة مفتاح واجهة برمجة تطبيقات 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. تتطلب عمليات الاستيراد مساحة تخزين متاحة، ويجب أن تتناسب كل مجموعة بيانات مع حد الحجم لكل عملية استيراد في خطتك.

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

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

ملخص الحساب#

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 لمساحة عمل المفتاح. تتلقى الطلبات الموثقة بمفتاح واجهة برمجة التطبيقات بيانات وصفية فقط؛ ويتم إظهار قيم المفاتيح الكاملة لمالك مساحة العمل في الإعدادات > مفاتيح واجهة برمجة التطبيقات في واجهة المستخدم للمنصة، وهي أيضًا المكان الذي يتم فيه إنشاء المفتاح وإلغاؤه.

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

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 المحدث.

API الفوترة#

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

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

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، وسياق النموذج لرسوم التدريب. لا يتم إرجاع تفاصيل الفوترة الداخلية أبدًا.

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

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

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

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.5" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    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#

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

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

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:

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

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

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

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