İçeriğe geç

REST API Referansı

Ultralytics Platform, veri kümelerine, modellere, eğitime ve dağıtımlara programatik erişim için kapsamlı bir REST API sağlar.

Hızlı Başlangıç

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

# Run inference on a model
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

Kimlik Doğrulama

Tüm API istekleri, API anahtarı aracılığıyla kimlik doğrulama gerektirir.

API Anahtarını Al

  1. Ayarlar > API Anahtarları bölümüne gidin
  2. Anahtar Oluştur düğmesine tıklayın
  3. Oluşturulan anahtarı kopyalayın

Ayrıntılı talimatlar için API Anahtarları bölümüne bakın.

Yetkilendirme Başlığı

API anahtarınızı tüm isteklere dahil edin:

Authorization: Bearer ul_your_api_key_here

Örnek

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

Temel URL

Tüm API uç noktaları şunları kullanır:

https://platform.ultralytics.com/api

Hız Sınırları

Planİstek/Dakikaİstek/Gün
Ücretsiz601,000
Pro30050,000
KurumsalÖzelÖzel

Hız sınırı başlıkları yanıtlara dahil edilmiştir:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

Yanıt Biçimi

Tüm yanıtlar JSON formatındadır:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Hata Yanıtları

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid dataset ID",
    "details": { ... }
  }
}

Veri Kümeleri API'si

Veri Kümelerini Listeleme

GET /api/datasets

Sorgu Parametreleri:

ParametreTürAçıklama
pageintSayfa numarası (varsayılan: 1)
limitintSayfa başına öğe sayısı (varsayılan: 20)
taskstringGörev türüne göre filtrele

Yanıt:

{
    "success": true,
    "data": [
        {
            "id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "visibility": "private",
            "createdAt": "2024-01-15T10:00:00Z"
        }
    ]
}

Veri Kümesini Al

GET /api/datasets/{datasetId}

Veri Kümesi Oluştur

POST /api/datasets

Gövde:

{
    "name": "my-dataset",
    "task": "detect",
    "description": "A custom detection dataset"
}

Veri Kümesini Sil

DELETE /api/datasets/{datasetId}

Veri Kümesini Dışa Aktar

POST /api/datasets/{datasetId}/export

NDJSON formatında indirme URL'si döndürür.

Veri Kümesi Üzerinde Eğitimli Modeller Alın

GET /api/datasets/{datasetId}/models

Bu veri kümesi kullanılarak eğitilmiş modellerin listesini döndürür ve veri kümeleri ile bunların ürettiği modeller arasındaki ilişkiyi gösterir.

Yanıt:

{
    "success": true,
    "data": [
        {
            "id": "model_abc123",
            "name": "experiment-1",
            "projectId": "project_xyz",
            "trainedAt": "2024-01-15T10:00:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72
            }
        }
    ]
}

Projeler API'si

Projeleri Listele

GET /api/projects

Proje Al

GET /api/projects/{projectId}

Proje Oluştur

POST /api/projects

Gövde:

{
    "name": "my-project",
    "description": "Detection experiments"
}

Projeyi Sil

DELETE /api/projects/{projectId}

Modeller API'si

Modelleri Listele

GET /api/models

Sorgu Parametreleri:

ParametreTürAçıklama
projectIdstringProjeye göre filtrele
taskstringGörev türüne göre filtrele

Model Al

GET /api/models/{modelId}

Model Yükle

POST /api/models

Çok Parçalı Form:

AlanTürAçıklama
filedosyasıModel .pt dosyası
projectIdstringHedef proje
namestringModel adı

Modeli Sil

DELETE /api/models/{modelId}

Modeli İndir

GET /api/models/{modelId}/files

Model dosyaları için imzalı indirme URL'leri döndürür.

Çıkarım Çalıştır

POST /api/models/{modelId}/predict

Çok Parçalı Form:

AlanTürAçıklama
filedosyasıGörüntü dosyası
conffloatGüven eşiği
ioufloatIoU eşiği

Yanıt:

{
    "success": true,
    "predictions": [
        {
            "class": "person",
            "confidence": 0.92,
            "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
        }
    ]
}

Eğitim API'si

Eğitime Başla

POST /api/training/start

Gövde:

{
    "modelId": "model_abc123",
    "datasetId": "dataset_xyz789",
    "epochs": 100,
    "imageSize": 640,
    "gpuType": "rtx-4090"
}

Eğitim Durumunu Al

GET /api/models/{modelId}/training

Eğitimi İptal Et

DELETE /api/models/{modelId}/training

Dağıtımlar API'si

Dağıtımları Listele

GET /api/deployments

Sorgu Parametreleri:

ParametreTürAçıklama
modelIdstringModele göre filtrele

Dağıtım Oluştur

POST /api/deployments

Gövde:

{
    "modelId": "model_abc123",
    "region": "us-central1",
    "minInstances": 0,
    "maxInstances": 10
}

Dağıtım Al

GET /api/deployments/{deploymentId}

Dağıtımı Başlat

POST /api/deployments/{deploymentId}/start

Dağıtımı Durdur

POST /api/deployments/{deploymentId}/stop

Dağıtımı Sil

DELETE /api/deployments/{deploymentId}

Metrikleri Al

GET /api/deployments/{deploymentId}/metrics

Logları Al

GET /api/deployments/{deploymentId}/logs

Sorgu Parametreleri:

ParametreTürAçıklama
severitystringBİLGİ, UYARI, HATA
limitintGirdi sayısı

Dışa Aktarım API'si

Dışa Aktarımları Listele

GET /api/exports

Dışa Aktarım Oluştur

POST /api/exports

Gövde:

{
    "modelId": "model_abc123",
    "format": "onnx"
}

Desteklenen Formatlar:

onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch

Dışa Aktarım Durumunu Al

GET /api/exports/{exportId}

Etkinlik API'si

Hesabınızdaki etkinlikleri track edin ve yönetin.

Etkinliği Listele

GET /api/activity

Sorgu Parametreleri:

ParametreTürAçıklama
startDatestringBaşlangıç tarihine göre filtrele (ISO)
endDatestringBitiş tarihine göre filtrele (ISO)
searchstringEtkinlik mesajlarında ara

Olayları Görüldü Olarak İşaretle

POST /api/activity/mark-seen

Olayları Arşivle

POST /api/activity/archive

Çöp Kutusu API'si

Geçici olarak silinmiş kaynakları yönetin (30 günlük saklama süresi).

Çöp Kutusunu Listele

GET /api/trash

Öğeyi Geri Yükle

POST /api/trash

Gövde:

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

Çöp Kutusunu Boşalt

POST /api/trash/empty

Çöp kutusundaki tüm öğeleri kalıcı olarak siler.

Faturalandırma API'si

Kredileri ve abonelikleri yönetin.

Bakiye Al

GET /api/billing/balance

Yanıt:

{
    "success": true,
    "data": {
        "cashBalance": 5000000,
        "creditBalance": 20000000,
        "reservedAmount": 0,
        "totalBalance": 25000000
    }
}

Mikro-USD

Tüm tutarlar, hassas muhasebe için mikro-USD (1.000.000 = 1,00 ABD doları) cinsindendir.

Kullanım Özetini Al

GET /api/billing/usage-summary

Plan ayrıntılarını, limitlerini ve kullanım metriklerini döndürür.

Ödeme Oturumu Oluştur

POST /api/billing/checkout-session

Gövde:

{
    "amount": 25
}

Kredi satın alımı (5-1000 ABD doları) için bir Stripe ödeme oturumu oluşturur.

Abonelik Ödemesi Oluştur

POST /api/billing/subscription-checkout

Pro aboneliği için bir Stripe ödeme oturumu oluşturur.

Portal Oturumu Oluştur

POST /api/billing/portal-session

Abonelik yönetimi için Stripe faturalandırma portalına URL döndürür.

Ödeme Geçmişini Al

GET /api/billing/payments

Stripe'tan ödeme işlemlerinin listesini döndürür.

Depolama API'si

Depolama Bilgisi Al

GET /api/storage

Yanıt:

{
    "success": true,
    "data": {
        "used": 1073741824,
        "limit": 107374182400,
        "percentage": 1.0
    }
}

GDPR API'si

Veri dışa aktarımı ve silme için GDPR uyumluluk uç noktaları.

Hesap Verilerini Dışa Aktar/Sil

POST /api/gdpr

Gövde:

{
    "action": "export"
}
EylemAçıklama
exportTüm hesap verilerini indir
deleteHesabı ve tüm verileri sil

Geri Alınamaz Eylem

Hesap silme işlemi kalıcıdır ve geri alınamaz. Tüm veriler, modeller ve dağıtımlar silinecektir.

API Anahtarları API'si

API Anahtarlarını Listele

GET /api/api-keys

API Anahtarı Oluştur

POST /api/api-keys

Gövde:

{
    "name": "training-server",
    "scopes": ["training", "models"]
}

API Anahtarını Sil

DELETE /api/api-keys/{keyId}

Hata Kodları

KodAçıklama
UNAUTHORIZEDGeçersiz veya eksik API anahtarı
FORBIDDENYetersiz izinler
NOT_FOUNDKaynak bulunamadı
VALIDATION_ERRORGeçersiz istek verileri
RATE_LIMITEDÇok fazla istek
INTERNAL_ERRORSunucu hatası

Python

Daha kolay entegrasyon için Ultralytics Python paketini kullanın.

Kurulum

pip install ultralytics

Kurulumu doğrulayın:

yolo check

Paket Sürüm Gereksinimi

Platform entegrasyonu ultralytics>=8.4.0 sürümünü gerektirir. Daha düşük sürümler Platform ile ÇALIŞMAZ.

Kimlik Doğrulama

Yöntem 1: CLI (Önerilen)

yolo settings api_key=YOUR_API_KEY

Yöntem 2: Ortam Değişkeni

export ULTRALYTICS_API_KEY=YOUR_API_KEY

Yöntem 3: Kodda

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Platform Veri Kümelerini Kullanma

Referans veri kümeleri ile ul:// URI'ler:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/your-dataset",
    epochs=100,
    imgsz=640,
)

URI Biçimi:

ul://{username}/{resource-type}/{name}

Examples:
ul://john/datasets/coco-custom     # Dataset
ul://john/my-project               # Project
ul://john/my-project/exp-1         # Specific model
ul://ultralytics/yolo26/yolo26n    # Official model

Platforma Aktarma

Sonuçları bir Platform projesine gönder:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="ul://your-username/my-project",
    name="experiment-1",
)

Neler senkronize edilir:

  • Eğitim metrikleri (gerçek zamanlı)
  • Nihai model ağırlıkları
  • Doğrulama grafikleri
  • Konsol çıktısı
  • Sistem ölçümleri

API Örnekleri

Platformdan bir model yükleyin:

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

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

Çıkarım çalıştır:

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

İhracat modeli:

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

Doğrulama:

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

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

Webhook'lar

Web kancaları, sunucunuzu Platform olayları hakkında bilgilendirir:

OlayAçıklama
training.startedEğitim işi başlatıldı
training.epochEpoch tamamlandı
training.completedEğitim tamamlandı
training.failedEğitim başarısız oldu
export.completedDışa aktarmaya hazır

Webhook kurulumu Kurumsal planlarda mevcuttur.

SSS

Büyük sonuçları nasıl sayfalandırırım?

Kullanım page ve limit parametreler:

GET /api/datasets?page=2 &
limit=50

API'yi bir SDK olmadan kullanabilir miyim?

Evet, tüm işlevsellik REST aracılığıyla kullanılabilir. SDK bir kolaylık sarmalayıcısıdır.

API istemci kütüphaneleri mevcut mu?

Şu anda, Ultralytics python paketini kullanın veya doğrudan HTTP istekleri yapın. Diğer diller için resmi istemci kütüphaneleri planlanmaktadır.

Hız sınırlarını nasıl yönetirim?

Üstel geri çekilmeyi uygulayın:

import time


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


📅 20 gün önce oluşturuldu ✏️ 14 gün önce güncellendi
glenn-jocherLaughing-q

Yorumlar