REST API Referansı#

Ultralytics Platform, veri kümelerine, görüntülere, projelere, modellere, eğitime, dışa aktarımlara ve dağıtımlara programatik erişim için bir REST API sağlar.

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

API'ye Genel Bakış#

API, temel Platform kaynakları etrafında düzenlenmiştir:

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

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

Kimlik Doğrulama#

Çoğu uç nokta bir API anahtarı gerektirir. Genel içeriği açığa çıkaran uç noktalar — genel bir veri kümesini, projeyi veya modeli okuma, genel veri kümesi görüntülerini listeleme, genel bir model üzerinde çıkarım çalıştırma ya da Keşfet'te arama — anonim istekleri de kabul eder ve bir anahtar sağlandığında yalnızca daha fazla sonuç döndürür.

API Anahtarı Alma#

1. Settings > API Keys konumuna git
2. Create Key seçeneğine tıkla
3. Oluşturulan anahtarı kopyala

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

Yetkilendirme Üst Bilgisi#

API anahtarını bearer token olarak ekle:

Authorization: Bearer YOUR_API_KEY

Örnek#

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

Temel URL#

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

https://platform.ultralytics.com/api

Kaynak Yolları#

Kaynaklara, veritabanı kimlikleriyle değil, Platform URL'lerinde görünen insan tarafından okunabilir adlarla erişilir:

• {owner}, kişisel kullanıcı adı veya ekip çalışma alanı tanıtıcısıdır: 4-32 karakter; bölümler arasında tek kısa çizgi bulunan, küçük harfli alfasayısal yapıdadır.
• {dataset}, {project}, {model} ve {deployment} aynı küçük harfli, kısa çizgilerle ayrılmış biçimi izler ve en fazla 128 karakter olabilir.
• {imageId} ve {exportId}, API tarafından döndürülen 24 karakterli onaltılık kimliklerdir.
• Bir kaynağı PATCH üzerinden yeniden adlandırmak, görünen name değerini ve URL adını birlikte değiştirir; yanıt, onu izlemeye devam edebilmen için geçerli URL adını döndürür.

İstek Sınırları#

API, her API anahtarı için kayan pencere sınırları uygular. Her rota bir kategoriye girer ve her kategorinin bağımsız bir sayacı vardır; bu nedenle 20 tahmin isteği varsayılan kullanım hakkını tüketmez.

Faturalandırma ödeme sayfası ve ekip yönetimi gibi yalnızca tarayıcıya özel Platform rotalarının, API anahtarı trafiği için geçerli olmayan kendi sınırları vardır.

Hız sınırına takıldığında API, hem üst bilgilerle hem de JSON gövdesiyle 429 döndürür:

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

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

Özel Uç Noktalar (Sınırsız)#

Özel uç noktalar, dağıtımın kendi serviceUrl adresini doğrudan çağırdığında Platform API anahtarı hız sınırlarına tabi değildir (örneğin, https://predict-abc123.run.app/predict). Bu durumda aktarım hızı, dağıtılan hizmetin yapılandırmasına bağlıdır.

Yanıt Biçimi#

Başarılı Yanıtlar#

Yanıtlar, kaynağa özgü alanlara sahip JSON nesneleridir. Genel bir kapsayıcı yoktur: listeleme uç noktaları, sayımlarla birlikte adlandırılmış bir koleksiyon döndürür; değişiklik işlemleri ise değiştirilen kimlikleri döndürür.

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

Veri içeren yanıtlar ayrıca region (us, eu veya ap) alanını, yani ilgili çalışma alanının depolama bölgesini içerir.

Hata Yanıtları#

Her hata yanıtı, error mesajına sahip bir JSON nesnesidir:

{
    "error": "Dataset not found"
}

Sayfalandırma#

Sayfalandırma stili koleksiyona bağlıdır:

Veri Kümeleri API'si#

YOLO modellerini eğitmek için etiketlenmiş görüntü veri kümeleri oluştur, görüntüle ve yönet. Veri kümeleri belgelerine bak.

Veri Kümelerini Listele#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

Sahibinin herkese açık veri kümelerini ve anahtarın bu çalışma alanını görüntüleyebildiği durumlarda özel veri kümelerini döndürür.

Sorgu Parametreleri:

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

Yanıt:

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

Veri Kümesini Al#

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

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

Tam veri kümesi nesnesini dataset anahtarı altında döndürür; buna classNames, splits, versions, source ve kullanıcı tanımlı metadata nesnesi dahildir.

Veri Kümesi Oluştur#

POST /api/datasets

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

Gövde:

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

Yanıt, gerçekten oluşturulan dataset kısa adını (slug) döndürür; bu nedenle, requireExactSlug ayarlamadıysan yükleme yapmadan önce kısa adı oku.

Yanıt (201):

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

Veri Kümesini Güncelle#

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

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

Gövde (kısmi güncelleme):

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

Kabul edilen alanlar: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter ve starred. Özel meta verilerini temizlemek için boş bir metadata nesnesi ({}) gönder. Meta veri anahtarları 128 karakterle, serileştirilmiş nesne ise 500.000 karakterle sınırlıdır.

Yanıt:

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

Yeniden adlandırma URL adını değiştirir; bu nedenle sonraki isteklerde döndürülen dataset değerini kullan.

Veri Kümesini Silme#

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

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

Veri kümesini çöp kutusuna taşır; veri kümesi burada 30 gün boyunca kurtarılabilir.

Veri Kümesini Klonlama#

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

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

Erişilebilir bir veri kümesini, görüntüleri ve etiketleriyle birlikte kişisel çalışma alanına veya ekip çalışma alanına kopyalar.

İsteğe bağlı gövde (tüm alanlar isteğe bağlıdır):

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

Yanıt (201): id, owner, dataset, name, imageCount, classCount ve region. Bağlı bir depolama kaynağı tarafından desteklenen veri kümeleri, dosyaları kopyalanmadığı için 409 döndürür.

Veri Kümesi Dışa Aktarmasını İndir#

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

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

İmzalı bir NDJSON indirme URL'si döndürür. Veri kümesinin mevcut durumunu dışa aktarmak için v değerini belirtme; oluşturulmasından bu yana hiçbir şey değişmediyse önbelleğe alınan dışa aktarmayı yeniden kullanır.

Sorgu Parametreleri:

Yanıt:

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

Belirli bir sürüm istendiğinde cached yerine downloadUrl ve version döndürülür.

Veri Kümesi Sürümü Oluştur#

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

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

Veri kümesinin değiştirilemez, numaralandırılmış bir anlık görüntüsünü oluşturur ve NDJSON dışa aktarmasını depolar. Düzenleyici erişimi gerektirir.

Gövde (isteğe bağlı):

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

Yanıt:

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

Veri kümesi önceki sürümden bu yana değişmediyse reused, true olur ve bunun yerine ilgili anlık görüntü döndürülür.

Sürüm Açıklamasını Güncelle#

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

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

Gövde:

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

Yanıt: {"ok": true}

Veri Kümesi Sürümünü Geri Yükle#

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

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

Görüntü baytlarını kopyalamadan, kaydedilmiş bir sürümden görüntüleri, açıklamaları ve sınıfları yeniden oluşturur.

Gövde:

{
    "version": 2
}

Yanıt: {"version": 2, "imageCount": 1000}

Veri Kümesi İstatistiklerini Al#

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

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

Sınıf başına açıklama sayılarını, görüntü ve açıklama histogramlarını ve ısı haritalarını döndürür. Büyük veri kümelerinde örnekleme yapılır; bu durumda sampleSize, katkıda bulunan görüntü sayısını bildirir.

Yanıt (kısaltılmış):

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

Sınıfları Yönet#

Sınıfları birleştir (açıklamaları hedef sınıfa yeniden ata, ardından kaynak sınıfları kaldır):

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

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

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

Sınıfları sil (açıklamaları silinir ve kalan sınıf kimlikleri aşağı doğru kaydırılır):

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

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

{
    "classIds": [2, 4]
}

Her iki işlem de success, güncellenen classNames ve classColors değerlerini ve nelerin değiştiğine ilişkin bir özeti (mergedClassIds ve targetClassId veya deletedClassIds ve deletedAnnotations) döndürür.

Bölümleri Yeniden Dağıt#

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

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

Görüntüleri bölümler arasında rastgele yeniden atar. Üç yüzdenin toplamı 100 olmalıdır.

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

Yanıt: success, elde edilen splits sayıları ve modified (taşınan görüntü sayısı).

Veri Kümesi Gömme Vektörleri#

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

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

GET, analiz özetini (analyzedAt, embeddingsCount, latestImageAt, activeJob) döndürür. POST, bir gömme vektörü analizini kuyruğa alır ve jobId içeren 202 değerini döndürür. DELETE, etkin işi iptal eder ve iptal edilen iş kimliğini veya null değerini döndürür.

Görüntü Kümeleme#

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

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

Tamamlanmış bir analizden UMAP 2B yerleşimini döndürür; offset ve limit ile sayfalandırılır (varsayılan ve maksimum 50.000). Her girişte id, umapX, umapY, split, classIds, width, height, bytes, labelCount ve missing bulunur.

Bir Veri Kümesi Üzerinde Eğitilen Modelleri Listele#

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

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

Yanıt:

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

Veri Kümesi Görüntülerini Listele#

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

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

Sorgu Parametreleri:

Yanıt:

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

Seçili Görüntüleri Al#

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

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

Sağlanan en fazla 1.000 görüntü kimliği için aynı görüntü şeklini döndürür ve listeleme işlemiyle aynı filtre ve URL sorgu parametrelerini kabul eder.

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

Veri Kümesi Verilerini Al#

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

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

Tamamlanmış bir yüklemeyi, uzak bir arşivi veya bağlı bir depolama kaynağını mevcut bir veri kümesine işler. Tam olarak bir kaynak belirt:

Yükleme oturumları, POST /api/upload/signed-url öğesine geçirilen assetId ile bir veri kümesine bağlanır ve alım işlemi farklı bir veri kümesine ait olan oturumu reddeder.

Gövde (yüklenen arşiv):

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

Gövde (uzak arşiv veya NDJSON):

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

Gövde (daha sonraki alım işleminde etiketleri içe aktarma):

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

Gövde (görüntü başına meta veri ekleme):

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

Meta veri anahtarları, klasörler dahil olmak üzere arşiv içindeki normalleştirilmiş yolla eşleşmelidir. NDJSON içe aktarımlarında her kayıt, eşleşen bir imageMetadata girdisine göre öncelikli olan kendi metadata nesnesini taşıyabilir. Arşiv yolları 1.024 karakterle, üst düzey meta veri anahtarları 128 karakterle ve her meta veri nesnesi ile imageMetadata haritasının tamamı serileştirilmiş 500.000 karakterle sınırlıdır.

Yanıt (201):

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

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/ingest"]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

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

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

Görüntüler API'si#

24 karakterlik görüntü kimlikleriyle veri kümesi görüntülerini incele, açıkla, taşı ve sil. Açıklama belgelerine bak.

Görüntüyü Al#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

metadata (özel, kullanıcı tanımlı), properties (dosya adı, karma, boyutlar, bölüm, sayımlar, zaman damgaları), labels ve veri kümesinin classNames öğesini döndürür.

Görüntüyü Güncelle#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

Ya açıklamaların ya da özel meta verilerin yerine geçer; iki şekli birden değil, bunlardan yalnızca birini gönder.

Gövde (açıklamalar):

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

Gövde (meta veriler):

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

Görüntüyü Sil#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

Bir görüntüyü ve açıklamalarını kalıcı olarak siler.

Görüntüyü Otomatik Açıkla#

POST /api/images/{imageId}/predict

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

Görüntü üzerinde YOLO çıkarımı çalıştırır ve tahmin edilen açıklamaları döndürür. Bunları kaydetmez; sonuçlardan memnun kaldığında PATCH /api/images/{imageId} ile sonuçları geri yaz.

Yanıt: success, predictions (açıklama nesneleri), modelUsed ve inferenceTime. Sınıfları veri kümesiyle eşleşmeyen bir model 422 döndürür.

Bir Veri Kümesini Otomatik Etiketle#

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

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

Bir veri kümesi sürümünü kaydeder, ardından veri kümesinin etiketlenmemiş görüntülerini model ile etiketleyen bir çalıştırmayı kuyruğa alır ve 202 döndürür. Gövde, tek görüntü uç noktasıyla aynı modelId, confidence ve iou alanlarını alır; ayrıca halihazırda etiketi olan görüntüleri de etiketlemek için includeAnnotated (varsayılan false) ve her model sınıfı için veri kümesi sınıfı indeksini veren isteğe bağlı bir classMapping dizisi veya bunu atlamak için null alır. Mevcut etiketler asla değiştirilmez ve çalıştırma, gerçekten işlediği görüntüler üzerinden ücretlendirilir. 402, bakiyenin tahmini tutarı karşılayamadığı anlamına gelir; 409, veri kümesinin hazır olmadığını, etiketlenecek başka görüntüsü kalmadığını veya devam eden bir çalıştırması olduğunu gösterir; 422 ise veri kümesinde hiç sınıf olmadığını belirtir: bu uç noktayı çağırmadan önce bunları sınıflar uç noktası ile oluştur; uygulamanın Sınıfları Eşle adımı bir çalıştırma başlatmadan önce bunu yapar.

Aynı yoldaki (client.datasets.batch(owner, dataset)) GET, devam eden çalıştırmayı ve ilerleme durumunu ya da kapatılana kadar son biten çalıştırmayı döndürür; DELETE (client.datasets.delete_batch(owner, dataset)) ise devam eden bir çalıştırmayı iptal eder veya faturalandırmayı sonuçlandırıp biten özeti kapatır.

Görüntüleri Toplu Taşı#

PATCH /api/images/bulk

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

En fazla 1.000 görüntüyü bir veri kümesinden farklı bir bölüme taşır.

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

Dosya adı veya içerik çakışmaları, conflictPolicy için skip, keep_both veya replace seçeneklerinden oluşan tüm paket için geçerli bir seçim yapana kadar 409 döndürür. Yanıt modifiedCount, skippedCount ve targetSplit öğelerini bildirir.

Görüntüleri Toplu Sil#

DELETE /api/images/bulk

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

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

Tek bir veri kümesinden en fazla 1.000 görüntüyü siler ve deletedCount ile deletedImageIds öğelerini döndürür.

İmzalı Görüntü URL'lerini Al#

POST /api/images/urls

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

Tek bir veri kümesindeki en fazla 100 görüntü kimliği için geçici imzalı URL'ler döndürür.

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

Yanıt: Her ikisi de görüntü kimliğiyle anahtarlanmış urls ve thumbnails.

Projeler API'si#

Modellerini projeler halinde düzenle. Her model bir projeye aittir. Projeler belgelerine bak.

Projeleri Listele#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

Sorgu Parametreleri:

Projeyi Al#

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

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

project nesnesini, model başına özetlerden oluşan models dizisini (durum, metrikler, epoch'lar, ağırlıklar, eğitim bağımsız değişkenleri) ve isOwner öğesini döndürür.

Proje Oluştur#

POST /api/projects

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

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

Yanıt (201): id, owner, project, region.

Projeyi Güncelle#

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

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

Kabul edilen alanlar: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences ve starred.

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

Temizlemek için boş bir metadata nesnesi ({}) gönder. Proje meta verileri, veri kümesi meta verileriyle aynı 128 karakterlik anahtar ve 500.000 karakterlik serileştirilmiş nesne sınırlarını kullanır.

Projeyi Sil#

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

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

Projeyi ve modellerini çöp kutusuna taşır ve cascadedModels öğesini döndürür.

Projeyi Klonlama#

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

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

Erişilebilir bir projeyi ve tamamlanmış modellerini klonlar. İsteğe bağlı gövde project, name, description, visibility, license ve hedef owner öğesini kabul eder.

Modeller API'si#

Eğitilmiş YOLO modellerini yönet: metrikleri görüntüle, ağırlıkları indir, çıkarım çalıştır ve eğitimi izle. Modeller belgelerine bak.

Bir Projedeki Modelleri Listele#

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

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

Sorgu Parametreleri:

Modeli Al#

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

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

Sorgu Parametreleri:

Varsayılan yanıt, model nesnesini (durum, görev, metrikler, trainArgs, trainResults, classNames, computeCost, metadata ve daha fazlası) ve ayrıca isOwner öğesini içerir.

Model Oluştur#

POST /api/models

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

Ağırlık ekleyebileceğin veya eğitebileceğin eğitilmemiş bir model kaydı oluşturur.

Yanıt (201): id, owner, project, model, region.

Modeli Güncelle#

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

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

Kabul edilen alanlar şunları içerir: name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError ve starred. projectId değerini tek başına iletmek, modeli aynı sahibin başka bir projesine taşır; yanıt, hedef konumda modelin slug değerini, orada bu kısa ad halihazırda alınmışsa renamed: true değerini ve model hala eğitilirken 409 değerini döndürür.

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

Özel metadata, trainArgs, environment ve trainResults gibi eğitime ait alanlardan ayrıdır ve veri kümesi meta verileriyle aynı boyut sınırlarını kullanır.

Modeli Sil#

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

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

Modeli 30 gün boyunca çöp kutusuna taşır.

Model Dosyalarını İndir#

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

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

Modelin ağırlıkları için kısa süreli imzalı URL'ler döndürür.

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

Modeli Klonla#

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

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

Erişilebilir bir modeli mevcut bir projeye kopyalar.

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

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

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

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

Herkese açık modeller kimlik doğrulama olmadan tahmin için kullanılabilir. Özel ve paylaşılan modeller, üst projeye erişimi olan bir API anahtarı gerektirir.

Çok Parçalı Form:

file veya source sağlayın. Derinlik modelleri, derinlik haritasının PNG nicelemesini seçmek için bits (8, 12 veya 16) değerlerini de kabul eder. Hizmetin giriş sınırlarını aşan istekler 413 döndürür.

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

Yanıt:

images içindeki her girişte shape, speed, results ve yoğun tahmin görevleri için semantic_mask veya depth PNG yükü bulunur (pixel × max / divisor derinlik değerleri, varsayılan 8 bitlik harita için 255 ve bits 12 veya 16 olduğunda 65535 böleni kullanır). metadata nesnesi görüntü sayısını, işlev sürelerini, görevi ve hizmet sürümlerini bildirir. Dahili model yolları hiçbir zaman döndürülmez.

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

Eğitim İlerlemesini Kontrol Et#

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

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

Durum, epoch ilerlemesi, zamanlama, işlem ayrıntıları, eğitim bağımsız değişkenleri, epoch metrikleri ve güvenli hata ayrıntılarını içeren job değerini veya model hiç eğitilmemişse null değerini döndürür. Genel projelerdeki modeller kimlik doğrulama olmadan okunabilir.

Eğitimi İptal Et#

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

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

Çalışan işlem örneğini sonlandırır ve işi iptal edildi olarak işaretler. Eğitim artık etkin olmadığında 409 döndürür.

Eğitim API'si#

YOLO eğitimini bulut GPU'larında başlatın ve ilerlemeyi gerçek zamanlı olarak izleyin. Bkz. Bulut Eğitimi belgeleri.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

GPU Kullanılabilirliğini Al#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

GPU kimliğine göre anahtarlanmış güncel stok durumunu döndürür. Genel ve kimlik doğrulaması gerektirmez; yönetilen eğitim kapasitesini de dahil etmek için managed=true gönderin; bunun için API anahtarı gerekir.

Eğitimi Başlat#

POST /api/training/start

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

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

Yanıt:

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

Kredi bakiyeniz çok düşük olduğunda eğitim 402, istenen GPU için kapasite bulunmadığında ise 503 döndürür.

Dışa Aktarma API'si#

Modelleri uç dağıtım için ONNX, TensorRT, CoreML ve LiteRT gibi optimize edilmiş biçimlere dönüştürün. Bkz. Dağıtım belgeleri.

Dışa Aktarmaları Listele#

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

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

Sorgu Parametreleri:

Dışa Aktarma Oluştur#

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

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

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

Yanıt (201): id, format, status (queued veya running), gpuType, region. Halihazırda devam eden eşdeğer bir dışa aktarma 409 döndürür.

Desteklenen Biçimler:

Aşağıdaki ortak dışa aktarma tablosundaki format bağımsız değişkenini kullanın. PyTorch kaynak biçimidir ve API dışa aktarma için hedef değildir.

nms=None, harici NMS için varsayılan olarak ham çıktıları kullanır. Mevcut bir NMS'siz başlığı seçmek için nms=False değerini ayarla; desteklenmeyen formatlar yerel çıktı yollarına geri döner. Yukarıdaki nms girdileri, NMS'yi nms=True ile gömebilen formatları tanımlar.

Dışa Aktarma Durumunu Al#

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

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

status, format, args, gpuType, zaman damgaları ve tamamlandığında size, downloadUrl ve downloadFilename içeren bir file nesnesiyle birlikte export nesnesini döndürür.

Dışa Aktarmayı İptal Et veya Sil#

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

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

Etkin bir dışa aktarmayı iptal eder veya tamamlanmış bir dışa aktarmayı ve dosyasını siler. Yanıt, hangisinin gerçekleştiğini bildirir:

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

Dağıtımlar API'si#

Modelleri sağlık kontrolleri ve izleme özelliklerine sahip özel çıkarım uç noktalarına dağıtın. Bkz. Uç noktalar belgeleri.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action start| C
    C -->|delete| E[Deleted]:::error
    D -->|delete| E
    C -->|predict| F[Inference Results]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

Dağıtımları Listele#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Sorgu Parametreleri:

Anonim çağıranlar bir genel modele göre filtreleme yapmalıdır; çalışma alanının tamamını listelemek için kimlik doğrulaması gerekir.

Dağıtım Oluştur#

POST /api/deployments/{owner}

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

Gövde:

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

Yanıt (201): id, deployment, status (creating), message ve region.

Dağıtımı Al#

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

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

status, statusMessage, region, serviceUrl ve resources içeren deployment nesnesini döndürür.

Dağıtımı Başlat, Durdur veya Değiştir#

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

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

Tek bir action alanı işlemi seçer:

{ "action": "start" }

Değiştirme işlemi, dağıtım kimliğini, bölgeyi ve uç nokta URL'sini koruyarak yeni bir revizyonu kullanıma sunar; kullanıma sunma başarısız olursa mevcut revizyon çalışmaya devam eder. Değiştirilecek model, anahtarının erişebildiği ağırlıklara sahip tamamlanmış bir model olmalıdır. Tamamlanan işlemler status ready veya stopped içeren 200 değerini; kullanıma sunma işlemi devam edenler ise deploying veya stopping içeren 202 değerini döndürür.

Dağıtımı Sil#

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

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

Çıkarım uç noktasını kalıcı olarak kaldırır.

Sağlık Kontrolü#

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

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

Uç noktaya ping gönderir ve onu ısıtır; healthy, latencyMs ve üst akıştaki status kodunu döndürür.

Dağıtımda Çıkarım Çalıştır#

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

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

Bir görüntüyü veya videoyu özel uç nokta üzerinden yönlendirir. İstek ve yanıt sözleşmeleri model çıkarımı ile aynıdır.

Çok Parçalı Form:

Metrikleri Al#

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

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

Sorgu Parametreleri:

Tam yanıt, summary (istek toplamları, hata oranı, ortalama ve p50/p95/p99 gecikme) ile timeSeries (istekler, hatalar, gecikme, CPU, bellek, örnek sayısı) içerir. Sparkline yanıtı requests24h, totalRequests, errorRate ve avgLatencyMs değerlerini döndürür.

Günlükleri Al#

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

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

Sorgu Parametreleri:

Çöp Kutusu API'si#

Yumuşak silinen projeleri, veri kümelerini ve modelleri görüntüleyin, geri yükleyin ve kalıcı olarak silin. Öğeler 30 gün sonra otomatik olarak temizlenir. Bkz. Çöp Kutusu belgeleri.

Çöp Kutusunu Listeleme#

GET /api/trash

Python SDK: client.lifecycle.trash()

Sorgu Parametreleri:

Yanıt, items (her biri daysRemaining içerir), total, page, limit, totalPages ve türe göre toplamları içeren bir summary içerir.

Öğeyi Geri Yükleme#

POST /api/trash

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

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

Bir projenin geri yüklenmesi, onunla birlikte çöp kutusuna taşınan modelleri de geri yükler ve bu modeller restoredModels olarak bildirilir.

Kalıcı Olarak Sil#

DELETE /api/trash

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

Bir öğeyi silin:

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

Veya tüm çöp kutusunu boşaltın:

{
    "all": true
}

Yanıt, deletedCount ile birlikte ilgili olduğunda cascadedModels ve survivingDeployments değerlerini bildirir.

Yükleme API'si#

İmzalı URL'ler kullanarak dosyaları doğrudan bulut depolamaya yükleyin. Model yüklemesinin tamamlanması ağırlıklarını ilişkilendirir; veri kümesi arşivi yüklemesinin tamamlanması oturumu kaydeder ve bu oturumu daha sonra veri kümesi alımı işlemine iletirsiniz. Bkz. Veri belgeleri.

İmzalı Yükleme URL'sini Al#

POST /api/upload/signed-url

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

Gövde:

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

Yanıt:

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

Beyan ettiğin aynı Content-Type değerini ve headers içinde döndürülen her üst bilgiyi (header) kullanarak, dosyayı uploadUrl adresine bir PUT isteğiyle yükle. Veri kümesi yükleme URL'leri 12 saat boyunca geçerlidir ve yalnızca oluşturma amaçlıdır: aynı URL'ye yapılan ikinci bir PUT isteği 412 döndürür ve döndürülen üst bilgiler olmadan yapılan bir PUT isteği 400 döndürür.

Yüklemeyi Tamamla#

POST /api/upload/complete

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

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

Yanıt: success ve size ile contentType içeren bir file nesnesi. Modeller için bu işlem ağırlıkları ilişkilendirir; veri kümesi arşivleri için işlemeyi başlatmak üzere sonraki adımda ingest çağrısını yapın.

md5 sağlandığında, saklanan nesneye göre kontrol edilir. Uyuşmazlık 400 döndürür; henüz tamamlanmamış bir oturumda ayrıca yüklenen dosyayı siler ve oturumu tamamlanmamış olarak bırakır; bu nedenle yeni bir imzalı URL iste ve tekrar yükle. Tamamlanmış bir veri kümesi oturumu, arşivi mevcut olduğu sürece tekrar tamamlanabilir, ancak farklı özet değerlerine (digest) sahip çakışan tamamlama denemeleri 409 döndürür; model oturumları tamamlandığında kaldırılır. checksum, model dosyası meta verisi olarak saklanır ve doğrulanmaz.

Depolama Entegrasyonları API'si#

Salt okunur Google Cloud Storage, Amazon S3 veya Azure Blob Storage hesaplarını bağlayın ve bunlara veri kümesi kaynakları olarak göz atın. Bkz. Entegrasyonlar belgeleri.

Entegrasyonları Listele#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Her biri id, provider, credentialIdentity, targets ve createdAt içeren integrations döndürür. Kimlik bilgileri asla döndürülmez.

Konumları Keşfet#

POST /api/integrations/buckets/discover

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

Sağlanan kimlik bilgileriyle okunabilen paketleri veya kapsayıcıları kaydetmeden listeler.

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

Yanıt: {"targets": ["my-bucket", "another-bucket"]}

Depolamaya Bağlan#

POST /api/integrations/buckets

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

Keşiftekiyle aynı kimlik bilgisi biçimlerine ek olarak, 1-50 paket veya kapsayıcı adı içeren zorunlu bir targets dizisi kullanılır. Kaydedilen entegrasyonla birlikte 201 döndürülür. Geçici S3 kimlik bilgileri (ASIA erişim anahtarları) reddedilir.

Nesnelere Göz At#

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

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

Sorgu Parametreleri:

entries döndürür (her kind, folder veya file değeridir) ve sonraki sayfa için isteğe bağlı bir cursor döndürür.

Depolama Bağlantısını Kes#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Sağlayıcı verilerini silmeden kaydedilmiş kimlik bilgilerini kaldırır. Bağlı veri kümeleri görünür kalır, ancak aynı depolama hesabı yeniden bağlanana kadar dosyaları erişilemez durumda kalır. Çalışma alanı yöneticisi erişimi gerekir.

Veri Kümesi İçe Aktarma API'si#

Veri kümelerini üçüncü taraf hizmetlerden içe aktar. Roboflow entegrasyonuna bak.

Roboflow İçe Aktarmasını Önizle#

POST /api/integrations/roboflow/preview

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

Bir Roboflow API anahtarını içe aktarma planına çözümler: çalışma alanı ayrıntıları, içe aktarılacak newDatasets, atlanan, desteklenmeyen ve çözümlenemeyen projelerin sayıları, bytesTotal ve storage için kalan kapasiten. Roboflow API anahtarı gövdeden okunur ve kalıcı olarak saklanmaz.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Roboflow'dan İçe Aktar#

POST /api/integrations/roboflow/import

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

Önizlemede döndürülen öğeleri kullanarak en fazla 500 seçili Roboflow proje sürümü için alım işleri kuyruğa ekler.

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

Yanıt (201): imported, failed ve skipped dizileri. İçe aktarma işlemleri depolama kapasitesi gerektirir ve her veri kümesi planının içe aktarma başına boyut sınırına sığmalıdır.

Hesap API'si#

Platform hesabını, anahtarlarını, depolama alanını ve herkese açık profillerini incele. Ayarlar belgelerine bak.

Hesap Özeti#

GET /api/account/summary

Python SDK: client.account.summary()

Anahtarı oluşturan çalışma alanının planını, kredi bakiyesini ve kaynak sayılarını döndürür.

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

API Anahtarlarını Listele#

GET /api/api-keys

Python SDK: client.account.api_keys()

Anahtarın çalışma alanı için keyId, name, keyPrefix ve createdAt içeren keys döndürür. API anahtarıyla kimlik doğrulanan istekler yalnızca meta verileri alır; tam anahtar değerleri, Platform kullanıcı arayüzündeki Ayarlar > API Anahtarları bölümünde çalışma alanı sahibine gösterilir; anahtarlar burada oluşturulur ve iptal edilir.

Depolama Kullanımını Kontrol Et#

GET /api/storage

Python SDK: client.account.storage()

Sorgu Parametreleri:

Yanıt:

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

Herkese Açık Kullanıcı Profilini Al#

GET /api/users

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

Sorgu Parametreleri:

Herkese açık user profilini, followerCount ile birlikte ve kimliği doğrulanmış çağrılar için isFollowed ile döndürür.

Bir Kullanıcıyı Takip Et veya Takibi Bırak#

PATCH /api/users

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

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

Yanıt: followed ve güncellenmiş followerCount.

Faturalandırma API'si#

Plan kullanımını ve kredi defterini kontrol et. Faturalandırma belgelerine bak.

Planı ve Kullanımı Görüntüle#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

plan (kimlik, durum, faturalandırma döngüsü, dönem sonu), metrics (depolama sınırı ve kullanım), trainingCredit, features, creditsCents ve koltuk sayılarını döndürür.

İşlemleri Görüntüle#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Sorgu Parametreleri:

Her işlem id, type (örneğin purchase, training, monthly_grant veya refund), amountCents, balanceAfter, createdAt, isteğe bağlı bir receiptUrl ve eğitim ücretleri için model bağlamı içerir. Dahili faturalandırma ayrıntıları asla döndürülmez.

API'yi Keşfet#

Topluluk tarafından paylaşılan herkese açık projeleri ve veri kümelerini ara. Keşfet belgelerine bak.

Herkese Açık İçerikte Ara#

GET /api/explore/search

Python SDK: client.explore.search()

Sorgu Parametreleri:

Yanıt: projects, datasets ve hasMore.

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

Python SDK#

ultralytics-platform, OpenAPI sözleşmesinden oluşturulmuş, her uç nokta için bir yönteme (client.datasets.list, client.models.predict, client.exports.create, ...) sahip, tür bilgili bir Python istemcisidir. Her yöntem yol parametrelerini konumsal olarak, diğer girdileri anahtar sözcük bağımsız değişkenleri olarak ve istek başına isteğe bağlı timeout ile extra_headers değerlerini kabul eder.

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

from ultralytics_platform import Platform

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

AsyncPlatform, async/await kodu için aynı kaynak ağacını sunar; başarısız yanıtlar status_code, body ve ayrıştırılmış json ile birlikte APIError hatasını yükseltir ve bağlantı hataları APIConnectionError hatasını yükseltir. Tam README için SDK deposuna bak.

Python Entegrasyonu#

Eğitim ve çıkarım iş akışları için, kimlik doğrulama, yüklemeler ve gerçek zamanlı metrik akışını otomatik olarak yöneten Ultralytics Python paketini kullan. Python 3.11+ üzerinde pip install ultralytics, ultralytics-platform SDK'sını da kurar. model.train(project=...), Platform'u hedeflediğinde, eğitim geri çağrıları (callbacks) olayları SDK'nın client.training.metrics() üzerinden aktırır ve OpenAPI belgesindeki POST /api/webhooks/training/metrics ve POST /api/webhooks/models/upload işlemleri olan client.models.upload_checkpoint() aracılığıyla kontrol noktası yükleme URL'leri ister, dolayısıyla senin kendin çağırman gereken hiçbir şey yoktur.

Kurulum ve Ayarlar#

Platform entegrasyonu Python>=3.11 ve ultralytics>=8.4.120 gerektirir:

pip install "ultralytics>=8.4.120"

Kurulumu doğrula:

yolo check

Kimlik Doğrulama#

yolo login YOUR_API_KEY

Platform Veri Kümelerini Kullanma#

Veri kümelerine ul:// URI'leriyle başvur:

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 Biçimi:

Platforma Gönderme#

Sonuçları bir Platform projesine gönder:

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

Senkronize edilenler:

• Eğitim metrikleri (gerçek zamanlı)
• Son model ağırlıkları
• Doğrulama grafikleri
• Konsol çıktısı
• Sistem metrikleri
• Eğitim argümanları ve ana bilgisayar ortamı (anahat adı, işletim sistemi, Python, donanım, git işleme, komut satırı)

API Örnekleri#

Platformdan model yükleme:

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

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

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

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

Modeli dışa aktarma:

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

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

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

Doğrulama:

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

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

SSS#