مرجع REST API

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

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

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

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

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

المصادقة

تتطلب معظم طلبات API المصادقة عبر مفتاح API. تدعم نقاط النهاية العامة (قائمة مجموعات البيانات العامة والمشاريع والنماذج) الوصول للقراءة بشكل مجهول دون مفتاح.

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

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

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

رأس التفويض

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

Authorization: Bearer YOUR_API_KEY

مثال

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

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const data = await response.json();

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

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

https://platform.ultralytics.com/api

حدود المعدل

تستخدم واجهة برمجة التطبيقات (API) نظامًا مزدوج الطبقات لتقييد معدل الاستخدام لحماية النظام من إساءة الاستخدام مع الحفاظ على الاستخدام المشروع دون قيود:

• لكل مفتاح API — يتم فرض القيود لكل مفتاح API على الطلبات المصادق عليها
• لكل عنوان IP — 100 طلب/دقيقة لكل عنوان IP على جميع /api/* المسارات (ينطبق على الطلبات المصادق عليها وغير المصادق عليها)

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

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

وفقًا لحدود مفتاح API

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

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

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

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

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

ردود النجاح

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

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

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

{
    "error": "Dataset not found"
}

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

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

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

GET /api/datasets

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

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

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

الاستجابة:

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

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

GET /api/datasets/{datasetId}

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

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

POST /api/datasets

الجسم:

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

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

PATCH /api/datasets/{datasetId}

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

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

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

DELETE /api/datasets/{datasetId}

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

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

POST /api/datasets/{datasetId}/clone

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

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

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

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

GET /api/datasets/{datasetId}/export

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

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

الاستجابة:

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

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

POST /api/datasets/{datasetId}/export

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

نص الطلب:

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

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

الاستجابة:

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

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

PATCH /api/datasets/{datasetId}/export

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

نص الطلب:

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

الاستجابة:

{
    "ok": true
}

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

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

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

الاستجابة:

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

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

GET /api/datasets/{datasetId}/models

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

الاستجابة:

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

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

POST /api/datasets/{datasetId}/predict

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

الجسم:

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

POST /api/datasets/ingest

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

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

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

قائمة الصور

GET /api/datasets/{datasetId}/images

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

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

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

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

حذف الصورة

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

الحصول على تسميات الصور

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

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

تحديث تسميات الصور

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

الجسم:

{
    "labels": [{ "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] }]
}

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

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

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

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

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

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

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

سرد المشاريع

GET /api/projects

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

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

GET /api/projects/{projectId}

إنشاء مشروع

POST /api/projects

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

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

تحديث المشروع

PATCH /api/projects/{projectId}

حذف المشروع

DELETE /api/projects/{projectId}

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

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

POST /api/projects/{projectId}/clone

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

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

POST /api/projects/{projectId}/icon

إزالة رمز المشروع:

DELETE /api/projects/{projectId}/icon

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

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

سرد النماذج

GET /api/models

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

قائمة النماذج المكتملة

GET /api/models/completed

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

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

GET /api/models/{modelId}

إنشاء نموذج

POST /api/models

نص JSON:

تحديث النموذج

PATCH /api/models/{modelId}

حذف النموذج

DELETE /api/models/{modelId}

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

GET /api/models/{modelId}/files

يعيد عناوين URL موقعة لتنزيل ملفات النموذج.

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

POST /api/models/{modelId}/clone

استنساخ نموذج عام إلى أحد مشاريعك.

الجسم:

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

تتبع التنزيل

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

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

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

POST /api/models/{modelId}/predict

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

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

الاستجابة:

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

احصل على رمز Predict

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

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

نموذج الإحماء

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

قم بتحميل نموذج مسبقًا للحصول على استنتاج أول أسرع. قم باستدعاء هذا قبل تشغيل التنبؤات لتجنب التأخير في الطلب الأولي.

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

ابدأ YOLO على وحدات معالجة الرسومات السحابية (RTX 4090، A100، H100) وتابع التقدم المحرز في الوقت الفعلي. راجع وثائق التدريب السحابي.

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

ابدأ التدريب

POST /api/training/start

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

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo26n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

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

GET /api/models/{modelId}/training

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

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

DELETE /api/models/{modelId}/training

ينهي تشغيل مثيل الحوسبة ويضع علامة على المهمة على أنها ملغاة.

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

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

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

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

GET /api/deployments

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

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

POST /api/deployments

الجسم:

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

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

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

GET /api/deployments/{deploymentId}

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

DELETE /api/deployments/{deploymentId}

بدء عملية النشر

POST /api/deployments/{deploymentId}/start

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

إيقاف عملية النشر

POST /api/deployments/{deploymentId}/stop

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

فحص السلامة

GET /api/deployments/{deploymentId}/health

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

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

POST /api/deployments/{deploymentId}/predict

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

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

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

GET /api/deployments/{deploymentId}/metrics

يعرض عدد الطلبات المرتجعة ومقاييس زمن الاستجابة ومعدل الأخطاء مع بيانات sparkline.

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

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

GET /api/deployments/{deploymentId}/logs

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

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

المقاييس المجمعة

GET /api/monitoring

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

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

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

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

GET /api/exports

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

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

POST /api/exports

الجسم:

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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

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

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

GET /api/exports/{exportId}

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

DELETE /api/exports/{exportId}

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

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

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

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

سرد النشاط

GET /api/activity

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

وضع علامة على الأحداث المشاهدة

POST /api/activity/mark-seen

الجسم:

{
    "all": true
}

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

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

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

POST /api/activity/archive

الجسم:

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

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

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

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

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

عرض سلة المهملات

GET /api/trash

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

استعادة عنصر

POST /api/trash

الجسم:

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

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

DELETE /api/trash

الجسم:

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

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

DELETE /api/trash/empty

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

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

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

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

GET /api/billing/balance

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

الاستجابة:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

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

GET /api/billing/usage-summary

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

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

GET /api/billing/transactions

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

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

إنشاء جلسة إتمام الدفع

POST /api/billing/checkout-session

الجسم:

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

ينشئ جلسة دفع لشراء الرصيد.

إنشاء إتمام دفع الاشتراك

POST /api/billing/subscription-checkout

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

الجسم:

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

إنشاء جلسة بوابة

POST /api/billing/portal-session

يعيد عنوان URL إلى بوابة الفوترة لإدارة الاشتراك.

تعبئة تلقائية

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

الحصول على تكوين إعادة التعبئة التلقائية

GET /api/billing/auto-topup

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

تحديث إعدادات التعبئة التلقائية

PATCH /api/billing/auto-topup

الجسم:

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

طرق الدفع

قائمة طرق الدفع

GET /api/billing/payment-methods

إنشاء نية إعداد

POST /api/billing/payment-methods/setup

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

تعيين طريقة الدفع الافتراضية

POST /api/billing/payment-methods/default

الجسم:

{
    "paymentMethodId": "pm_123"
}

تحديث معلومات الفوترة

PATCH /api/billing/payment-methods

الجسم:

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

حذف طريقة الدفع

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

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

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

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

GET /api/storage

الاستجابة:

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

إعادة حساب السعة التخزينية

POST /api/storage

يؤدي إلى إعادة حساب استخدام التخزين.

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

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

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

POST /api/upload/signed-url

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

الجسم:

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

الاستجابة:

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

اكتمال التحميل

POST /api/upload/complete

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

الجسم:

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

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

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

عرض مفاتيح API

GET /api/api-keys

إنشاء مفتاح API

POST /api/api-keys

الجسم:

{
    "name": "training-server"
}

حذف مفتاح API

DELETE /api/api-keys

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

مثال:

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

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

أنشئ مساحات عمل للفرق، وادعُ الأعضاء، وادِر الأدوار للتعاون. انظر وثائق الفرق.

قائمة الفرق

GET /api/teams

إنشاء فريق

POST /api/teams/create

الجسم:

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

قائمة الأعضاء

GET /api/members

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

دعوة عضو

POST /api/members

الجسم:

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

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

PATCH /api/members/{userId}

إزالة عضو

DELETE /api/members/{userId}

نقل الملكية

POST /api/members/transfer-ownership

دعوات

قبول الدعوة

POST /api/invites/accept

احصل على معلومات الدعوة

GET /api/invites/info

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

إلغاء الدعوة

DELETE /api/invites/{inviteId}

إعادة إرسال الدعوة

POST /api/invites/{inviteId}/resend

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

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

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

GET /api/explore/search

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

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

GET /api/explore/sidebar

يعرض محتوى مختارًا للشريط الجانبي "استكشاف".

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

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

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

GET /api/users

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

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

PATCH /api/users

الجسم:

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

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

GET /api/username/check

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

الإعدادات

GET /api/settings
POST /api/settings

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

أيقونة الملف الشخصي

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

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

التأهيل

POST /api/onboarding

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

واجهة برمجة تطبيقات GDPR

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

احصل على حالة وظيفة GDPR

GET /api/gdpr

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

يعرض حالة المهمة. بالنسبة لمهام التصدير المكتملة، تتضمن الاستجابة downloadUrl.

بدء التصدير أو حذف التدفق

POST /api/gdpr

الجسم:

{
    "action": "export"
}

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

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

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

رموز الأخطاء

Python

لتسهيل عملية التكامل، استخدمPython Ultralytics Python التي تتولى المصادقة والتحميل وتدفق المقاييس في الوقت الفعلي تلقائيًا.

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

pip install ultralytics

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

yolo check

المصادقة

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

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

مجموعات البيانات المرجعية مع ul:// URIs:

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

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

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

أمثلة على واجهة برمجة التطبيقات

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

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

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

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

results = model("image.jpg")

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

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

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

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

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

التحقق من الصحة:

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

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

Webhooks

تقوم Webhooks بإخطار الخادم الخاص بك بأحداث المنصة عبر استدعاءات HTTP POST:

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

كيف يمكنني تقسيم النتائج الكبيرة إلى صفحات؟

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

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

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

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

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

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

هل يمكنني استخدام واجهة برمجة التطبيقات (API) بدون حزمة تطوير البرامج (SDK)؟

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

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

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

كيف أتعامل مع قيود المعدل؟

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

import time

import requests


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

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

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

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

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

📅 تم الإنشاء قبل 2 أشهر ✏️ تم التحديث قبل 4 أيام

تعليقات