مرجع 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يسرد كل مسار أدناه استدعاء client.<resource>.<method>(...) الخاص به من حزمة SDK المسماة ultralytics-platform، والتي تُنشأ من العقد نفسه الذي يستند إليه هذا المرجع.
تقدم هذه الصفحة جولة إرشادية لواجهة API. يوجد المرجع المُنشأ والمحدّث دائمًا في platform.ultralytics.com/api/docs، كما تُنشر وثيقة OpenAPI 3.2 القابلة للقراءة آليًا، والتي تشغّله، في platform.ultralytics.com/openapi.json. ويُنشأ كلاهما مباشرةً من العقد على جانب الخادم، لذا يُعدّان المرجع المعتمد كلما تعارضت هذه الصفحة مع المخطط.
نظرة عامة على API#
تُنظَّم API حول موارد المنصة الأساسية:
| المورد | الوصف | العمليات الرئيسية |
|---|---|---|
| مجموعات البيانات | مجموعات الصور الموسومة | إنشاء وقراءة وتحديث وحذف، وإدخال البيانات، والإصدارات، والفئات، والتقسيمات، والاستنساخ، والنسخ |
| الصور | الصور الفردية والتسميات | القراءة، والإضافة التوضيحية، ونقل التقسيم، والحذف، والإضافة التوضيحية التلقائية، وطمس الوجوه |
| المشاريع | مساحات عمل النماذج | إنشاء وقراءة وتحديث وحذف، واستنساخ |
| النماذج | نقاط تحقق النماذج المدرّبة | إنشاء وقراءة وتحديث وحذف، والتنبؤ، والتنزيل، والاستنساخ، وحالة التدريب |
| التدريب | مهام التدريب السحابي على GPU | توفر GPU، والبدء، والتقدم، والإلغاء |
| عمليات التصدير | مهام تحويل التنسيقات | إنشاء، إدراج، الحالة، إلغاء، رابط الهاتف المحمول |
| عمليات النشر | نقاط استدلال مخصصة | الإنشاء، والتحديث، والبدء/الإيقاف، والتنبؤ، والمقاييس، والسجلات |
| الوكلاء | سير عمل مرئي محفوظ | الإدراج، والحفظ، والحذف |
| المهملات | الموارد المحذوفة حذفًا مبدئيًا | الإدراج، والاستعادة، والحذف نهائيًا |
| التخزين | تكاملات التخزين السحابي | الاتصال، والاستكشاف، والتصفح، وقطع الاتصال |
| الحساب | الخطة، والأرصدة، والتخزين، والملف الشخصي | ملخص الحساب، ومفاتيح API، واستخدام التخزين، والبحث عن المستخدمين |
| الفوترة | استخدام الخطة ودفتر المعاملات | ملخص الاستخدام، والمعاملات |
| استكشاف | البحث في المحتوى العام | ابحث في المشاريع ومجموعات البيانات والنماذج والصور |
المصادقة#
تتطلب معظم المسارات مفتاح API. كما تقبل المسارات التي تتيح الوصول إلى محتوى عام — مثل قراءة مجموعة بيانات أو مشروع أو نموذج عام، أو إدراج صور مجموعة بيانات عامة، أو تنفيذ الاستدلال على نموذج عام، أو البحث في «استكشاف» — الطلبات المجهولة، وتعيد ببساطة مزيدًا من النتائج عند توفير مفتاح.
الحصول على مفتاح API#
- انتقل إلى
Settings>API Keys - انقر على
Add Key، واتركUltralyticsمحددًا كمزوّد، وأدخل اسمًا، ثم انقر علىCreate Key - انسخ المفتاح المُنشأ
راجع مفاتيح API للاطلاع على التعليمات التفصيلية.
ترويسة التفويض#
أدرج مفتاح API الخاص بك على هيئة رمز حامل:
Authorization: Bearer YOUR_API_KEYمفاتيح API هي البادئة الحرفية ul_ متبوعة بـ40 محرفًا سداسيًا عشريًا، أي 43 محرفًا إجمالًا (مثلًا ul_a1b2c3d4e5f6789012345678901234567890abcd). تؤدي الطلبات التي تفتقد الترويسة أو تتضمن مفتاحًا مشوهًا أو ملغى إلى إرجاع 401. احتفظ بمفتاحك سرًا — ولا تودعه مطلقًا في نظام التحكم بالإصدارات أو تشاركه علنًا.
مثال#
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/account/summaryعنوان URL الأساسي#
تستخدم جميع مسارات API ما يلي:
https://platform.ultralytics.com/apiمسارات الموارد#
تُعرَف معظم الموارد بالأسماء المقروءة للبشر نفسها التي تظهر في عناوين URL للمنصة، لا بمعرّفات قاعدة البيانات:
| المورد | المسار | مثال |
|---|---|---|
| مجموعة البيانات | /api/datasets/{owner}/{dataset} | /api/datasets/acme-vision/warehouse |
| المشروع | /api/projects/{owner}/{project} | /api/projects/acme-vision/inspection |
| النموذج | /api/models/{owner}/{project}/{model} | /api/models/acme-vision/inspection/v3 |
| النشر | /api/deployments/{owner}/{deployment} | /api/deployments/acme-vision/edge-1 |
| الصورة | /api/images/{imageId} | /api/images/65f1c0a2b3d4e5f601234567 |
| الوكيل | /api/workflows?id={agentId} | /api/workflows?id=65f1c0a2b3d4e5f601234567 |
- يشير
{owner}إلى اسم مستخدم شخصي أو معرّف مساحة عمل لفريق: من 4 إلى 32 حرفًا، بأحرف وأرقام صغيرة، مع واصلات مفردة بين المقاطع. - تتبع
{dataset}و{project}و{model}و{deployment}النمط نفسه باستخدام الأحرف الصغيرة والواصلات، وبحد أقصى 128 حرفًا. - إن
{imageId}و{exportId}و{agentId}معرّفات سداسية عشرية بطول 24 حرفًا تعيدها API. - تؤدي إعادة تسمية مورد عبر
PATCHإلى تغييرnameالمعروض واسم URL معًا، ويعيد الرد اسم URL الحالي لتتمكن من مواصلة استخدامه.
باستثناء واجهة Agents API، لا توجد معلمة استعلام باسم owner. تتضمن المسارات المحددة بنطاق مساحة العمل المالكَ ضمن المسار، بينما تعمل نقاط النهاية المحددة بنطاق الحساب (/api/account/summary و/api/api-keys و/api/storage و/api/billing/* و/api/trash و/api/integrations/buckets) على مساحة العمل التي أصدرت مفتاح API. لتنفيذ إجراء على مساحة عمل فريق، استخدم مفتاح API أُنشئ في مساحة العمل تلك، أو مرّر owner إلى Agents API.
حدود المعدل#
تفرض API حدودًا باستخدام نافذة متحركة لكل مفتاح API. ويندرج كل مسار ضمن فئة واحدة، ولكل فئة عدّاد مستقل؛ لذا فإن 20 طلب تنبؤ لا تستهلك الحد الافتراضي المخصص لك.
| الفئة | الحد | ينطبق على |
|---|---|---|
| الافتراضي | 100 طلب/دقيقة | كل المسارات غير المدرجة أدناه |
| التدريب | 10 طلبات/دقيقة | POST /api/training/start |
| التحميل | 10 طلبات/دقيقة | عناوين URL الموقّعة للتحميل، وإكمال التحميل، وإدخال مجموعة البيانات |
| التنبؤ | 20 طلبًا/دقيقة | الاستدلال على النماذج وعمليات النشر عبر مسارات Platform API |
| التصدير | 20 طلبًا/دقيقة | إدراج عمليات تصدير النماذج وإنشاؤها، وإنشاء إصدارات مجموعات البيانات أو تحديثها؛ أما قراءة تصدير مجموعة بيانات (GET) وقراءة تصدير نموذج واحد فتخضعان للحد الافتراضي |
| تنزيل | 30 طلبًا/دقيقة | تنزيل ملفات النماذج |
| التعديل | 10 طلبات/دقيقة | إدراج مفاتيح API، وإدراج تكاملات التخزين السحابي أو ربطها، واستكشاف مواقع التخزين، وتحديثات عمليات النشر (PATCH) |
| التهيئة | 20 طلبًا/دقيقة | POST /api/datasets/{owner}/{dataset}/images (جلب مجموعة محددة من الصور) وGET /api/images/{imageId}/similar |
| التجميع العنقودي | 10 طلبات/دقيقة | GET /api/datasets/{owner}/{dataset}/images/clustering وGET /api/models/{owner}/{project}/{model}/similar-images |
للمسارات المتاحة عبر منصة Platform في المتصفح فقط، مثل إتمام الدفع وإدارة الفريق، حدودها الخاصة التي لا تنطبق على حركة المرور باستخدام مفاتيح API.
عند تقييد المعدل، تُرجع API الرمز 429 مع الترويسات ونص JSON:
Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z{
"error": "Rate limit exceeded, wait 12s",
"retryAfter": 12,
"resetAt": "2026-02-21T12:34:56.000Z"
}نقاط نهاية مخصصة (غير محدودة)#
لا تخضع نقاط النهاية المخصصة لحدود معدل مفاتيح API الخاصة بالمنصة عند استدعاء serviceUrl الخاص بعملية النشر مباشرةً (على سبيل المثال، https://predict-abc123.run.app/predict). ويعتمد معدل النقل عندئذٍ على إعدادات الخدمة المنشورة.
عند تلقي 429، انتظر Retry-After ثانية (أو حتى X-RateLimit-Reset) قبل إعادة المحاولة. راجع الأسئلة الشائعة حول حدود المعدل للاطلاع على تطبيق التراجع الأسي.
تنسيق الاستجابة#
استجابات النجاح#
الاستجابات كائنات JSON تتضمن حقولًا خاصة بكل مورد. لا يوجد غلاف عام: تُرجع نقاط نهاية القوائم مجموعة مسماة، وغالبًا ما تُرفق بها أعداد، بينما تُرجع عمليات التعديل المعرّفات التي تغيّرت.
{
"datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
"total": 1,
"region": "us"
}تتضمن قوائم الموارد واستجابات الإنشاء والاستنساخ وبعض عمليات القراءة، مثل عمليات النشر والتخزين وسلة المهملات، أيضًا region (us أو eu أو ap)، وهي منطقة التخزين الخاصة بمساحة العمل تلك.
استجابات الأخطاء#
كل استجابة خطأ هي كائن JSON يتضمن رسالة error:
{
"error": "Dataset not found"
}| حالة HTTP | المعنى |
|---|---|
200 | نجاح |
201 | تاريخ الإنشاء |
202 | مقبول، يستمر العمل بصورة غير متزامنة |
400 | مسار أو استعلام أو نص طلب غير صالح |
401 | بيانات المصادقة مفقودة أو غير صالحة |
402 | أرصدة غير كافية (التدريب) |
403 | الأذونات أو الخطة أو الحصة غير كافية |
404 | المورد غير موجود |
409 | تعارض مع الحالة الحالية (اسم مكرر، أو مهمة قيد التنفيذ) |
413 | مدخل التنبؤ كبير جدًا |
422 | فئات النموذج لا تتطابق مع مجموعة البيانات، أو مفتاح المزوّد مفقود أو مرفوض (التعليق التلقائي) |
429 | تم تجاوز حد المعدل |
500 | خطأ في الخادم |
502 | فشل استدعاء المزوّد أو الخدمة في النظام الأعلى |
503 | الخدمة التابعة غير متاحة مؤقتًا |
التقسيم إلى صفحات#
يعتمد أسلوب تقسيم الصفحات على المجموعة:
| الأسلوب | نقاط النهاية | المعلمات |
|---|---|---|
| الحد فقط | قوائم مجموعات البيانات والمشاريع والنماذج وعمليات التصدير وعمليات النشر | limit |
| الإزاحة والحد | صور مجموعة البيانات، وتجميع الصور، والبحث في Explore | offset وlimit، بالإضافة إلى hasMore في الاستجابة |
| المؤشر | صور مجموعة البيانات (مجموعات البيانات الكبيرة) | cursor وincludeTotal، بالإضافة إلى nextCursor |
| رقم الصفحة | سلة المهملات | page وlimit، بالإضافة إلى totalPages |
| رمز صفحة غير شفاف | سجلات عمليات النشر | pageToken، بالإضافة إلى nextPageToken |
API مجموعات البيانات#
أنشئ مجموعات بيانات الصور المصنفة لتدريب نماذج YOLO، واستعرضها وأدرها. راجع وثائق مجموعات البيانات.
سرد مجموعات البيانات#
GET /api/datasets/{owner}Python SDK: client.datasets.list(owner)
يُرجع مجموعات البيانات العامة الخاصة بالمالك، بالإضافة إلى مجموعات البيانات الخاصة عندما يتيح مفتاحك عرض مساحة العمل تلك.
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
limit | int | الحد الأقصى لعدد مجموعات البيانات المطلوب إرجاعها (الافتراضي: 1000، الحد الأقصى: 1000) |
includeSamples | قيمة منطقية | تضمين معاينات صور العينات (الافتراضي: true) |
includeImageUrls | قيمة منطقية | تضمين عناوين URL البديلة لصور العينات بالحجم الكامل (الافتراضي: false) |
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 الذي يحدده المستخدم. أثناء معالجة استيراد يضم 10,000 صورة أو أكثر، يتلقى المحررون أيضًا processingProgress مع stage وpercent، وعند توفرها، processed وtotal وobjects (عناصر التخزين السحابي التي جرى فحصها).
إنشاء مجموعة بيانات#
POST /api/datasetsPython 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"
}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
dataset | سلسلة نصية | نعم | اسم مجموعة البيانات المستخدم في عناوين URL للمنصة (أحرف صغيرة، مع وصل الكلمات بشرطات، بحد أقصى 128 حرفًا) |
name | سلسلة نصية | نعم | اسم العرض (بحد أقصى 100 حرف) |
description | سلسلة نصية | لا | الوصف (بحد أقصى 1000 حرف) |
task | سلسلة نصية | لا | نوع المهمة (الافتراضي: detect) |
classNames | مصفوفة | لا | أسماء الفئات بترتيب الفهرس (بحد أقصى 25,000)؛ بلا تكرار، مع تجاهل حالة الأحرف للأسماء التي يتجاوز طولها حرفين |
format | سلسلة نصية | لا | تنسيق التعليقات التوضيحية: yolo (الافتراضي)، coco، raw، ndjson |
visibility | سلسلة نصية | لا | public أو private (الافتراضي: مستوى الرؤية الافتراضي لمساحة العمل) |
blurFaces | قيمة منطقية | لا | تمويه الوجوه في الصور التي تُحمّل إلى مجموعة البيانات (راجع تمويه الوجوه) |
tags | مصفوفة | لا | حتى 50 وسمًا، يتكون كل منها من 50 حرفًا |
license | سلسلة نصية | لا | معرّف ترخيص مجموعة البيانات |
metadata | كائن | لا | بيانات وصفية مخصصة بتنسيق JSON |
owner | سلسلة نصية | لا | معرّف مساحة عمل الفريق؛ ويكون الافتراضي مساحة العمل الشخصية |
يؤدي استخدام معرّف dataset موجود بالفعل في مساحة العمل، بما في ذلك معرّف موجود في سلة المهملات، إلى إرجاع 409.
القيم الصالحة لـ task عند إنشاء مجموعة بيانات أو تحديثها: detect وsegment وsemantic وdepth وclassify وpose وobb. لا تتضمن مجموعات بيانات العمق أي فئات.
الاستجابة (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 وblurFaces وkptSkeletonId (لتعيين قالب هيكل عظمي لوضعية إلى مجموعة بيانات وضعية)، وinitializeClassNames (يُرجع التحديث 409 ما لم تكن مجموعة البيانات بلا فئات أو تعليقات توضيحية بعد). أرسل كائن 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}/clonePython SDK: client.datasets.clone(owner, dataset)
ينسخ مجموعة بيانات يمكن الوصول إليها، بصورها وتسمياتها، إلى مساحة عملك الشخصية أو مساحة عمل فريق. يمكن استخدام splits (train وval وtest) أو imageIds (حتى 1,000) اختياريًا لاستنساخ جزء منها فقط، ويستنسخ version إصدارًا محفوظًا بدلًا من الصور الحالية، وينسخ annotations: false الصور بلا تسميات، ويضيف into الصور بلا تسميات إلى مجموعة بيانات تملكها بدلًا من إنشاء مجموعة جديدة. لا يمكن الجمع بين version وsplits أو imageIds أو into أو annotations: false.
النص الاختياري (جميع الحقول اختيارية):
{
"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. تُرجع مجموعات البيانات التي يستند تخزينها إلى مصدر متصل، أو مجموعة بيانات into قيد المعالجة أو متصلة، القيمة 409. في غياب visibility، تكون النسخة خاصة إذا كانت إمكانية الرؤية الافتراضية لمساحة العمل الوجهة خاصة، وإلا احتفظت بإمكانية رؤية المصدر.
تنزيل تصدير مجموعة بيانات#
GET /api/datasets/{owner}/{dataset}/exportPython SDK: client.datasets.export(owner, dataset)
يُرجع عنوان URL موقّعًا لتنزيل ملف NDJSON. احذف v لتصدير الحالة الحالية لمجموعة البيانات، مع إعادة استخدام التصدير المخزّن مؤقتًا إذا لم يحدث أي تغيير منذ إنشائه.
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
v | عدد صحيح | رقم الإصدار المحفوظ (يبدأ الفهرس من 1). احذفه لاستخدام مجموعة البيانات الحالية. |
الاستجابة:
{
"downloadUrl": "https://storage.googleapis.com/...&signature=...",
"cached": true
}يؤدي طلب إصدار محدد إلى إرجاع downloadUrl وversion بدلًا من cached.
إنشاء إصدار لمجموعة بيانات#
POST /api/datasets/{owner}/{dataset}/exportPython SDK: client.datasets.create_export(owner, dataset)
ينشئ إصدارًا مرقمًا غير قابل للتغيير من مجموعة البيانات. يتطلب ذلك صلاحية المحرر. اضبط download على false لحفظ الإصدار دون إعداد تنزيل NDJSON؛ وعندئذٍ يُحذف downloadUrl. تقبل SDK القيمة download من ultralytics-platform>=0.1.73.
النص (اختياري):
{
"description": "Added 500 training images",
"download": true
}الاستجابة:
{
"version": 3,
"downloadUrl": "https://storage.googleapis.com/...&signature=...",
"reused": false
}تكون قيمة reused هي true عندما تطابق مجموعة البيانات إصدارًا موجودًا، كأن يحدث ذلك مباشرةً بعد استعادتها، ويُعاد ذلك الإصدار بدلًا من إنشاء إصدار جديد، مع تحديث وصفه عند إرسال وصف.
تحديث وصف الإصدار#
PATCH /api/datasets/{owner}/{dataset}/exportPython SDK: client.datasets.update_export(owner, dataset, version=..., description=...)
النص:
{
"version": 2,
"description": "Fixed mislabeled classes"
}الاستجابة: {"ok": true}
استعادة إصدار مجموعة بيانات#
POST /api/datasets/{owner}/{dataset}/restorePython SDK: client.datasets.restore(owner, dataset, version=...)
يعيد إنشاء الصور والتعليقات التوضيحية والفئات من إصدار محفوظ، دون نسخ وحدات بايت الصور.
النص:
{
"version": 2
}الاستجابة: {"version": 2, "imageCount": 1000}
مقارنة إصدارات مجموعات البيانات#
GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}Python SDK: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)
| المعلمة | النوع | الوصف |
|---|---|---|
base | int | الإصدار المُقارَن منه |
head | int | الإصدار المُقارَن به |
cursor | سلسلة نصية | nextCursor من الصفحة السابقة |
hash | سلسلة نصية | قيمة hash لعنصر ما: أعد تلك الصورة كما يخزنها كل إصدار، لا التغييرات التي طرأت عليها |
الاستجابة (مختصرة):
{
"summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
"items": [
{
"hash": "b5c605c133f84c3024af7e652b135501",
"name": "000000000042",
"change": "moved",
"base": { "split": "val", "labelCount": 1 },
"head": { "split": "test", "labelCount": 1 }
}
]
}يظهر summary في الصفحة الأولى فقط، ويتضمن الإجماليات الدقيقة، بالإضافة إلى header الذي يسرد الفئات المضافة أو المحذوفة أو المعاد تسميتها وحقول مجموعة البيانات الأخرى التي تختلف. تكون قيمة change لكل عنصر هي added أو removed أو modified (مع fields المتغير) أو moved (تغيّر التقسيم)، ويتضمن labelsRemoved تسميات الصور المحذوفة. مرّر nextCursor، عند وجوده، بوصفه cursor للصفحة التالية. عند استخدام hash، تكون الاستجابة versions: الصورة كما يخزنها كل إصدار، مع تسمياتها وimageUrl موقّع. يصلح كلا الترتيبين؛ إذ يؤدي تبديل base وhead إلى الإبلاغ عن صورة محذوفة على أنها مضافة. تخضع المقارنات لحد المعدل الافتراضي، كما تُقيّد الطلبات التي لا تتضمن hash بما يصل إلى 10 طلبات في الدقيقة لكل مستخدم ومجموعة بيانات، بصرف النظر عن مفتاح API المُستخدم لإرسالها.
الحصول على إحصاءات مجموعة البيانات#
GET /api/datasets/{owner}/{dataset}/class-statsPython 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/mergePython SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)
{
"sourceClassIds": [2, 4],
"targetClassId": 1
}حذف الفئات (تُحذف تعليقاتها التوضيحية، وتتناقص معرّفات الفئات المتبقية):
POST /api/datasets/{owner}/{dataset}/classes/deletePython 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/redistributePython 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}/embeddingsPython 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، أو 409 إذا كانت ميزات الذكاء الاصطناعي معطلة في تخزين مجموعة البيانات أو كان التخزين محليًا. وتلغي DELETE المهمة النشطة، ثم تُرجع معرّف المهمة الملغاة أو null.
تجميع الصور#
GET /api/datasets/{owner}/{dataset}/images/clusteringPython SDK: client.datasets.clustering(owner, dataset)
يعيد تخطيط UMAP ثنائي الأبعاد الناتج عن تحليل مكتمل، مقسّمًا إلى صفحات باستخدام offset وlimit (القيمة الافتراضية والحد الأقصى 50,000). يتضمن كل إدخال id، وumapX، وumapY، وcluster، وsplit، وclassIds، وwidth، وheight، وbytes، وlabelCount، وlabeled، وmissing. يشير cluster إلى الجزيرة المرئية للنقطة، مرتبة حسب الحجم (0 = الأكبر، و-1 = متناثرة)، أو null للتخطيطات التي حُلّلت قبل إضافة التجميع.
سرد النماذج المدرّبة على مجموعة بيانات#
GET /api/datasets/{owner}/{dataset}/modelsPython 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}/imagesPython SDK: client.datasets.images(owner, dataset)
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
limit | int | الحد الأقصى لعدد الصور المطلوب إرجاعها (الافتراضي: 50، والحد الأقصى: 5000) |
offset | int | عدد الصور المطلوب تخطيها (الافتراضي: 0) |
cursor | سلسلة نصية | معرّف آخر صورة من الصفحة السابقة، لترقيم الصفحات بالمؤشر |
includeTotal | قيمة منطقية | تضمين العدد الإجمالي للنتائج المطابقة (الافتراضي: true) |
split | سلسلة نصية | التصفية حسب القسم: train، وval، وtest |
hasLabel | قيمة منطقية | التصفية حسب حالة التعليقات التوضيحية |
hasError | قيمة منطقية | التصفية حسب حالة أخطاء المعالجة |
classIds | سلسلة نصية | معرّفات الفئات مفصولة بفواصل؛ يعيد الصور التي تحتوي على أي منها |
search | سلسلة نصية | مطابقة جزئية لاسم الملف واسم الفئة والبيانات الوصفية المخصصة (بحد أقصى 200 حرف)؛ أما المصطلح الذي ينتهي بامتداد ملف صورة، مثل img_0042.jpg، فيطابق أسماء الملفات فقط |
q | سلسلة نصية | ترتّب النتائج حسب مدى الصلة بدلًا من sort: تطابقات نصية، ثم ما يصل إلى 1,000 صورة مشابهة؛ ويُستخدم المعرّف أو التجزئة أو اسم الملف بوصفه search (بحد أقصى 200 محرف) |
sort | سلسلة نصية | newest (الافتراضي)، وoldest، وname-asc، وname-desc، وheight-asc، وheight-desc، وwidth-asc، وwidth-desc، وsize-asc، وsize-desc، وlabels-asc، وlabels-desc |
includeThumbnails | قيمة منطقية | تضمين عناوين URL موقّعة للصور المصغّرة (الافتراضي: true) |
includeImageUrls | قيمة منطقية | تضمين عناوين URL موقّعة للصور كاملة الحجم (الافتراضي: false) |
includeLabels | قيمة منطقية | تضمين معاينات محدودة للتعليقات التوضيحية (الافتراضي: false) |
الاستجابة:
{
"images": [
{
"id": "65f1c0a2b3d4e5f601234567",
"hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
"ext": "jpg",
"name": "aisle-04",
"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}/imagesPython SDK: client.datasets.selected_images(owner, dataset, image_ids=...)
يعيد بنية الصور نفسها لما يصل إلى 1,000 معرّف صورة مُقدّم، ويقبل معلمات التصفية وعناوين URL نفسها المستخدمة في عملية السرد.
{
"imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}نسخ الصور أو نقلها#
POST /api/datasets/{owner}/{dataset}/images/adoptPython SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)
ينسخ ما يصل إلى 1,000 صورة من مجموعات بيانات أخرى إلى هذه المجموعة، كما يفعل التطبيق عند النسخ واللصق، ويعيد العدد adopted.
{
"imageIds": ["65f1c0a2b3d4e5f601234567"],
"release": false,
"classMapping": { "person": 0, "vase": null }
}يحافظ تعيين release أو classMapping على الوسوم والتقسيمات من مجموعات البيانات التي يمكنك تعديلها: إذ ينسخ release: false الصور، بينما ينقلها release: true من مجموعة بيانات المصدر. يؤدي إغفال الحقلين إلى استيراد صور train بلا وسوم، وكذلك النسخ من مصدر للقراءة فقط؛ أما النقل من مصدر للقراءة فقط فيعيد 403. تُتجاوز الصور الموجودة؛ وعند الحفاظ على الوسوم والتقسيمات، يُتحقق من التكرارات ضمن تقسيم الوجهة. تُطابق الفئات بحسب الاسم، مع تجاهل حالة الأحرف للأسماء التي يتجاوز طولها حرفين؛ ويعيد 422 فئات المصدر التي لا يقابلها تطابق في unmatchedClasses، ويعيّن classMapping كل فئة إلى فهرس فئة أو اسم فئة جديدة أو null لإسقاط وسومها. تعني 409 أن الوجهة مجموعة بيانات متصلة أو أن المصدر أو الوجهة مشغول. عند الحفاظ على الوسوم والتقسيمات، تؤدي أيضًا المهام غير المتوافقة أو قنوات الصور أو إعدادات الوضعية أو مقاييس العمق إلى إرجاع 409، حتى للصور التي لا تحتوي على وسوم.
استيعاب بيانات مجموعة البيانات#
POST /api/datasets/{owner}/{dataset}/ingestPython SDK: client.datasets.ingest(owner, dataset, body=...)
يعالج رفعًا مكتملًا أو أرشيفًا بعيدًا أو مصدر تخزين متصلًا ويضيفه إلى مجموعة بيانات موجودة. حدّد مصدرًا واحدًا فقط:
| الحقل | النوع | الوصف |
|---|---|---|
sessionId | سلسلة نصية | جلسة رفع من POST /api/upload/signed-url؛ يتحقق الاستيعاب من الرفع ويُكمله إذا لم يُستدعَ POST /api/upload/complete |
sourceUrl | سلسلة نصية | عنوان URL عام عبر HTTP أو HTTPS لملف ZIP أو TAR أو TAR.GZ أو TGZ أو NDJSON (بحد أقصى 4096 حرفًا) |
reference | كائن | مصدر متصل: تخزين سحابي (provider: "cloud"، وintegrationId، وtarget، وprefix) أو محلي (provider: "local"، وkeyId، وroot، وprefix) |
targetSplit | سلسلة نصية | train أو val أو test؛ يتجاوز بنية الأقسام في الأرشيف |
conflictPolicy | سلسلة نصية | skip أو keep_both أو replace لتعارضات أسماء الملفات أو المحتوى |
classMapping | كائن | يربط أسماء الفئات الواردة بفهرس فئة أو اسم فئة موجود أو جديد، أو null لتخطيها |
imageMetadata | كائن | بيانات وصفية مخصصة، مفتاحها المسار النسبي لكل صورة داخل الأرشيف أو قيمة file في NDJSON |
ترتبط جلسات الرفع بمجموعة بيانات بواسطة 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 حرف بعد التسلسل.
ينشئ الإدخال الأول الفئات تلقائيًا من الأرشيف. وفي عمليات الإدخال اللاحقة، تُطابق فئات الأرشيف المحذوفة من classMapping بأسماء فئات مجموعة البيانات الموجودة، مع تجاهل حالة الأحرف للأسماء التي يتجاوز طولها حرفين؛ وتُضاف الفئات التي لا تطابق أي فئة كفئات جديدة. لا تُتجاوز الوسوم إلا للفئات التي عُيّنت صراحةً إلى null.
الاستجابة (201):
{
"jobId": "65f1c0a2b3d4e5f6012345aa",
"status": "queued"
}رفع صورة واحدة مع بيانات وصفية باستخدام Python
تتعامل الشيفرة نفسها مع مجموعة من الصور: أضف مزيدًا من الملفات إلى ZIP وإدخالات مطابقة إلى imageMetadata.
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()
headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, 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 }
}تستخدم إحداثيات التسميات قيم YOLO موحّدة بين 0 و1. تستخدم مربعات الإحاطة [x_center, y_center, width, height]. وتستخدم تسميات التجزئة segments، وهي قائمة مسطّحة من رؤوس المضلعات [x1, y1, x2, y2, ...]. وتستخدم تسميات الوضعية keypoints في بنية مسطّحة متسقة: أزواج [x1, y1, x2, y2, ...] أو ثلاثيات [x1, y1, v1, x2, y2, v2, ...]، حيث تستخدم الرؤية عادةً القيم 0 أو 1 أو 2. وتستخدم المربعات الموجّهة رؤوس obb. تُقرّب الإحداثيات المحفوظة إلى 5 منازل عشرية، ويمكن للصورة أن تتضمن 10,000 تعليق توضيحي كحد أقصى.
حذف صورة#
DELETE /api/images/{imageId}Python SDK: client.images.delete(image_id)
يحذف صورة واحدة وتعليقاتها التوضيحية نهائيًا.
إضافة تعليقات توضيحية تلقائيًا إلى صورة#
POST /api/images/{imageId}/predictPython SDK: client.images.predict(image_id, model_id=...)
يشغّل النموذج على الصورة ويعيد التعليقات التوضيحية المتوقعة. لا يحفظ هذه التعليقات — اكتب النتائج مرة أخرى باستخدام PATCH /api/images/{imageId} عندما تكون راضيًا عنها.
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
modelId | سلسلة نصية | نعم | معرّف URI كامل التأهيل للنموذج، أو ul://{owner}/{project}/{model}، أو معرّف نموذج موجّه بالفئات لمجموعة بيانات كشف تضم من 1 إلى 200 فئة (yoloe26x مع visualPrompts يدعم أيضًا مجموعات بيانات التجزئة وOBB): نموذج مستضاف (qwen، gemma، nemotron، moondream، wevisone، florence2، owlv2، yoloe26x، sam3، sam3.1، groundingdino) أو معرّف نموذج لمزوّد مدفوع من تعداد modelId في openapi.json |
confidence | float | لا | عتبة الثقة، من 0.01 إلى 1.0 (الافتراضي: 0.25)؛ تتجاهلها النماذج المحددة بالفئات التي لا تتضمن visualPrompts، وتستخدم عتبات خاصة بكل نموذج. |
iou | float | لا | عتبة IoU للكبت غير الأقصى، من 0.0 إلى 0.95 (الافتراضي: 0.5)؛ تتجاهلها النماذج الموجّهة بالفئات التي لا تستخدم visualPrompts |
visualPrompts | مصفوفة | لا | باستخدام modelId وyoloe26x على مجموعة بيانات للكشف أو التجزئة أو OBB، يمكن استخدام من 1 إلى 200 كائن توسيم (classId بالإضافة إلى bbox أو segments أو obb) من هذه الصورة، أو من الصورة referenceImageId، لتجد الفئات التي يعيد النموذج اكتشافها في الصورة |
referenceImageId | سلسلة نصية | لا | باستخدام visualPrompts، معرّف الصورة في مجموعة البيانات نفسها التي رُسمت عليها المطالبات، إذا لم تكن هي الصورة الجاري التنبؤ بها |
classMapping | مصفوفة | لا | لنموذج YOLO، فهرس فئة مجموعة البيانات المقابل لكل فئة من فئات النموذج بالترتيب، أو null لإسقاط تلك الفئة؛ وتؤدي القائمة ذات الطول غير الصحيح أو الفهرس الخارج عن نطاق فئات مجموعة البيانات إلى إرجاع 400. تتجاهلها النماذج المحددة بالفئات، ولا يُسمح بها مع visualPrompts. |
الاستجابة: success وpredictions (كائنات التعليقات التوضيحية) وconfidences (درجات مصطفّة حسب الفهرس، وفارغة للنماذج الموجّهة بالفئات التي لا تتضمن visualPrompts) وmodelUsed وinferenceTime وusage ([input tokens, output tokens]، عندما يُبلغ عنها نموذج لغوي)، وللنماذج الموجّهة بالفئات partial (true عندما يؤدي حد الإخراج أو الوقت إلى اقتطاع الرد قبل اكتماله، أو يُشتبه في ذلك، لذا قد تحذف التعليقات التوضيحية المُعادة بعض الكائنات)، ولنماذج موفّري الخدمات المدفوعة cost اختياريًا (التكلفة المقدّرة لدى الموفّر بالدولار الأمريكي، والمُحمّلة على مفتاح الموفّر الخاص بك، وتُحذف عند عدم توفر تقدير). يُعيد نموذج YOLO الذي لا تتطابق فئاته مع مجموعة البيانات 422، وكذلك النموذج الموجّه بالفئات عند استخدامه مع مجموعة بيانات غير مخصصة للكشف أو خارج نطاق 1–200 فئة (ما لم يستخدم visualPrompts)، أو مع نموذج أو مهمة أخرى visualPrompts، أو مع classId غير معروف، أو مطالبة صغيرة جدًا أو خارج الصورة، أو classMapping، وكذلك نموذج موفّر خدمة مدفوع دون حفظ مفتاح موفّر في Settings > API Keys لمساحة عمل مجموعة البيانات (code: missing_provider_api_key). ويُعيد referenceImageId الذي لا يمثل صورة في مجموعة البيانات هذه 404. يتضمن خطأ الموفّر رسالة الموفّر: 422 عندما يرد الموفّر بـ 400 أو 401 أو 402 أو 403 أو 404 (مفتاح أو نموذج أو طلب مرفوض، أو رصيد غير مدفوع لدى الموفّر؛ code: provider_refused لكل الحالات عدا 400)، و429 عند تجاوز حد المعدل، و503 لأي خطأ آخر لدى الموفّر. تُعيد مجموعات بيانات العمق 400. أما مجموعات بيانات On Premise، ومجموعات بيانات التخزين السحابي التي تكون ميزات الذكاء الاصطناعي فيها متوقفة أو بيانات اعتمادها غير متصلة، ومجموعات البيانات التي تضم أكثر من 3 قنوات صور، فتُعيد 409.
العثور على صور مشابهة#
GET /api/images/{imageId}/similarPython SDK: client.images.find_similar_images(image_id)
يعرض ما يصل إلى 24 عنصرًا من images المتشابهة بصريًا من مجموعات البيانات العامة ومجموعات بياناتك ومجموعات بيانات فريقك، مع score لكل عنصر (0-1)، وthumbnailUrl موقّع، وdataset المصدر (owner، وdataset، وlicense). تُستثنى مجموعة البيانات المصدر ومجموعات البيانات التي تحتوي على نسخة من صورة الاستعلام؛ ويحافظ includeSourceDataset=true عليها ويستبعد النسخ فقط. يضيّق كل من license (معرّفات مفصولة بفواصل من التراخيص المتاحة، مع None لمجموعات البيانات التي لا تحمل ترخيصًا) وpublicOnly=true (مجموعات البيانات العامة وحدها) نطاق البحث، مع استمرار إرجاع ما يصل إلى 24 صورة. يتطلب ذلك مفتاح API يتيح الوصول للعرض إلى الصورة؛ وتُضمَّن الصورة أولًا إن لم تكن قد ضُمّنت بعد، وتعني 503 تعذّر إعدادها، لذا أعد المحاولة. لا تُدرج مجموعة البيانات الخاصة بصورة من التخزين السحابي إلا ضمن مساحة عملها، وتعني 409 أن ميزات الذكاء الاصطناعي في مساحة تخزين الصورة معطّلة أو أن مجموعة البيانات من نوع On Premise.
إضافة تعليقات توضيحية تلقائيًا إلى مجموعة بيانات#
POST /api/datasets/{owner}/{dataset}/predict/batchPython SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)
يحفظ إصدارًا من مجموعة البيانات (ولا يتوفر لمجموعات بيانات التخزين السحابي إصدار)، ثم يضع في قائمة الانتظار تشغيلًا يوسم الصور غير الموسومة في مجموعة البيانات باستخدام النموذج، ويعيد 202. يقبل المتن الحقول نفسها modelId وconfidence وiou وclassMapping التي تقبلها نقطة نهاية الصورة الواحدة، بالإضافة إلى includeAnnotated (الافتراضي false) لتوسيم الصور التي لها تسميات بالفعل أيضًا. باستخدام modelId وyoloe26x، يبحث visualPrompts وreferenceImageId (وهما مطلوبان معهما؛ 422 من دونه، و404 إذا لم تعد الصورة ضمن مجموعة البيانات) عن كائنات مشابهة للأمثلة في صور التشغيل (الصور غير الموسومة فقط، ما لم يُستخدم includeAnnotated)، وذلك في مجموعات بيانات الكشف والتجزئة و OBB؛ وتُرمّز الأمثلة مرة واحدة عند بدء التشغيل. يكشف النموذج الموجّه بالفئات فئات مجموعة البيانات من دون درجات ثقة، ويحتاج نموذج المزوّد المدفوع إلى مفتاح مزوّد محفوظ في مساحة عمل مجموعة البيانات ضمن Settings > API Keys (422 وcode: missing_provider_api_key، قبل قبول التشغيل). لا تتغير التسميات الموجودة أبدًا، وتُتخطى التنبؤات التي يتجاوز تداخلها مع تسمية موجودة من الفئة نفسها iou، وتُحتسب تكلفة التشغيل على الصور التي يعالجها فعليًا. تعني 402 أن الرصيد لا يغطي التكلفة المقدّرة، وتعني 409 أن مجموعة البيانات غير جاهزة، أو أن ميزات الذكاء الاصطناعي متوقفة في وحدة التخزين الخاصة بها أو أنها محلية، أو أنه لم تبقَ صور لتوسيمها، أو أن هناك تشغيلًا قيد التنفيذ بالفعل. وتعني 422 أن مجموعة البيانات لا تضم فئات، أو أن نموذجًا موجّهًا بالفئات استُخدم مع مجموعة بيانات ليست للكشف أو لا تضم من 1 إلى 200 فئة: أنشئ الفئات باستخدام نقطة نهاية الفئات قبل استدعاء نقطة النهاية هذه؛ وهذا ما تنفذه خطوة تعيين الفئات في التطبيق قبل بدء التشغيل.
يعيد GET على المسار نفسه (client.datasets.batch(owner, dataset)) التشغيل الجاري وتقدمه، أو آخر تشغيل مكتمل حتى إغلاقه؛ وتتضمن قيمة results لهذا التشغيل partialImages عندما احتفظ تشغيل النموذج التوليدي بالمربعات المكتملة فقط من الخرج المقتطع؛ ويُلغي DELETE (client.datasets.delete_batch(owner, dataset)) تشغيلًا جاريًا، أو يسوّي الفوترة ويغلق الملخص المكتمل.
تقوم نقطة النهاية نفسها بتمويه الوجوه باستخدام "operation": "blur" وconfidence (الافتراضي 0.25) وboxScale (من 0.5 إلى 1.5، والافتراضي 1)؛ ويحدّ imageId التشغيل بصورة واحدة. لا تنشئ أي إصدار ولا تغيّر التسميات مطلقًا. أرسل "preview": true لمعالجة ما يصل إلى ست صور دون تغييرها، ثم أرسل jobId المُعاد باعتباره previewJobId وبالإعدادات نفسها للتطبيق؛ ولا يمكن إعادة استخدام معاينة مطبّقة، وستُعاد 409 عند محاولة ذلك. أثناء انتظار معاينة، مرّر معرّفها بوصفه previewJobId إلى DELETE للتخلص منها.
{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }نقل الصور دفعة واحدة#
PATCH /api/images/bulkPython 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/bulkPython SDK: client.images.delete_bulk(image_ids=...)
{
"imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}يحذف ما يصل إلى 1,000 صورة من مجموعة بيانات واحدة، ويعيد deletedCount وdeletedImageIds.
الحصول على عناوين URL موقّعة للصور#
POST /api/images/urlsPython SDK: client.images.urls(image_ids=...)
يعيد عناوين URL موقّعة مؤقتة لما يصل إلى 100 معرّف صورة من مجموعة بيانات واحدة.
{
"imageIds": ["65f1c0a2b3d4e5f601234567"]
}الاستجابة: urls وthumbnails وdepths (معاينات أهداف العمق لصور العمق المقترنة)، وكلها مفهرسة حسب معرّف الصورة.
واجهة برمجة المشاريع#
نظّم نماذجك في مشاريع. ينتمي كل نموذج إلى مشروع واحد. راجع وثائق المشاريع.
سرد المشاريع#
GET /api/projects/{owner}Python SDK: client.projects.list(owner)
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
limit | int | الحد الأقصى لعدد المشاريع المطلوب إرجاعها (الافتراضي: 20، والحد الأقصى: 500) |
الحصول على مشروع#
GET /api/projects/{owner}/{project}Python SDK: client.projects.retrieve(owner, project)
يعيد كائن project، ومصفوفة models التي تتضمن ملخصات لكل نموذج (الحالة، والمقاييس، والعصور، والأوزان، ومعاملات التدريب)، وisOwner. مرّر search (بحد أقصى 200 حرف) لتصفية models حسب اسم النموذج أو البيانات الوصفية.
إنشاء مشروع#
POST /api/projectsPython SDK: client.projects.create(project=..., name=...)
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
project | سلسلة نصية | نعم | اسم المشروع المستخدم في عناوين URL للمنصة |
name | سلسلة نصية | نعم | اسم العرض (بحد أقصى 100 حرف) |
description | سلسلة نصية | لا | الوصف (بحد أقصى 1000 حرف) |
visibility | سلسلة نصية | لا | public أو private (الافتراضي: مستوى الرؤية الافتراضي لمساحة العمل) |
tags | مصفوفة | لا | ما يصل إلى 50 وسمًا |
license | سلسلة نصية | لا | معرّف ترخيص المشروع |
metadata | كائن | لا | بيانات وصفية مخصصة بتنسيق JSON |
owner | سلسلة نصية | لا | معرّف مساحة عمل الفريق؛ ويكون الافتراضي مساحة العمل الشخصية |
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.
يؤدي استخدام معرّف project موجود بالفعل في مساحة العمل، بما في ذلك معرّف موجود في سلة المهملات، إلى إرجاع 409.
تحديث مشروع#
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 حرف للكائن المتسلسل. يُرجع تغيير name الذي يغيّر المعرّف المختصر 409 أثناء بدء التدريب لأي نموذج في المشروع.
حذف المشروع#
DELETE /api/projects/{owner}/{project}Python SDK: client.projects.delete(owner, project)
ينقل المشروع ونماذجه إلى المهملات، مع إرجاع cascadedModels، ويحذف عمليات النشر الخاصة بها نهائيًا. لا تؤدي استعادة المشروع إلى استعادة عمليات النشر. تعني 502 أن تنظيف عمليات النشر لم يكتمل؛ وتظل النماذج في المهملات إلى أن ينجح التنظيف.
استنساخ المشروع#
POST /api/projects/{owner}/{project}/clonePython SDK: client.projects.clone(owner, project)
يستنسخ مشروعًا متاحًا ونماذجه المكتملة. يقبل نص الطلب الاختياري project وname وdescription و visibility وlicense، ووجهة owner، وmodels، وهي قائمة بأسماء النماذج المراد استنساخها بدلًا من جميع النماذج المكتملة. إذا لم يُحدَّد visibility، فستكون النسخة المستنسخة خاصةً عندما يكون إعداد الظهور الافتراضي لمساحة العمل الوجهة هو «خاص»، وإلا فستحتفظ بإعداد الظهور للمصدر. إذا كانت نماذج النسخة المستنسخة ستتجاوز حد النماذج في مساحة العمل الوجهة، فسيُرجع الطلب 403 ولن ينسخ أي شيء.
واجهة API للنماذج#
إدارة نماذج YOLO المدرّبة — عرض المقاييس، وتنزيل الأوزان، وتشغيل الاستدلال، ومراقبة التدريب. راجع وثائق النماذج.
عرض النماذج في مشروع#
GET /api/models/{owner}/{project}Python SDK: client.models.list(owner, project)
لا تتضمن النماذج المدرجة plots وtrainResults الخاصة بالتحقق؛ ويعيد الحصول على النموذج هذه العناصر.
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
limit | int | الحد الأقصى لعدد النماذج المُعادة (الافتراضي: 20، الحد الأقصى: 100) |
الحصول على نموذج#
GET /api/models/{owner}/{project}/{model}Python SDK: client.models.retrieve(owner, project, model)
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
analysis | int | اضبط على 1 لإرجاع تحليل التحقق لكل صورة بدلًا من النموذج |
تتضمن الاستجابة الافتراضية الكائن model — الحالة، والمهمة، والمقاييس، وtrainArgs، وtrainResults، وclassNames، وcomputeCost، وmetadata، وغير ذلك — بالإضافة إلى isOwner.
إنشاء نموذج#
POST /api/modelsPython SDK: client.models.create(body=...)
ينشئ سجلًا لنموذج غير مدرّب، يمكنك إرفاق الأوزان به أو تدريبه.
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
project | سلسلة نصية | نعم | اسم المشروع الوجهة |
owner | سلسلة نصية | لا | معرّف مساحة العمل؛ يكون الافتراضي مساحة العمل الشخصية |
model | سلسلة نصية | لا | اسم النموذج المستخدم في عناوين URL للمنصة؛ يُنشأ تلقائيًا إذا لم يُحدَّد |
name | سلسلة نصية | لا | اسم العرض (يُقبل فقط مع model) |
description | سلسلة نصية | لا | الوصف (بحد أقصى 1000 حرف) |
task | سلسلة نصية | لا | detect أو segment أو semantic أو depth أو classify أو pose أو obb |
metadata | كائن | لا | بيانات وصفية مخصصة بتنسيق JSON |
trainArgs | كائن | لا | وسيطات التدريب المراد تسجيلها |
metrics | كائن | لا | مقاييس مثل mAP50 وmAP50-95 وprecision وrecall |
epochs | عدد | لا | عدد العصور التدريبية لنموذج مدرّب مسبقًا |
version | سلسلة نصية | لا | تسمية الإصدار (الحد الأقصى 50 حرفًا) |
الاستجابة (201): id، owner، project، model، name، region. تتضمن الاستجابة معرّف النموذج واسمه المعروض اللذين تم اختيارهما بعد حل تعارضات التسمية.
لإرفاق أوزان .pt، اطلب عنوان URL موقّعًا للتحميل باستخدام assetType: "models" وid لهذا النموذج باعتباره assetId، ثم PUT الملف إلى عنوان URL المُعاد، وبعدها استدعِ POST /api/upload/complete باستخدام sessionId المُعاد.
تحديث نموذج#
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 إذا كان ذلك المعرّف المختصر مستخدمًا هناك بالفعل، و409 ما دام النموذج لا يزال قيد التدريب. يُرجع تغيير name الذي يغيّر المعرّف المختصر 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}/filesPython SDK: client.models.files(owner, project, model)
يعيد عناوين URL موقّعة قصيرة الأجل لأوزان النموذج، وتُسمّى باسم النموذج ({model}.pt).
{
"files": [
{
"name": "my-model.pt",
"size": 6534127,
"downloadUrl": "https://storage.googleapis.com/...&signature=..."
}
]
}العثور على صور مشابهة لأسوأ صور التحقق#
GET /api/models/{owner}/{project}/{model}/similar-imagesPython SDK: client.models.find_similar_training_images(owner, project, model)
يعرض ما يصل إلى 100 عنصر من images، بالتنسيق نفسه الذي تعرضه العثور على صور مشابهة، وتشبه صور التحقق التي سجّل هذا التدريب أدنى النتائج عليها، مع استبعاد الصور الموجودة مسبقًا في مجموعة بيانات التدريب. مرّر hashes (قائمة مفصولة بفواصل، بحد أقصى 100) للبحث انطلاقًا من مجموعة فرعية من تلك الصور الأدنى أداءً، ومرّر license أو publicOnly لتضييق نطاق البحث كما في العثور على صور مشابهة. يتطلب ذلك مفتاح API يتيح الوصول إلى مساحة عمل النموذج. تكون القائمة فارغة إذا لم يسجّل التشغيل نتائج لكل صورة، وتعني 404 أيضًا أن الصور الأقل أداءً لم تُضمَّن بعد: شغّل تضمينات مجموعة البيانات على مجموعة بيانات التدريب أولًا.
استنساخ النموذج#
POST /api/models/{owner}/{project}/{model}/clonePython 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"
}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
project | سلسلة نصية | نعم | اسم المشروع الوجهة |
owner | سلسلة نصية | لا | مساحة العمل الوجهة؛ تكون الافتراضية مساحة العمل الشخصية |
model | سلسلة نصية | لا | اسم النموذج الوجهة |
name | سلسلة نصية | لا | اسم العرض للوجهة |
description | سلسلة نصية | لا | وصف النسخة |
تشغيل الاستدلال#
POST /api/models/{owner}/{project}/{model}/predictPython SDK: client.models.predict(owner, project, model, body=...)
يمكن إجراء الاستدلال على النماذج العامة دون مصادقة. أما النماذج الخاصة والمشتركة فتتطلب مفتاح API يتيح الوصول إلى المشروع الأصل.
نموذج متعدد الأجزاء:
| المعلمة | النوع | الافتراضي | النطاق | الوصف |
|---|---|---|---|---|
file | ملف | - | - | ملف صورة أو فيديو (مطلوب ما لم يتم تعيين source) |
conf | float | 0.25 | 0.01 – 1.0 | الحد الأدنى لعتبة الثقة |
iou | float | 0.5 | 0.0 – 0.95 | عتبة IoU لـ NMS |
imgsz | int | - | 32 – 1280 | حجم صورة الإدخال بالبكسل؛ القيمة الافتراضية هي حجم التدريب للنموذج (640 إذا لم يتوفر) |
normalize | bool | false | - | إرجاع إحداثيات الصندوق المحيط ضمن النطاق 0 – 1 |
decimals | int | 5 | 0 – 10 | الدقة العشرية لقيم الإحداثيات |
vid_stride | int | 1 | ≥ 1 | التنبؤ بكل إطار فيديو رقم N؛ لا ينطبق على الصور |
bits | int | 8 | 8, 12, 16 | تكميم خريطة العمق، لنماذج العمق فقط |
source | سلسلة نصية | - | - | عنوان URL للصورة أو سلسلة base64 (بديل لـ file)؛ الحد الأقصى 4,096 حرفًا عبر واجهة 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 (ما يصل إلى 1,000 لكل صورة، و300 لنماذج RT-DETR)، وبالنسبة إلى مهام التنبؤ الكثيف، حمولة 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}/trainingPython SDK: client.models.training(owner, project, model)
يعيد job متضمنًا الحالة، والتقدم في العصور التدريبية، والتوقيت، وتفاصيل الحوسبة، ووسيطات التدريب، ومقاييس العصور التدريبية، وتفاصيل آمنة عن الأخطاء؛ أو يعيد null إذا لم يسبق تدريب النموذج. يمكن قراءة النماذج الموجودة في مشاريع عامة دون مصادقة.
إلغاء التدريب#
DELETE /api/models/{owner}/{project}/{model}/trainingPython SDK: client.models.delete_training(owner, project, model)
ينهي مثيل الحوسبة قيد التشغيل ويضع علامة إلغاء على المهمة. يُرجع 409 عندما لا يكون التدريب نشطًا.
واجهة API للتدريب#
ابدأ تدريب YOLO على وحدات GPU سحابية وراقب التقدم في الوقت الفعلي. راجع وثائق التدريب السحابي.
الحصول على مدى توفر GPU#
GET /api/training/gpu-availabilityPython SDK: client.training.gpu_availability()
يعيد حالة المخزون الحالية مرتبة حسب معرّف GPU. الخدمة عامة ولا تتطلب المصادقة؛ مرّر managed=true لتضمين سعة التدريب المُدارة، التي تتطلب مفتاح API.
بدء التدريب#
POST /api/training/startPython SDK: client.training.start(model_id=..., train_args=...)
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
modelId | سلسلة نصية | نعم | معرّف النموذج المراد تدريبه |
trainArgs | كائن | نعم | وسائط تدريب YOLO؛ يلزم توفير model وdata وepochs. ويكون data معرّف URI لمجموعة بيانات ul://username/datasets/slug أو ملف YAML لمجموعة بيانات مضمنة، مثل coco8.yaml |
gpuType | سلسلة نصية | لا | وحدة GPU السحابية المراد استخدامها (الافتراضي: rtx-4090) |
captureDatasetVersion | قيمة منطقية | لا | حفظ إصدار ثابت من مجموعة البيانات لهذا التشغيل (الافتراضي: false) |
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.89, "gpuMemoryGb": 24 },
"billing": {
"estimatedCostCents": 178,
"estimatedCostDisplay": "$1.78",
"balanceCents": 2500
}
}يُرجع التدريب 400 عندما تكون data معرّف مجموعة بيانات أو مسار مجموعة بيانات في Platform من دون ul://، أو عندما لا تتوافق مهمة النموذج مع مهمة مجموعة البيانات؛ ويُرجع 402 عندما يكون رصيدك الائتماني منخفضًا جدًا، و409 عندما تكون ميزات الذكاء الاصطناعي معطّلة في التخزين السحابي لمجموعة البيانات أو عند انقطاع الاتصال به، و503 عندما لا تتوفر سعة لوحدة GPU المطلوبة.
يتوفر 26 نوعًا من GPU، بدءًا من rtx-2000-ada وحتى b300، بما في ذلك rtx-4090 وl40s وa100-80gb-pcie، a100-80gb-sxm وrtx-pro-6000 وh100-sxm وh200-sxm وb200. راجع التدريب السحابي للاطلاع على القائمة الكاملة.
واجهة API للتصدير#
حوِّل النماذج إلى تنسيقات محسّنة مثل ONNX وTensorRT وCoreML وLiteRT من أجل النشر على الأجهزة الطرفية.
عرض عمليات التصدير#
GET /api/models/{owner}/{project}/{model}/exportsPython SDK: client.exports.list(owner, project, model)
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
status | سلسلة نصية | التصفية حسب queued أو starting أو running أو completed أو failed أو cancelled |
limit | int | الحد الأقصى لعدد عمليات التصدير المُعادة (الافتراضي: 20، الحد الأقصى: 100) |
إنشاء عملية تصدير#
POST /api/models/{owner}/{project}/{model}/exportsPython SDK: client.exports.create(owner, project, model, format=...)
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
format | سلسلة نصية | نعم | تنسيق التصدير المستهدف (راجع الجدول أدناه) |
gpuType | سلسلة نصية | مشروط | مطلوب عندما تكون format هي engine؛ استخدم هدف GPU أو Jetson مدعومًا |
args | كائن | لا | خيارات التصدير: imgsz، quantize، dynamic، simplify، opset، conf، iou، batch، workspace، nms، optimize، وname (الهدف على الجهاز لـ RKNN وQNN وHailo وAscend وXilinx) |
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يدعم كل تنسيق الخيارات الواردة في عمود Arguments في جدول التصدير أدناه فقط: إذا كانت قيمة batch أو dynamic أو opset أو simplify أو workspace أو optimize غير افتراضية لتنسيق لا يدعمها، فستُعاد 400. تكون صادرات imx بصيغة INT8 فقط، وهي متاحة لنماذج الكشف والتجزئة والتصنيف وتقدير الوضعية؛ أما النموذج الذي يشير اسمه إلى أنه نموذج YOLO غير YOLOv8n أو YOLO11n فستُعاد له 400.
الاستجابة (201): id وformat وstatus (queued أو running) وregion وgpuType لصادرات TensorRT. أثناء وجود عملية تصدير بالتنسيق نفسه قيد التنفيذ للنموذج، يُرجع الطلب الجديد 409 أيًا كانت قيمة args.
التنسيقات المدعومة:
استخدم وسيط format من جدول التصدير المشترك أدناه. تنسيق المصدر هو PyTorch، وليس هدف تصدير عبر API.
| التنسيق | وسيط format | النموذج | البيانات الوصفية | الوسيطات |
|---|---|---|---|---|
| PyTorch | - | yolo26n.pt | ✅ | - |
| TorchScript | torchscript | yolo26n.torchscript | ✅ | imgsz, quantize, dynamic, nms, batch, device |
| ONNX | onnx | yolo26n.onnx | ✅ | imgsz, quantize, dynamic, simplify, opset, nms, batch, data, fraction, device |
| OpenVINO | openvino | yolo26n_openvino_model/ | ✅ | imgsz, quantize, dynamic, nms, batch, data, fraction, device |
| TensorRT | engine | yolo26n.engine | ✅ | imgsz, quantize, dynamic, simplify, opset, workspace, nms, batch, data, fraction, device |
| CoreML | coreml | yolo26n.mlpackage | ✅ | imgsz, dynamic, quantize, nms, batch, device |
| Apple Core AI | coreai | yolo26n.aimodel | ✅ | imgsz, batch, quantize |
| TF SavedModel | saved_model | yolo26n_saved_model/ | ✅ | imgsz, quantize, opset, nms, batch, data, fraction, device |
| TF GraphDef | pb | yolo26n.pb | ❌ | imgsz, opset, batch, device |
| TF Edge TPU | edgetpu | yolo26n_edgetpu.tflite | ✅ | imgsz, quantize, opset, data, fraction, device |
| LiteRT | litert | yolo26n.tflite | ✅ | imgsz, quantize, batch, data, fraction, device |
| PaddlePaddle | paddle | yolo26n_paddle_model/ | ✅ | imgsz, batch, device |
| MNN | mnn | yolo26n.mnn | ✅ | imgsz, batch, dynamic, quantize, simplify, opset, nms, device |
| NCNN | ncnn | yolo26n_ncnn_model/ | ✅ | imgsz, quantize, device |
| IMX500 | imx | yolo11n_imx_model/ | ✅ | imgsz, quantize, data, fraction, nms, device |
| RKNN | rknn | yolo26n_rknn_model/ | ✅ | imgsz, batch, name, quantize, simplify, opset, data, fraction, device |
| ExecuTorch | executorch | yolo26n_executorch_model/ | ✅ | imgsz, quantize, batch, data, fraction, device |
| Axelera | axelera | yolo26n_axelera_model/ | ✅ | imgsz, batch, quantize, data, fraction, device |
| DEEPX | deepx | yolo26n_deepx_model/ | ✅ | imgsz, quantize, simplify, opset, data, optimize, device |
| Qualcomm QNN | qnn | yolo26n_qnn.onnx | ✅ | imgsz, batch, name, quantize, simplify, opset, data, fraction, device |
| Hailo | hailo | yolo26n_hailo_model/ | ✅ | imgsz, name, quantize, data, fraction, simplify, conf, iou, device |
| Huawei Ascend | ascend | yolo26n_ascend_model/ | ✅ | imgsz, batch, name, quantize, opset, simplify, nms, device |
| AMD Xilinx | xilinx | yolo26n_xilinx_model/ | ✅ | imgsz, name, quantize, data, fraction, opset, simplify, device |
| NXP | nxp | yolo26n_nxp.tflite | ✅ | imgsz, quantize, data, fraction, device |
يُخرج nms=None افتراضيًا مخرجات خامًا لاستخدام NMS خارجي (ويحتفظ YOLO26 برأسه الخالي من NMS على Axelera). اضبط 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 (لـ TensorRT فقط) والطوابع الزمنية، وعند الاكتمال، كائن file الذي يتضمن size وdownloadUrl وdownloadFilename.
إنشاء رابط استيراد للهاتف المحمول#
POST /api/models/{owner}/{project}/{model}/exports/{exportId}/mobilePython SDK: لا يتوفر حاليًا؛ أرسل طلب HTTP مباشرةً.
يعيد importUrl وexpiresAt لفتح تصدير مكتمل بصيغة CoreML أو Core AI أو LiteRT في تطبيق Ultralytics YOLO. تنتهي صلاحية الرابط بعد 24 ساعة، ويستطيع أي شخص لديه الرابط تنزيل التصدير حتى ذلك الحين. ويعيد التصدير غير المكتمل أو غير المتوافق القيمة 409.
إلغاء عملية تصدير أو حذفها#
DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}Python SDK: client.exports.delete(owner, project, model, export_id)
يلغي عملية تصدير نشطة أو يحذف عملية مكتملة وملفها. توضح الاستجابة الإجراء الذي تم:
{
"success": true,
"action": "cancelled"
}واجهة API لعمليات النشر#
انشر النماذج على نقاط نهاية استدلال مخصصة مع فحوصات السلامة والمراقبة. راجع وثائق نقاط النهاية.
عرض عمليات النشر#
GET /api/deployments/{owner}Python SDK: client.deployments.list(owner)
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
status | سلسلة نصية | creating أو deploying أو ready أو stopping أو stopped أو failed |
model | سلسلة نصية | التصفية حسب {project}/{model}، مثل inspection/v3 |
limit | int | الحد الأقصى لعدد عمليات النشر المُعادة (الافتراضي: 20، الحد الأقصى: 100) |
يجب على المتصلين المجهولين التصفية حسب نموذج عام واحد؛ ويتطلب عرض مساحة عمل بأكملها المصادقة.
إنشاء عملية نشر#
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"
}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
project | سلسلة نصية | نعم | المشروع الذي يحتوي على النموذج |
model | سلسلة نصية | نعم | النموذج المراد نشره |
deployment | سلسلة نصية | نعم | اسم عملية النشر المستخدم في عناوين URL للمنصة |
name | سلسلة نصية | نعم | اسم العرض |
region | سلسلة نصية | نعم | إحدى مناطق النشر الـ42 المدعومة |
cpu | عدد | لا | أنوية vCPU: 1 (الافتراضي)، أو 2، أو 4، أو 6، أو 8 |
memoryGi | عدد | لا | الذاكرة بوحدة GiB: 2 (الافتراضي)، أو 4، أو 8، أو 16، أو 24، أو 32 |
الاستجابة (201): id وdeployment وstatus (creating) وmessage وregion.
يُقلّص الحجم الافتراضي، وهو 1 vCPU / 2 GiB، إلى الصفر عند الخمول، ويمكن الاستفادة معه من حصة نشر مجانية؛ أما الأحجام الأخرى فتُحاسب وفق الأسعار حسب الاستخدام. وتُعرض القيم الحالية في الكائن resources عند قراءة كل عملية نشر.
اختر منطقة قريبة من مستخدميك للحصول على أقل زمن استجابة. تعرض واجهة مستخدم المنصة تقديرات زمن الاستجابة لجميع المناطق الـ42 المتاحة.
الحصول على عملية نشر#
GET /api/deployments/{owner}/{deployment}Python SDK: client.deployments.retrieve(owner, deployment)
يعيد كائن deployment مع status وstatusMessage وregion وserviceUrl وresources وmetadata المخصص، بالإضافة إلى camera وcameraApplying للمالك.
تحديث عملية نشر#
PATCH /api/deployments/{owner}/{deployment}Python SDK: client.deployments.update(owner, deployment, body=...)
أرسل أحد هذه النصوص:
{ "name": "Edge 1 (primary)" }يغيّر إعادة التسمية قيمة deployment في URL إلى مقطع URL مشتق من الاسم الجديد، وتُعاد هذه القيمة باسم deployment؛ ويعيد المسار القديم 404، بينما يظل serviceUrl كما هو. يمحو الكائن الفارغ metadata البيانات الوصفية المخصصة. يؤدي الاستبدال إلى نشر مراجعة جديدة مع الحفاظ على معرّف عملية النشر والمنطقة وعنوان URL لنقطة النهاية؛ وتظل المراجعة الحالية نشطة إذا فشل النشر. يجب أن يكون النموذج البديل نموذجًا مكتملًا بأوزان يمكن لمفتاحك الوصول إليها. يحفظ إجراء الكاميرا كاميرا RTSP أو RTSPS تُبقيها نقطة نهاية جاهزة ذات موارد مخصصة قيد التشغيل للاستدلال (راجع كاميرا تعمل في الخلفية)؛ وتزيلها "url": null، وكذلك إعادة الحجم إلى الحجم الافتراضي، كما أن حفظ كاميرا على نقطة نهاية ذات الحجم الافتراضي يعيد 403. يعيد تغيير الكاميرا 202 مع status وready أثناء تطبيقه: استعلم عن عملية النشر إلى أن تصبح cameraApplying غير true، ثم تحقّق من camera؛ ويُبقي التغيير الفاشل الكاميرا السابقة ويضبط statusMessage. تعيد العمليات المكتملة 200 مع status وready أو stopped؛ أما العمليات الأخرى التي لا تزال قيد النشر فتعيد 202 مع deploying أو stopping.
حذف النشر#
DELETE /api/deployments/{owner}/{deployment}Python SDK: client.deployments.delete(owner, deployment)
يزيل نقطة نهاية الاستدلال نهائياً.
فحص الحالة#
GET /api/deployments/{owner}/{deployment}/healthPython SDK: client.deployments.health(owner, deployment)
يرسل طلبات تحقق إلى نقطة النهاية وينشّطها، ويُرجع healthy وlatencyMs ورمز status من الخدمة الأصلية.
تشغيل الاستدلال على عملية نشر#
POST /api/deployments/{owner}/{deployment}/predictPython SDK: client.deployments.predict(owner, deployment, body=...)
يوجّه صورة أو فيديو عبر نقطة النهاية المخصصة. تتطابق مواصفات الطلب والاستجابة مع استدلال النموذج. لا تُمرر تدفقات الكاميرا عبر وسيط؛ أرسلها إلى عنوان URL لنقطة النهاية كما هو موضح في الاستدلال المباشر بالكاميرا.
نموذج متعدد الأجزاء:
| المعلمة | النوع | الافتراضي | النطاق | الوصف |
|---|---|---|---|---|
file | ملف | - | - | ملف صورة أو فيديو (مطلوب ما لم يتم تعيين source) |
conf | float | 0.25 | 0.01 – 1.0 | الحد الأدنى لعتبة الثقة |
iou | float | 0.5 | 0.0 – 0.95 | عتبة IoU لـ NMS |
imgsz | int | - | 32 – 1280 | حجم صورة الإدخال بالبكسل؛ القيمة الافتراضية هي حجم التدريب للنموذج (640 إذا لم يتوفر) |
normalize | bool | false | - | إرجاع إحداثيات الصندوق المحيط ضمن النطاق 0 – 1 |
decimals | int | 5 | 0 – 10 | الدقة العشرية لقيم الإحداثيات |
vid_stride | int | 1 | ≥ 1 | التنبؤ بكل إطار فيديو رقم N؛ لا ينطبق على الصور |
bits | int | 8 | 8, 12, 16 | تكميم خريطة العمق، لنماذج العمق فقط |
source | سلسلة نصية | - | - | عنوان URL للصورة أو سلسلة base64 (بديل لـ file)؛ الحد الأقصى 4,096 حرفًا عبر واجهة API للمنصة |
الحصول على المقاييس#
GET /api/deployments/{owner}/{deployment}/metricsPython SDK: client.deployments.metrics(owner, deployment)
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
range | سلسلة نصية | 1h أو 6h أو 24h (افتراضي) أو 7d أو 30d |
sparkline | قيمة منطقية | إرجاع ملخص لوحة المعلومات الموجز بدلاً من السلاسل الكاملة (الافتراضي: false) |
view | سلسلة نصية | لا يعرض overview سوى مقاييس الطلبات والأخطاء وزمن الاستجابة عند P95 |
تتضمن الاستجابة الكاملة summary (إجمالي الطلبات ومعدل الأخطاء ومتوسط زمن الاستجابة وقيم p50/p95/p99) وtimeSeries (الطلبات والأخطاء وزمن الاستجابة ووحدة المعالجة المركزية والذاكرة وعدد المثيلات). وتعيد استجابة المخطط المصغر requests24h (أعداد الطلبات بالساعة؛ وتُحذف الساعات التي لم تتضمن طلبات) وtotalRequests وerrorRate وavgLatencyMs (متوسط أزمنة الاستجابة P95 بالساعة). عند استخدام view=overview، يحتوي summary على totalRequests وerrorRate وp95LatencyMs، ويحتوي timeSeries على requests وerrors وlatencyP95.
الحصول على السجلات#
GET /api/deployments/{owner}/{deployment}/logsPython SDK: client.deployments.logs(owner, deployment)
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
severity | سلسلة نصية | مفصولة بفواصل: DEBUG وINFO وNOTICE وWARNING وERROR وCRITICAL وALERT وEMERGENCY |
limit | int | عدد الإدخالات المطلوب إرجاعها (الافتراضي: 50، الحد الأقصى: 200) |
pageToken | سلسلة نصية | رمز ترقيم الصفحات من استجابة سابقة |
واجهة برمجة تطبيقات الوكلاء#
احفظ سير عمل الوكلاء وأدِره. تخزّن واجهة برمجة التطبيقات تعريفات الوكلاء؛ وتبدأ عمليات التشغيل من لوحة الوكلاء، حيث يفتح https://platform.ultralytics.com/agents?workflow={id} وكيلاً محفوظاً. تتطلب طرائق Python SDK ultralytics-platform>=0.1.74.
تقبل كل عملية معلّمة استعلام اختيارية باسم owner تحدد اسم المستخدم لمساحة عمل تنتمي إليها (الافتراضي: مساحة عملك). يتطلب عرض القوائم صلاحية المشاهدة؛ ويتطلب الحفظ والحذف صلاحية التحرير.
عرض الوكلاء#
GET /api/workflowsPython SDK: client.agents.list()
| المعلمة | النوع | الوصف |
|---|---|---|
owner | سلسلة نصية | اسم مستخدم مساحة العمل (الافتراضي: اسم المستخدم الخاص بك) |
id | سلسلة نصية | إرجاع وكيل واحد مع graph الخاص به |
search | سلسلة نصية | التصفية حسب اسم الوكيل |
تعرض الاستجابة ما يصل إلى 100 وكيل ضمن workflows، مرتبة من الأحدث تحديثاً إلى الأقدم، ويتضمن كل منها id وusername وname وversion وcreatedAt وupdatedAt. ويؤدي طلب id أيضاً إلى إرجاع graph الخاص بالوكيل.
حفظ وكيل#
PUT /api/workflowsPython SDK: client.agents.save(name=..., graph=..., version=...)
أرسل version: 0 لإنشاء وكيل. لتحديث وكيل، أرسل id وversion اللذين أعادتهما آخر عملية عرض قائمة أو حفظ؛ ويؤدي استخدام version قديم إلى إرجاع 409، لذا اعرض قائمة الوكلاء مجدداً ثم أعد المحاولة. وتؤدي بنية الرسم البياني التي تشكل اتصالاتها دورة أو تمنح كتلة أكثر من مُدخل واحد إلى إرجاع 400.
from ultralytics_platform import Platform
def block(node_id, kind, x, config):
return {
"id": node_id,
"type": "agent",
"position": {"x": x, "y": 0},
"data": {"label": kind, "type": kind, "config": config},
}
graph = {
"nodes": [
block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
block("output", "Output", 440, {}),
],
"edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
"templateId": "",
}
with Platform() as client:
saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
print(saved["id"], saved["version"], saved["errors"])تعيد الاستجابة id الخاص بالوكيل، وversion الجديد، وerrors: الكتل التي ستضع لوحة العمل علامة عليها، مثل كتلة Dataset التي لم تُحدَّد لها مجموعة بيانات. يُحفظ الوكيل في كلتا الحالتين. راجع openapi.json للاطلاع على جميع أنواع الكتل وإعداداتها.
حذف وكيل#
DELETE /api/workflows?id={id}Python SDK: client.agents.delete(id=...)
يحذف الوكيل ويلغي عمليات التشغيل النشطة الخاصة به. لا تظهر الوكلاء المحذوفة في سلة المحذوفات، ولا يمكن استعادتها.
واجهة برمجة تطبيقات سلة المحذوفات#
اعرض المشاريع ومجموعات البيانات والنماذج المحذوفة حذفاً مبدئياً، واستعدها أو احذفها نهائياً. تُحذف العناصر تلقائياً بعد 30 يوماً. راجع وثائق سلة المحذوفات.
عرض سلة المحذوفات#
GET /api/trashPython SDK: client.lifecycle.trash()
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
type | سلسلة نصية | all (افتراضي) أو project أو dataset أو model |
page | int | رقم الصفحة (الافتراضي: 1) |
limit | int | عدد العناصر في الصفحة (الافتراضي: 50، الحد الأقصى: 200) |
id | سلسلة نصية | استخدم type أو project أو model لمعاينة النماذج وعمليات النشر التي سيتأثر بها الحذف |
تتضمن الاستجابة items (ويتضمن كل عنصر منها daysRemaining) وtotal وpage وlimit وtotalPages وsummary الذي يحتوي على الإجماليات حسب النوع. وعند استخدام id، تُرجع الاستجابة بدلاً من ذلك resources: النماذج المتأثرة وعمليات النشر التي سيُحذف كل منها نهائياً.
استعادة عنصر#
POST /api/trashPython SDK: client.lifecycle.restore(id=..., type=...)
{
"id": "65f1c0a2b3d4e5f601234567",
"type": "dataset"
}تؤدي استعادة مشروع أيضاً إلى استعادة النماذج التي نُقلت إلى سلة المحذوفات معه، ويُبلّغ عنها في restoredModels.
الحذف نهائياً#
DELETE /api/trashPython SDK: client.lifecycle.delete_trash(body=...)
حذف عنصر واحد:
{
"id": "65f1c0a2b3d4e5f601234567",
"type": "dataset"
}أو إفراغ سلة المحذوفات بأكملها:
{
"all": true
}تُبلغ الاستجابة عن deletedCount، بالإضافة إلى cascadedModels وsurvivingDeployments عند الاقتضاء.
لا يمكن التراجع عن الحذف النهائي. يُزال المورد وجميع البيانات المرتبطة به.
واجهة برمجة تطبيقات الرفع#
ارفع الملفات مباشرةً إلى التخزين السحابي باستخدام عناوين URL موقّعة. يؤدي إكمال رفع نموذج إلى إرفاق أوزانه؛ أما إكمال رفع أرشيف مجموعة بيانات فيتحقق منه، ثم تمرر الجلسة إلى إدخال مجموعة البيانات، الذي يُكمل عملية الرفع نفسها أيضاً إذا تخطيت تلك الخطوة. راجع وثائق البيانات.
الحصول على عنوان URL موقّع للرفع#
POST /api/upload/signed-urlPython SDK: client.upload.signed_url(body=...)
النص:
{
"assetType": "datasets",
"assetId": "65f1c0a2b3d4e5f601234567",
"filename": "warehouse.zip",
"contentType": "application/zip",
"totalBytes": 52428800
}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
assetType | سلسلة نصية | نعم | datasets أو models |
assetId | سلسلة نصية | نعم | مُعرّف مجموعة البيانات أو النموذج المستهدف |
filename | سلسلة نصية | نعم | اسم الملف الأصلي (الحد الأقصى 256 حرفاً) |
contentType | سلسلة نصية | نعم | نوع MIME |
totalBytes | عدد | نعم | حجم الملف بالبايت |
عندما تكون قيمة assetType هي datasets، يجب أن ينتهي filename بـ .zip أو .tar أو .tar.gz أو .tgz أو .ndjson. اجمع الصور المنفردة في أرشيف قبل رفعها.
الاستجابة:
{
"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/completePython 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، وتصفحها كمصادر لمجموعات البيانات، وشغّل ميزات الذكاء الاصطناعي فيها أو أوقفها. راجع وثائق عمليات التكامل.
يتطلب اكتشاف التخزين وربطه صلاحية مسؤول مساحة العمل وخطة Pro أو Enterprise (وإلا فستكون 403)؛ ويتطلب عرض التكاملات واستعراض الكائنات صلاحية التحرير.
عرض التكاملات#
GET /api/integrations/bucketsPython SDK: client.storage_integrations.list()
يعيد integrations، ويحتوي كل عنصر على id وprovider وcredentialIdentity وtargets وprocessing (ما إذا كانت ميزات الذكاء الاصطناعي مفعّلة) وcreatedAt. لا تُعاد بيانات الاعتماد مطلقًا.
اكتشاف المواقع#
POST /api/integrations/buckets/discoverPython 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/bucketsPython SDK: client.storage_integrations.create(body=...)
تطابق بنية بيانات الاعتماد بنية الاكتشاف، مع إضافة مصفوفة مطلوبة targets تتضمن من 1 إلى 50 اسمًا للحاويات أو الحاويات المنطقية. يعيد 201 مع التكامل المخزّن. يتحقق الاتصال من صلاحية الكتابة لكل هدف من دون كتابة أي شيء. تُرفض بيانات اعتماد S3 المؤقتة (مفاتيح الوصول ASIA).
استعراض الكائنات#
GET /api/integrations/buckets/{id}/objectsPython SDK: client.storage_integrations.objects(id, target=...)
معلمات الاستعلام:
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
target | سلسلة نصية | نعم | اسم الدلو أو الحاوية |
prefix | سلسلة نصية | لا | بادئة المجلد (الحد الأقصى 1024 حرفاً) |
cursor | سلسلة نصية | لا | مؤشر ترقيم الصفحات لدى مزود الخدمة من صفحة سابقة |
تعيد entries (وتكون قيمة كل kind إما folder أو file) ومعها cursor اختياري للصفحة التالية.
ضبط ميزات الذكاء الاصطناعي#
PATCH /api/integrations/buckets/{id}Python SDK: client.storage_integrations.update(id, processing=False)
يشغّل ميزات الذكاء الاصطناعي ({"processing": true}) أو يوقفها لكل هدف في التكامل، ثم يعيد التكامل المحدّث. يؤدي إيقافها إلى منع بدء أعمال جديدة. يتطلب ذلك صلاحية مسؤول مساحة العمل.
إلغاء ربط التخزين#
DELETE /api/integrations/buckets/{id}Python SDK: client.storage_integrations.delete(id)
يزيل بيانات الاعتماد المحفوظة من دون حذف بيانات مزود الخدمة. تظل مجموعات البيانات المرتبطة ظاهرة، لكن يتعذر الوصول إلى ملفاتها حتى إعادة ربط حساب التخزين نفسه. يتطلب ذلك صلاحية مسؤول مساحة العمل.
واجهة برمجة تطبيقات استيراد مجموعات البيانات#
استورد مجموعات البيانات من خدمات الجهات الخارجية. راجع تكاملي Roboflow وLabel Studio.
معاينة استيراد Roboflow#
POST /api/integrations/roboflow/previewPython SDK: client.datasets.preview_roboflow(api_key=...)
يحلّ مفتاح API الخاص بـ Roboflow إلى خطة استيراد تتضمن تفاصيل مساحة العمل، وnewDatasets التي ستُستورد، وimportedDatasets التي سبق استيراد أحدث إصدار منها، وأعداد المشاريع المستوردة مسبقًا (skippedCount)، والتي لا إصدارات لها أو غير المدعومة أو التي تعذّر حلّها، وbytesTotal، والمساحة المتاحة لديك storage. تتضمن مجموعات البيانات الجديدة sizeBytes الخاص بالتصدير؛ أما مجموعات البيانات المستوردة مسبقًا فتتضمنه إذا أمكن تقدير حجم التصدير. يُعدّ apiKey اختياريًا: في غيابه، يُستخدم مفتاح Roboflow المحفوظ في مساحة العمل، وفي غياب المفتاحين، يُرجع الطلب 400. يُحفَظ المفتاح الذي يرسله مالك مساحة العمل لاستخدام مساحة العمل بمجرد أن يحلّ مساحة عمل Roboflow.
{
"apiKey": "ROBOFLOW_API_KEY"
}الاستيراد من Roboflow#
POST /api/integrations/roboflow/importPython SDK: client.datasets.import_roboflow(api_key=..., items=...)
يضع مهام الاستيعاب في قائمة الانتظار لما يصل إلى 500 إصدار محدد من مشاريع Roboflow، باستخدام العناصر التي أعادتها المعاينة. يُعدّ apiKey اختياريًا ويُستخدم المفتاح المحفوظ بديلًا عنه كما في المعاينة، لكنه لا يُحفَظ مطلقًا.
{
"apiKey": "ROBOFLOW_API_KEY",
"items": [
{
"workspace": "my-workspace",
"projectId": "warehouse-safety",
"projectName": "Warehouse Safety",
"projectType": "object-detection",
"latestVersion": 4
}
]
}الاستجابة (201): مصفوفات imported وfailed وskipped. تتطلب عمليات الاستيراد سعة تخزين متاحة، ويجب ألا يتجاوز حجم كل مجموعة بيانات الحد الأقصى لحجم الاستيراد في خطتك.
معاينة استيراد Label Studio#
POST /api/integrations/label-studio/previewPython SDK: client.datasets.preview_label_studio(api_key=...)
يسرد المشاريع في حساب Label Studio المستضاف المتصل على هيئة خطة استيراد: newDatasets وimportedDatasets (يحتوي كل منهما على projectId وprojectName والتقدير task وimageCount)، وunsupportedCount للمشاريع التي لا يمكن استيراد إعدادات وضع التسميات فيها، وstorage الخاص بك. يُعد apiKey رمز وصول شخصيًا أو رمزًا مميزًا قديمًا اختياريًا لـ Label Studio: يُستخدم الرمز المحفوظ لمساحة العمل عند عدم تقديمه، وإذا لم يتوفر أي منهما، يُعيد الطلب 409. لا يمكن إرسال رمز إلا من قِبل مالك مساحة العمل، ويُحفظ لمساحة العمل بمجرد إدراج المشاريع؛ وأي شخص آخر يرسله يحصل على 403.
{
"apiKey": "LABEL_STUDIO_ACCESS_TOKEN"
}الاستيراد من Label Studio#
POST /api/integrations/label-studio/importPython SDK: client.datasets.import_label_studio(project_ids=...)
يضع في قائمة الانتظار عملية استيراد واحدة لمجموعة بيانات لكل مشروع، لما يصل إلى 500 معرّف مشروع في Label Studio، باستخدام الرمز المحفوظ لمساحة العمل. وتُقرأ المهمة مجددًا من إعداد وضع التسميات لكل مشروع، لذا لا يمكن اختيارها في الطلب.
{
"projectIds": [101, 102]
}الاستجابة (201): مصفوفات imported وfailed وskipped. تتطلب عمليات الاستيراد مساحة تخزين متاحة؛ ويحصل كل مشروع على حصة متساوية منها، مع حد أقصى يحدده حد حجم الاستيراد في خطتك.
واجهة برمجة تطبيقات الحساب#
اطّلع على حسابك في Platform ومفاتيحك ومساحة التخزين وملفاتك الشخصية العامة. راجع وثائق الإعدادات.
ملخص الحساب#
GET /api/account/summaryPython SDK: client.account.summary()
تعيد الخطة ورصيد الاعتمادات وأعداد الموارد لمساحة العمل التي أصدرت المفتاح.
{
"username": "acme-vision",
"name": "Acme Vision",
"accountType": "team",
"plan": "pro",
"creditsCents": 2500,
"counts": { "projects": 4, "datasets": 7, "models": 21 },
"teams": []
}بالنسبة إلى الحساب الشخصي، تعرض teams مساحات عمل الفرق التي تنتمي إليها، ويتضمن كل منها role الخاص بك وdeniedReason عند تعذر الوصول إلى مساحة العمل حالياً، مثلاً بعد انتهاء صلاحية خطتها. أما مساحات عمل الفرق فتُرجع قائمة فارغة.
عرض مفاتيح API#
GET /api/api-keysPython SDK: client.account.api_keys()
تعيد keys مع keyId وname وkeyPrefix وcreatedAt لمساحة العمل المرتبطة بالمفتاح. لا تتلقى الطلبات الموثّقة بمفتاح API سوى البيانات الوصفية؛ أما القيم الكاملة للمفاتيح فتظهر لمالك مساحة العمل في الإعدادات > مفاتيح API ضمن واجهة مستخدم Platform، حيث تُنشأ المفاتيح وتُلغى أيضاً.
التحقق من استخدام التخزين#
GET /api/storagePython SDK: client.account.storage()
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
details | قيمة منطقية | تضمين أكبر عشرة مستهلكين لمساحة التخزين (الافتراضي: false) |
الاستجابة:
{
"tier": "pro",
"usage": {
"storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
"datasets": { "current": 2, "limit": -1, "percent": 0 },
"models": { "current": 4, "limit": 500, "percent": 1 }
},
"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"
}تعرض usage أعداد projects وdatasets وmodels وimages وannotations وdeployments، والبايتات لـ storage. وتعني قيمة limit البالغة -1 أن الحد غير محدود، بينما تمثل percent نسبة مئوية صحيحة من الحد.
الحصول على ملف شخصي عام لمستخدم#
GET /api/usersPython SDK: client.account.profile(username=...)
معلمات الاستعلام:
| المعلمة | النوع | مطلوب | الوصف |
|---|---|---|---|
username | سلسلة نصية | نعم | اسم المستخدم المطلوب البحث عنه |
تعيد الملف الشخصي العام user مع followerCount، ومع isFollowed للجهات المستدعية التي تمت مصادقتها.
متابعة مستخدم أو إلغاء متابعته#
PATCH /api/usersPython SDK: client.account.follow(username=..., followed=...)
{
"username": "target-user",
"followed": true
}الاستجابة: followed وfollowerCount بعد تحديثه.
واجهة API للفوترة#
تحقّق من استخدام الخطة وسجلّ الرصيد. راجع وثائق الفوترة.
مبالغ الفوترة أعداد صحيحة بالسنت الأمريكي، حيث 100 = $1.00.
عرض الخطة والاستخدام#
GET /api/billing/usage-summaryPython SDK: client.billing.usage_summary()
تعرض plan (المعرّف والحالة ودورة الفوترة ونهاية الفترة)، وmetrics (حد التخزين والاستخدام)، وtrainingCredit، وfeatures، وcreditsCents، وعدد المقاعد.
عرض المعاملات#
GET /api/billing/transactionsPython SDK: client.billing.transactions()
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
from | سلسلة نصية | الطابع الزمني لأقدم معاملة (ISO 8601) |
to | سلسلة نصية | الطابع الزمني لأحدث معاملة (ISO 8601) |
تتضمن كل معاملة id، وtype (مثل purchase أو training أو monthly_grant أو refund)، وamountCents، وbalanceAfter، وcreatedAt، وreceiptUrl اختياريًا، وسياق النموذج لرسوم التدريب. لا تُعاد تفاصيل الفوترة الداخلية مطلقًا.
واجهة API للاستكشاف#
ابحث في المشاريع ومجموعات البيانات والنماذج العامة التي يشاركها المجتمع، أو ابحث عن الصور بحسب ما تعرضه أو باستخدام صورة. راجع وثائق الاستكشاف.
البحث في المحتوى العام#
GET /api/explore/searchPython SDK: client.explore.search()
معلمات الاستعلام:
| المعلمة | النوع | الوصف |
|---|---|---|
q | سلسلة نصية | عبارة البحث (بحد أقصى 200 حرف)؛ في مجموعات البيانات والنماذج، تُطابق النصوص أولاً، ثم مجموعات البيانات التي تطابق صورها (أو النماذج المدرّبة عليها) |
type | سلسلة نصية | all (الافتراضي؛ للمشاريع ومجموعات البيانات)، أو projects، أو datasets، أو models، أو images (يتجاهل sort) |
sort | سلسلة نصية | relevance (الافتراضي)، أو newest، أو oldest، أو stars، أو name-asc، أو name-desc، أو count-desc، أو count-asc؛ يرتّب relevance نتائج مطابقة مجموعات البيانات والنماذج حسب q، وإلا فيعرض الأحدث أولاً |
offset | int | عدد النتائج المطلوب تخطيها (الافتراضي: 0) |
limit | int | الحد الأقصى للنتائج لكل نوع مورد (الافتراضي: 20، الحد الأقصى: 100) |
task | سلسلة نصية | عوامل تصفية المهام، مفصولة بفواصل: detect، segment، semantic، depth، classify، pose، obb |
license | سلسلة نصية | معرّفات التراخيص المفصولة بفواصل، مثل CC-BY-4.0,MIT؛ وتطابق الصور ترخيص مجموعة البيانات التابعة لها |
author | سلسلة نصية | عامل تصفية اسم المستخدم للمالك |
starred | قيمة منطقية | إرجاع المحتوى الذي أضافه المستخدم المصادق عليه إلى المفضلة فقط؛ يتطلب مفتاح API |
minImages | int | أعِد مجموعات البيانات التي تحتوي على هذا العدد من الصور على الأقل؛ ومع type=images، أعِد الصور من مجموعات البيانات هذه فقط |
maxImages | int | أعِد مجموعات البيانات التي لا يتجاوز عدد صورها هذا الحد؛ ومع type=images، أعِد الصور من مجموعات البيانات هذه فقط |
الاستجابة: projects وdatasets وhasMore. يعيد type=images التطابقات ضمن images بدلًا من ذلك، مرتبةً بدءًا بأفضل تطابق، ويتضمن كل تطابق مصدره dataset ودرجة تشابه من 0 إلى 1 هي score؛ وباستخدام q، يبحث في مجموعات البيانات العامة، إضافةً إلى مجموعات بياناتك ومجموعات بيانات فريقك عند إرسال مفتاح API. ومن دون q، يعرض صورة واحدة من كل مجموعة بيانات عامة حديثة، من دون ترتيب، مع score و1، مع مراعاة عوامل التصفية.
يعرض type=models النماذج العامة ضمن models، نموذجاً واحداً لكل مجموعة بيانات تدريب (أو لكل مشروع إذا لم توجد مجموعة بيانات)، باستثناء نماذج @ultralytics الرسمية التي تحتفظ كل منها بإدخال مستقل؛ ويستبعد النماذج المستنسخة والنماذج التي لم يكتمل تدريبها. عند استخدام q، تظهر النماذج الرسمية المطابقة أولاً، تليها النماذج التي يطابق اسمها أو مشروعها الاستعلام، ثم النماذج المدرّبة على مجموعات البيانات العامة التي تتطابق صورها معه بأفضل شكل. في غياب q، يعرض النماذج المدرّبة على مجموعات بيانات عامة، بدءاً بالأحدث. يراعي task وauthor، ويفرز حسب relevance أو newest أو oldest؛ أما خيارات الفرز الأخرى فتعرض الأحدث أولاً.
curl "https://platform.ultralytics.com/api/explore/search?type=datasets&task=detect&sort=stars&limit=20"البحث باستخدام صورة#
POST /api/explore/searchPython SDK: client.explore.search_by_image() (ultralytics-platform>=0.1.107)
أرسل صورة بترميز base64 image (بحجم لا يتجاوز 3 MiB ولا تُخزَّن مطلقاً) ضمن متن JSON مع type وimages (الافتراضي) أو datasets أو models، وأي من sort وoffset وlimit وtask وlicense وauthor وstarred وminImages وmaxImages، باستخدام البحث في المحتوى العام. تكون الاستجابة بالتنسيق نفسه، كما أن الطلب الذي يرسل image يعيد أيضاً vector: أرسله بدلاً من image لعرض صفحات إضافية أو عوامل تصفية أخرى أو type آخر، كي تُقرأ الصورة مرة واحدة فقط. يعيد type=images صوراً مع درجاتها كما يفعل البحث النصي؛ ويعيد type=datasets مجموعات البيانات العامة التي تتضمن صوراً مطابقة، بدءاً بأفضل تطابق وفق sort=relevance الافتراضي (أما خيارات الفرز الأخرى فترتبها كالمعتاد)، وتتصدر هذه الصور بطاقة كل مجموعة بيانات ضمن sampleImages؛ ويعيد type=models النماذج العامة المدرّبة على تلك المجموعات، بدءاً بالأفضل تطابقاً. يُحتسب كل طلب يرسل image أيضاً ضمن حد مستقل يبلغ 20 طلباً في الدقيقة لكل مستخدم (ولكل عنوان IP عند عدم استخدام مفتاح API). يعني 400 وجود معلمات غير صالحة أو تعذّر قراءة الصورة، بينما يعني 503 أن خدمة البحث مشغولة؛ أعد المحاولة بعد قليل.
حزمة Python SDK#
يُعدّ ultralytics-platform عميل Python مولّدًا ذا أنواع محددة استنادًا إلى عقد OpenAPI، ويضم طريقة واحدة لكل نقطة نهاية (client.datasets.list، وclient.models.predict، وclient.exports.create، ...). تقبل كل طريقة معلمات المسار موضعيًا، وسائر المدخلات كوسائط كلمات مفتاحية، إضافة إلى timeout وextra_headers الاختياريين لكل طلب.
pip install "ultralytics-platform>=0.1.45" # Python 3.11+from ultralytics_platform import Platform
with Platform() as client: # يقرأ ULTRALYTICS_API_KEY أو المفتاح المحفوظ بواسطة 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#
لسير عمل التدريب والاستدلال، استخدم حزمة Ultralytics Python، التي تتولى المصادقة والتحميلات وبث المقاييس في الوقت الفعلي تلقائيًا. في Python 3.11 والإصدارات الأحدث، تثبّت pip install ultralytics أيضًا حزمة SDK المسماة ultralytics-platform. عندما يستهدف model.train(project=...) منصة Platform، تبث استدعاءات التدريب الراجعة الأحداث عبر client.training.metrics() التابعة لحزمة SDK، وتطلب عناوين URL لتحميل نقاط التحقق عبر client.models.upload_checkpoint()، وهما العمليتان POST /api/webhooks/training/metrics وPOST /api/webhooks/models/upload في مستند OpenAPI، لذا لا حاجة إلى استدعائهما بنفسك.
التثبيت والإعداد#
يتطلب التكامل مع Platform 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")
# درّب باستخدام مجموعة بيانات Platform الخاصة بك
model.train(
data="ul://your-username/datasets/your-dataset",
epochs=100,
imgsz=640,
)تنسيق URI:
| النمط | الوصف |
|---|---|
ul://username/datasets/slug | مجموعة البيانات |
ul://username/project/model-name | نموذج محدد |
ul://ultralytics/yolo26/yolo26n | نموذج رسمي |
الإرسال إلى Platform#
أرسل النتائج إلى مشروع على Platform:
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
# تُزامَن النتائج تلقائيًا مع Platform
model.train(
data="coco8.yaml",
epochs=100,
project="your-username/my-project",
name="experiment-1",
)ما تتم مزامنته:
- مقاييس التدريب (في الوقت الفعلي)
- أوزان النموذج النهائية
- مخططات التحقق
- مخرجات وحدة التحكم
- مقاييس النظام
- وسيطات التدريب وبيئة المضيف (اسم المضيف ونظام التشغيل وPython والأجهزة وإيداع git وسطر الأوامر)
أمثلة على API#
تحميل نموذج من Platform:
# نموذجك الخاص
model = YOLO("ul://username/project/model-name")
# نموذج رسمي
model = YOLO("ul://ultralytics/yolo26/yolo26n")تنفيذ الاستدلال:
results = model("image.jpg")
# الوصول إلى النتائج
for r in results:
boxes = r.boxes # مربعات الكشف
masks = r.masks # أقنعة التجزئة
keypoints = r.keypoints # نقاط مفاصل الوضعية
probs = r.probs # احتمالات التصنيفتصدير النموذج:
# التصدير إلى ONNX
model.export(format="onnx", imgsz=640, quantize=16)
# التصدير إلى TensorRT
model.export(format="engine", imgsz=640, quantize=16)
# التصدير إلى CoreML
model.export(format="coreml", imgsz=640) # استخدم imgsz=224 للتصنيفالتحقق:
metrics = model.val(data="ul://username/datasets/my-dataset")
print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")الأسئلة الشائعة#
استخدم مقاطع اسم المالك والاسم نفسها الظاهرة في عنوان URL الخاص بـ Platform. النموذج الموجود في
https://platform.ultralytics.com/acme-vision/inspection/v3هوGET /api/models/acme-vision/inspection/v3. تظل معرّفات قاعدة البيانات مُعادة في الاستجابات (على هيئةid)، وتتطلبها بعض المسارات مباشرةً — إذ تتطلب مسارات الصورimageId، وتتطلب عمليات التحميلassetId، بينما تتطلبPOST /api/training/startقيمةmodelId.يعتمد ذلك على المجموعة. تقبل معظم نقاط نهاية القوائم
limit:curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://platform.ultralytics.com/api/datasets/acme-vision?limit=50"تستخدم صور مجموعة البيانات والتجميع والبحث في Explore
offsetمعlimit، وتُبلغ عنhasMore:curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&limit=20&sort=stars"من الأفضل التنقل بين مجموعات الصور الكبيرة باستخدام المؤشر المُعاد على هيئة
nextCursor:curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://platform.ultralytics.com/api/datasets/acme-vision/warehouse/images?limit=1000&includeTotal=false&cursor=NEXT_CURSOR"تستخدم سلة المهملات
page، بينما تستخدم سجلات النشرpageTokenالمعتمة المُعادة على هيئةnextPageToken.نعم. كل عملية في هذه الصفحة هي طلب HTTPS عادي، والعقد الكامل منشور بتنسيق OpenAPI 3.2 على platform.ultralytics.com/openapi.json، ويمكنك تمريره إلى مولّد عميل بأي لغة. حزمة
ultralytics-platformهي تحديدًا عميل ذو أنواع محددة، مولّد من العقد، بينما تضيف حزمةultralyticsبث المقاييس في الوقت الفعلي والتحميل التلقائي للنماذج إلى التدريب والاستدلال. أما تدفقات الحساب التي تقتصر على جلسة المتصفح، مثل الدفع للفوترة وإدارة الفرق، فتبقى ضمن واجهة مستخدم Platform.استخدم الترويسة
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")يعني
404أن المورد غير موجود أو أنه غير مرئي لمفتاحك إطلاقًا. أما403فيعني العثور على المورد، لكن الإجراء يتطلب صلاحيات تتجاوز ما يتيحه مفتاحك — مثل صلاحية المحرر لتعديل مجموعة بيانات، أو صلاحية المالك لحذف عملية نشر، أو صلاحية المسؤول لفصل التخزين، أو خطة أو حصة أعلى للتصدير وعمليات النشر.قراءة مجموعات البيانات والمشاريع والنماذج العامة، بما في ذلك صورها وعناوين URL الموقعة للصور وإحصاءات الفئات وحالة التضمين وتخطيط التجميع والنماذج المدرّبة على مجموعة بيانات وقائمة التصدير؛ والتحقق من تقدم التدريب على نموذج عام؛ وتنزيل ملفات نموذج عام؛ وإنشاء رابط استيراد للهاتف المحمول لتصدير نموذج عام؛ وتشغيل الاستدلال على نموذج عام؛ والبحث عن ملف تعريف مستخدم عام؛ وإدراج عمليات النشر مع تصفيتها حسب نموذج عام واحد؛ والبحث في Explore. تكون
GET /api/training/gpu-availabilityعامة بالكامل ما لم تطلب سعة مُدارة. وتتطلب جميع العمليات الأخرى مفتاحًا، كما أن تقديم مفتاح إلى نقطة نهاية عامة يكشف أيضًا عن مواردك الخاصة.
التعليقات
اطرح سؤالًا، وشارك نتائجك، أو ساعد شخصًا آخر.