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 sunar.

# 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, Platform'un temel kaynakları etrafında düzenlenmiştir:

Kimlik Doğrulama#

Çoğu uç nokta bir API anahtarı gerektirir. Herkese açık içerik sunan uç noktalar — herkese açık bir veri kümesini, projeyi veya modeli okuma, herkese açık veri kümesi görüntülerini listeleme, herkese açık bir modelde çıkarım yapma veya Keşfet'te arama — anonim istekleri de kabul eder ve anahtar sağlandığında daha fazla bilgi döndürür.

API Anahtarı Edin#

1. Settings > API Keys bölümüne git
2. Add Key seçeneğine tıkla, sağlayıcı olarak Ultralytics seçeneğini bırak, bir ad gir ve Create Key seçeneğine tıkla
3. Oluşturulan anahtarı kopyala

Ayrıntılı yönergeler için API Anahtarları sayfasına bak.

Yetkilendirme Üstbilgisi#

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

Çoğu kaynağa, veritabanı kimlikleriyle değil, Platform URL'lerinde görünen aynı okunabilir adlarla erişilir:

• {owner}, kişisel bir kullanıcı adı veya ekip çalışma alanı tanıtıcısıdır: 4-32 karakter uzunluğunda, küçük harfli alfasayısal karakterlerden ve bölümler arasında tek tirelerden oluşur.
• {dataset}, {project}, {model} ve {deployment} aynı küçük harf ve tire düzenini izler ve en fazla 128 karakter uzunluğundadır.
• {imageId}, {exportId} ve {agentId}, API tarafından döndürülen 24 karakterlik onaltılık kimliklerdir.
• Bir kaynağın adını PATCH üzerinden değiştirmek, görünen name adını ve URL adını birlikte değiştirir; yanıt, kaynağı izlemeye devam edebilmen için geçerli URL adını döndürür.

Hız Sınırları#

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

Faturalandırma ödeme adımları ve ekip yönetimi gibi yalnızca tarayıcıda kullanılan Platform rotalarının, API anahtarı trafiği için geçerli olmayan kendi limitleri vardır.

Hız sınırına takıldığında API, hem başlıklarda hem de JSON gövdesinde 429 döndürür:

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

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

Özel uç noktalar, dağıtımın kendi serviceUrl uç noktasını doğrudan çağırdığında (örneğin https://predict-abc123.run.app/predict) Platform API anahtarı hız sınırlarına tabi değildir. 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ü alanları içeren JSON nesneleridir. Genel bir kapsayıcı yoktur: liste uç noktaları, çoğunlukla sayımlarla birlikte, adlandırılmış bir koleksiyon döndürür; değişiklik yapan işlemler ise değiştirilen tanımlayıcıları döndürür.

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

Kaynak listeleri, oluşturma ve klonlama yanıtları ve dağıtımlar, depolama ve çöp kutusu gibi bazı okuma işlemleri region (us, eu veya ap) bilgisini de içerir; bu, söz konusu çalışma alanının depolama bölgesidir.

Hata Yanıtları#

Her hata yanıtı, error mesajını içeren bir JSON nesnesidir:

{
    "error": "Dataset not found"
}

Sayfalandırma#

Sayfalandırma yöntemi koleksiyona bağlıdır:

Veri Kümeleri API'si#

YOLO modellerini eğitmek için etiketli görüntü veri kümeleri oluştur, göz at 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üleyebiliyorsa ö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 Getir#

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

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

dataset anahtarı altında classNames, splits, versions, source ve kullanıcı tanımlı metadata nesnesi dahil olmak üzere veri kümesinin tüm nesnesini döndürür. 10.000 veya daha fazla görüntünün içe aktarımı sürerken düzenleyiciler, stage, percent ve biliniyorsa processed, total ile objects (taranan bulut nesneleri) bilgilerini içeren processingProgress değerini de alır.

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

Çalışma alanında, Çöp Kutusu'ndakiler dahil, zaten bulunan bir dataset kısa adı 409 döndürür.

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, starred, blurFaces, kptSkeletonId (bir poz veri kümesine poz iskeleti şablonu atar) ve initializeClassNames (veri kümesinde henüz sınıf veya açıklama yoksa güncelleme 409 değerini döndürür). Özel meta verileri temizlemek için boş bir metadata nesnesi ({}) gönder. Meta veri anahtarları en fazla 128 karakter, serileştirilmiş nesne ise en fazla 500.000 karakter olabilir.

Yanıt:

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

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

Veri Kümesini Sil#

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

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

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

Veri Kümesini Klonla#

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ğına dayalı veri kümeleri, dosyaları kopyalanmadığından 409 döndürür.

Veri Kümesi Dışa Aktarımı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 parametresini belirtme; oluşturulduğundan beri hiçbir şey değişmediyse önbelleğe alınan dışa aktarım yeniden kullanılı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 sürümünü oluşturur. Düzenleyici erişimi gerekir. NDJSON indirmesi hazırlamadan sürümü kaydetmek için download değerini false olarak ayarla; bu durumda downloadUrl atlanır. SDK, ultralytics-platform>=0.1.73 içinden download değerini kabul eder.

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

{
    "description": "Added 500 training images",
    "download": true
}

Yanıt:

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

Veri kümesi mevcut bir sürümle eşleşiyorsa, örneğin geri yüklemenin hemen ardından, reused değeri true olur ve bunun yerine o sürüm döndürülür; bir açıklama gönderirsen açıklaması güncellenir.

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 Sürümlerini Karşılaştır#

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)

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

{
    "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 yalnızca ilk sayfada yer alır ve kesin toplamları, eklenen, kaldırılan veya yeniden adlandırılan sınıfları ve farklılık gösteren diğer veri kümesi alanlarını listeleyen bir header değerini içerir. Her öğenin change değeri added, removed, modified (değiştirilen fields ile) veya moved (bölünmüş değişiklik) olur; labelsRemoved ise kaldırılan görüntülerin etiketlerini içerir. Varsa sonraki sayfa için nextCursor değerini cursor olarak gönder. hash ile yanıt versions olur: her sürümde saklandığı hâliyle görüntü, etiketleri ve imzalı bir imageUrl ile birlikte döndürülür. Her iki sıralama da çalışır; base ile head değerlerini yer değiştirmek, kaldırılmış bir görüntüyü eklenmiş olarak bildirir. Karşılaştırmalar varsayılan hız sınırını kullanır; ayrıca hash içermeyen istekler, hangi API anahtarını kullandıklarına bakılmaksızın kullanıcı ve veri kümesi başına dakikada 10 istekle sınırlıdır.

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, kaç görüntünün kullanıldığı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ı sil):

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 (bu sınıfların açıklamaları silinir ve kalan sınıf kimlikleri aşağı kayar):

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üncellenmiş classNames ve classColors ile nelerin değiştiğine dair bir özet döndürür (mergedClassIds ve targetClassId ya da deletedClassIds ve deletedAnnotations).

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 dağıtır. Üç yüzdenin toplamı 100 olmalıdır.

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

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

Veri Kümesi Gömüleri#

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 analizini sıraya 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; sayfalama için offset ve limit kullanılır (varsayılan ve en fazla 50.000). Her girdi id, umapX, umapY, cluster, split, classIds, width, height, bytes, labelCount, labeled ve missing içerir. cluster, noktanın boyuta göre sıralanmış görsel adacığıdır (0 = en büyük, -1 = dağınık) veya kümeleme özelliği eklenmeden önce analiz edilen yerleşimler için null değerini alır.

Bir Veri Kümesinde Eğitilmiş 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",
            "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=...)

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

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

Görüntüleri Kopyala veya Taşı#

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

Python SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)

Diğer veri kümelerinden bu veri kümesine en fazla 1.000 görüntü kopyalar; uygulamanın kopyala ve yapıştır özelliğinde olduğu gibi çalışır ve adopted sayısını döndürür.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

release veya classMapping ayarlamak, düzenleyebileceğin veri kümelerindeki etiketleri ve bölümleri korur: release: false görselleri kopyalar, release: true ise görselleri kaynak veri kümesinden taşır. Her iki alanı da belirtmezsen etiketsiz train görseller içe aktarılır; salt okunur bir kaynaktan kopyalama da aynı sonucu verir. Salt okunur bir kaynaktan taşıma işlemi 403 döndürür. Mevcut görseller atlanır; etiketler ve bölümler korunurken yinelenenler hedef bölüm içinde denetlenir. Sınıflar ada göre eşleştirilir; iki karakterden uzun adlarda büyük/küçük harf duyarlılığı yoktur. 422, unmatchedClasses içinde eşleşmeyen kaynak sınıfları döndürür; classMapping ise her sınıfı etiketlerini kaldırmak için bir sınıf diziniyle, yeni bir sınıf adıyla veya null ile eşleştirir. 409, hedefin bağlı bir veri kümesi olduğu veya kaynağın ya da hedefin meşgul olduğu anlamına gelir. Etiketler ve bölümler korunurken uyumsuz görevler, görsel kanalları, poz ayarları veya derinlik ölçekleri, etiketsiz görseller için bile 409 döndürür.

Veri Kümesi Verilerini İçeri 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 çağrısına iletilen assetId aracılığıyla bir veri kümesine bağlanır; içe alma işlemi başka bir veri kümesine ait oturumları 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 bir içe alma 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 arşiv içindeki normalleştirilmiş yolla eşleşmelidir. NDJSON içe aktarımlarında her kayıt kendi metadata nesnesini taşıyabilir; bu nesne, eşleşen imageMetadata girdisine göre önceliklidir. Arşiv yolları en fazla 1.024 karakter, en üst düzey meta veri anahtarları en fazla 128 karakter ve her meta veri nesnesi ile tüm imageMetadata haritası serileştirildiğinde en fazla 500.000 karakter olabilir.

Yanıt (201):

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

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

Görüntüler API'si#

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

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ılar, zaman damgaları), labels ve veri kümesinin classNames değerini döndürür.

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

PATCH /api/images/{imageId}

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

Açıklamaların veya özel meta verilerin yalnızca birini değiştirir; iki biçimi birden değil, bunlardan 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=...)

Modeli görüntü üzerinde çalıştırır ve tahmin edilen açıklamaları döndürür. Bunları kaydetmez; sonuçlardan memnunsan PATCH /api/images/{imageId} ile geri yaz.

Yanıt: success, predictions (açıklama nesneleri), confidences (indekslerle hizalanmış puanlar; sınıf istemli modeller için boş), modelUsed, inferenceTime; sınıf istemli modeller için partial (üretken bir modelin kesilmiş çıktısı yalnızca eksiksiz kutuları döndürdüğünde true) ve ücretli sağlayıcı modelleri için isteğe bağlı cost (sağlayıcı anahtarına yansıtılan tahmini sağlayıcı maliyeti, tahmin yoksa atlanır). Sınıfları veri kümesiyle eşleşmeyen bir YOLO modeli 422 döndürür; algılama dışı bir veri kümesinde veya 1–200 sınıf aralığının dışında kullanılan sınıf istemli model ve veri kümesi çalışma alanının Settings > API Keys bölümünde kayıtlı sağlayıcı anahtarı olmayan ücretli sağlayıcı modeli de (code: missing_provider_api_key) bu değeri döndürür. Sağlayıcı hatası, sağlayıcının iletisini içerir: sağlayıcı 400, 401, 403 veya 404 yanıtını verdiğinde 422 (reddedilen bir anahtar, model veya istek), hız sınırı için 429 ve diğer sağlayıcı hataları için 503. Derinlik veri kümeleri 400, bağlı depolamadaki veya 3'ten fazla görüntü kanalı olan veri kümeleri ise 409 döndürür.

Benzer görüntüleri bul#

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

Herkese açık veri kümelerinden ve kendi veri kümelerin ile ekip veri kümelerinden görsel olarak benzer en fazla 24 images döndürür; her biri score (0-1), imzalı bir thumbnailUrl ve kaynak dataset (owner, dataset, license) içerir. Kaynak veri kümesinde zaten bulunan görüntüler ve sorgu görüntüsünün kopyaları hariç tutulur. Görüntüyü görüntüleme erişimi olan bir API anahtarı gerekir; henüz gömme işlemi uygulanmamış bir görüntü önce gömülür. 503, hazırlığın başarısız olduğu anlamına gelir; yeniden dene.

Veri Kümesini Otomatik Açıkla#

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

Python SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)

Bir veri kümesi sürümü kaydeder, ardından veri kümesindeki etiketsiz görüntüleri modelle etiketleyen bir çalıştırmayı sıraya alır ve 202 değerini döndürür. Gövde, tek görüntü uç noktasıyla aynı modelId, confidence, iou ve classMapping alanlarını alır; ayrıca zaten etiketleri olan görüntüleri de açıklamak için includeAnnotated (varsayılan false) alanını alır. Sınıf istemli model, güven puanları olmadan veri kümesi sınıflarını algılar; ücretli sağlayıcı modeli içinse veri kümesi çalışma alanının Settings > API Keys bölümünde kayıtlı bir sağlayıcı anahtarı gerekir (422, code: çalıştırma kabul edilmeden önce missing_provider_api_key). Mevcut etiketler hiçbir zaman değiştirilmez ve çalıştırma, gerçekten işlediği görüntüler için ücretlendirilir. 402, bakiyenin tahmini karşılayamayacağı; 409, veri kümesinin hazır olmadığı, açıklanacak görüntü kalmadığı veya zaten devam eden bir çalıştırma olduğu; 422 ise veri kümesinde sınıf bulunmadığı ya da sınıf istemli modelin algılama dışı bir veri kümesi veya 1–200 sınıf aralığının dışında bir veri kümesi için kullanıldığı anlamına gelir: bu uç noktayı çağırmadan önce sınıfları sınıflar uç noktası ile oluştur; uygulamadaki Sınıfları eşle adımı da çalıştırmayı başlatmadan önce bunu yapar.

Aynı yol üzerindeki GET (client.datasets.batch(owner, dataset)), devam eden çalıştırmayı ve ilerlemesini ya da kapatılana kadar son tamamlanan çalıştırmayı döndürür; son tamamlanan çalıştırmanın results alanları, üretken bir modelin çalıştırmasında kesilmiş çıktının yalnızca eksiksiz kutuları tutulduğunda partialImages değerini içerir; DELETE (client.datasets.delete_batch(owner, dataset)) devam eden bir çalıştırmayı iptal eder ya da faturalandırmayı sonuçlandırıp tamamlanan özeti kapatır.

Aynı uç nokta "operation": "blur", confidence (varsayılan 0.25) ve boxScale (0.5–1.5, varsayılan 1) ile yüzleri bulanıklaştırır; imageId, çalıştırmayı tek bir görüntüyle sınırlar. Sürüm oluşturmaz ve etiketleri hiçbir zaman değiştirmez. En fazla altı görüntüyü değiştirmeden işlemek için "preview": true gönder, ardından uygulamak için döndürülen jobId değerini aynı ayarlarla previewJobId olarak gönder; uygulanmış bir önizleme yeniden kullanılamaz ve 409 döndürür. Bir önizleme beklemedeyken, önizlemeyi silmek için kimliğini previewJobId olarak DELETE uç noktasına ilet.

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

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ı, sepet genelinde skip, keep_both ya da replace değerlerinden bir conflictPolicy seçene kadar 409 döndürür. Yanıt modifiedCount, skippedCount ve targetSplit değerlerini 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 değerlerini 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: urls, thumbnails ve depths (eşlenmiş derinlik görüntüleri için derinlik hedefi önizlemeleri); tümü görüntü kimliğine göre anahtarlanır.

Projeler API'si#

Modellerini projeler halinde düzenle. Her model bir projeye aittir. Bkz. Projeler belgeleri.

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 (durum, ölçümler, dönemler, ağırlıklar, eğitim bağımsız değişkenleri) oluşan bir models dizisini ve isOwner değerini döndürür. models değerini model adına veya meta verilere göre filtrelemek için search (en fazla 200 karakter) ilet.

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.

Çalışma alanında, Çöp Kutusu'ndakiler dahil, zaten bulunan bir project kısa adı 409 döndürür.

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ına tabidir.

Projeyi Sil#

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

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

Projeyi ve modellerini çöp kutusuna taşır, cascadedModels değerini döndürür ve dağıtımlarını kalıcı olarak siler. Projeyi geri yüklemek dağıtımları geri yüklemez. 502, dağıtım temizliğinin tamamlanmadığı anlamına gelir; işlem başarılı olana kadar modeller Çöp Kutusu'nda kalır.

Projeyi Klonla#

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ı istek gövdesi project, name, description, visibility, license ve hedef owner değerlerini 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 göz at.

Projede 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; durum, görev, metrikler, trainArgs, trainResults, classNames, computeCost, metadata ve daha fazlasını içeren model nesnesinin yanı sıra isOwner değerini 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 arasında name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError ve starred bulunur. Tek başına projectId göndermek modeli aynı sahibin başka bir projesine taşır; yanıt, hedefteki modelin slug değerini, bu kısa ad orada zaten kullanılıyorsa renamed: true değerini ve model hâlâ eğitiliyorsa 409 değerini döndürür.

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

Özel metadata, trainArgs, environment ve trainResults gibi eğitimin yönettiği alanlardan ayrıdır ve veri kümesi meta verileriyle aynı boyut sınırlarına tabidir.

Modeli Sil#

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

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

Modeli 30 günlüğüne çöp kutusuna taşır ve bekleyen yenilemeler dahil modeli kullanan tüm dağıtımları kalıcı olarak siler. Modeli geri yüklemek dağıtımları geri yüklemez.

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üre geçerli imzalı URL'ler döndürür.

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

En Kötü Doğrulama Görüntülerine Benzer Görüntüler Bul#

GET /api/models/{owner}/{project}/{model}/similar-images

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

Bu eğitim çalıştırmasının en kötü puan verdiği doğrulama görüntülerine benzeyen ve çalıştırmanın eğitim veri kümesinde zaten bulunmayan en fazla 100 images döndürür; biçimleri Benzer Görüntüler Bul ile aynıdır. Bu en kötü görüntülerin bir alt kümesinden arama yapmak için hashes (virgülle ayrılmış, en fazla 100) gönder. Modelin çalışma alanına erişimi olan bir API anahtarı gerekir. Çalıştırma görüntü başına sonuç kaydetmediyse liste boş olur. 404, en kötü görüntülerin henüz gömülmediği anlamına da gelir: önce eğitim veri kümesinde veri kümesi gömmelerini çalıştır.

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 modellerde kimlik doğrulaması olmadan tahmin yapılabilir. Özel ve paylaşılan modeller için üst projeye erişimi olan bir API anahtarı gerekir.

Çok Parçalı Form:

file veya source değerlerinden birini gönder. Derinlik modelleri, derinlik haritasının PNG nicemlemesini seçmek için bits (8, 12 veya 16) değerini 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örevlerinde semantic_mask veya depth PNG verisi bulunur (derinlik değerleri pixel × max / divisor biçimindedir; varsayılan 8 bitlik haritada bölen 255, bits 12 veya 16 olduğunda ise 65535'tir). metadata nesnesi görüntü sayısını, model sınıf adları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,
        "classNames": ["person", "forklift"],
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Eğitim İlerlemesini Denetle#

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

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

Durumu, epoch ilerlemesini, süreyi, hesaplama ayrıntılarını, eğitim argümanlarını, epoch metriklerini ve güvenli hata ayrıntılarını içeren job değerini veya model hiç eğitilmediyse null değerini döndürür. Herkese açık projelerdeki modeller, kimlik doğrulaması olmadan okunabilir.

Eğitimi İptal Et#

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

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

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

Eğitim API'si#

YOLO eğitimini bulut GPU'larında başlat ve ilerlemeyi gerçek zamanlı izle. Bulut Eğitimi belgelerine göz at.

GPU Kullanılabilirliğini Al#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

GPU kimliğine göre mevcut stok durumunu döndürür. Herkese açık ve kimlik doğrulaması gerektirmez; yönetilen eğitim kapasitesini dahil etmek için managed=true gönder; 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 bakiyen yetersiz olduğunda eğitim 402, istenen GPU için kapasite olmadığında ise 503 döndürür.

Dışa Aktarımlar API'si#

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

Dışa Aktarımları Listele#

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

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

Sorgu Parametreleri:

Dışa Aktarım 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

Her biçim, yalnızca aşağıdaki dışa aktarım tablosunun Argümanlar sütunundaki seçenekleri dikkate alır: biçim tarafından desteklenmeyen bir seçenek için varsayılan dışı batch, dynamic, opset, simplify, workspace veya optimize değeri 400 döndürür. imx dışa aktarımları yalnızca INT8 biçimindedir ve detect, segment, classify ve pose modellerinde kullanılabilir; YOLO26 modelleri ile nano dışındaki YOLOv8 veya YOLO11 boyutları 400 döndürür.

Yanıt (201): id, format, status (queued veya running), region ve TensorRT dışa aktarımları için gpuType. Devam etmekte olan eşdeğer bir dışa aktarım varsa 409 döndürülür.

Desteklenen Biçimler:

Aşağıdaki ortak dışa aktarım tablosundaki format argümanını kullan. PyTorch kaynak biçimidir ve API dışa aktarım hedefi değildir.

nms=None, harici NMS için varsayılan olarak ham çıktılar üretir. Kullanılabilir bir NMS içermeyen başlık seçmek için nms=False değerini ayarla; desteklenmeyen biçimler yerel çıktı yoluna döner. Yukarıdaki nms girdileri, nms=True ile NMS içerebilen biçimleri tanımlar.

Dışa Aktarım Durumunu Al#

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

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

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

Dışa Aktarımı İ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 aktarımı iptal eder veya tamamlanmış olanı 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. Uç Noktalar belgelerine göz at.

Dağıtımları Listele#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Sorgu Parametreleri:

Anonim çağrılar tek bir herkese açık 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)

deployment nesnesini; status, statusMessage, region, serviceUrl, resources ve özel metadata öğeleriyle, ayrıca sahip için camera ve cameraApplying öğeleriyle birlikte döndürür.

Dağıtımı Güncelle#

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

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

Bu istek gövdelerinden birini gönder:

{ "name": "Edge 1 (primary)" }

Yeniden adlandırma, URL'deki deployment değerini yeni adın kısa biçimine ayarlar ve bunu deployment olarak döndürür; eski yol 404 döndürür, serviceUrl ise aynı kalır. Boş bir metadata nesnesi özel meta verileri temizler. Değiştirme işlemi dağıtım kimliğini, bölgeyi ve uç nokta URL'sini koruyarak yeni bir sürümü devreye alır; devreye alma başarısız olursa mevcut sürüm çalışmaya devam eder. Yeni model, anahtarının erişebildiği ağırlıklara sahip, tamamlanmış bir model olmalıdır. Kamera eylemi, özel kaynaklara sahip hazır bir uç noktanın çıkarım yaparak çalışır durumda tuttuğu bir RTSP veya RTSPS kamerayı kaydeder (Arka Plan Kamerası bölümüne bak); "url": null kamerayı kaldırır, varsayılan boyuta yeniden geçmek de aynı işlemi yapar. Varsayılan boyutlu bir uç noktaya kamera kaydetmek 403 döndürür. Kamera değişikliği uygulanırken status ready ile birlikte 202 döndürür: true, cameraApplying değerine dönüşene kadar dağıtımı yokla, ardından camera değerini denetle. Başarısız bir değişiklik önceki kamerayı korur ve statusMessage değerini ayarlar. Tamamlanan işlemler status ready veya stopped ile birlikte 200 döndürür; devreye alınması hâlâ süren diğer işlemler ise deploying veya stopping ile birlikte 202 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 uç noktayı hazır duruma getirir; healthy, latencyMs ve üst akışın 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örseli veya videoyu özel uç noktadan geçirir. İstek ve yanıt sözleşmeleri model çıkarımı ile eşleşir. Kamera akışları ara sunucudan geçirilmez; bunları Canlı Kamera Çıkarımı bölümünde açıklandığı gibi uç nokta URL'sine gönder.

Ç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 (toplam istek sayısı, hata oranı, ortalama ve p50/p95/p99 gecikme süresi) ile timeSeries (istekler, hatalar, gecikme süresi, CPU, bellek, örnek sayısı) içerir. Kıvılcım çizgisi yanıtı requests24h (saatlik istek sayıları; istek olmayan saatler atlanır), totalRequests, errorRate ve avgLatencyMs (saatlik P95 gecikme sürelerinin ortalaması) döndürür. view=overview ile summary, totalRequests, errorRate ve p95LatencyMs değerlerini; timeSeries ise requests, errors ve latencyP95 değerlerini içerir.

Günlükleri al#

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

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

Sorgu Parametreleri:

Agents API#

Agents iş akışlarını kaydet ve yönet. API, agent tanımlarını saklar; çalıştırmalar, https://platform.ultralytics.com/agents?workflow={id} değerinin kayıtlı bir agent'ı açtığı Agents tuvalinden başlatılır. Python SDK yöntemleri ultralytics-platform>=0.1.74 gerektirir.

Her işlem, ait olduğun bir çalışma alanının kullanıcı adını içeren isteğe bağlı bir owner sorgu parametresini kabul eder (varsayılan: kendi çalışma alanın). Listeleme için görüntüleyici erişimi; kaydetme ve silme için düzenleyici erişimi gerekir.

Agent'ları listele#

GET /api/workflows

Python SDK: client.agents.list()

Yanıt, workflows içinde en son güncellenen en başta olacak şekilde en fazla 100 agent listeler; her agent için id, username, name, version, createdAt ve updatedAt bulunur. id istenmesi, agent'ın graph değerini de döndürür.

Bir agent kaydet#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

Bir agent oluşturmak için version: 0 gönder. Bir agent'ı güncellemek için agent'ın id değerini ve son listeleme veya kaydetme işleminde döndürülen version değerini gönder; eski bir version, 409 döndürür. Bu durumda agent'ı yeniden listele ve tekrar dene. Bağlantıları döngü oluşturan veya bir bloğa birden fazla girdi sağlayan bir grafik 400 döndürür.

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

Yanıt, agent'ın id değerini, yeni version değerini ve tuvalin uyarı vereceği blokları içeren errors değerini döndürür; örneğin veri kümesi seçilmemiş bir Dataset bloğu. Agent her durumda kaydedilir. Her blok türü ve yapılandırması için openapi.json sayfasına bak.

Bir agent'ı sil#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

Agent'ı siler ve etkin çalıştırmalarını iptal eder. Silinen agent'lar Çöp Kutusu bölümünde görünmez ve geri yüklenemez.

Çöp Kutusu API'si#

Yumuşak silinmiş projeleri, veri kümelerini ve modelleri görüntüle, geri yükle ve kalıcı olarak sil. Öğeler 30 gün sonra otomatik olarak tamamen silinir. Çöp Kutusu belgelerine bak.

Çöp Kutusunu listele#

GET /api/trash

Python SDK: client.lifecycle.trash()

Sorgu Parametreleri:

Yanıt, her biri daysRemaining içeren items öğelerini, total, page, limit, totalPages değerlerini ve türe göre toplamları içeren bir summary değerini içerir. id ile bunun yerine etkilenen modelleri ve kalıcı olarak silinecek dağıtımları içeren resources döndürülür.

Öğeyi geri yükle#

POST /api/trash

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

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

Bir projeyi geri yüklemek, projeyle birlikte çöp kutusuna taşınan modelleri de geri yükler; bunlar restoredModels olarak raporlanır.

Kalıcı olarak sil#

DELETE /api/trash

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

Tek bir öğeyi sil:

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

Veya çöp kutusunun tamamını boşalt:

{
    "all": true
}

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

Yükleme API'si#

İmzalı URL'ler kullanarak dosyaları doğrudan bulut depolama alanına yükle. Model yüklemesi tamamlandığında ağırlıkları eklenir; veri kümesi arşivi yüklemesi tamamlandığında arşiv doğrulanır. Ardından oturumu veri kümesi alımına ilet; bu adımı atlarsan yükleme işlemi de tamamlanır. Veri belgelerine bak.

İmzalı yükleme URL'si 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" }
}

Dosyayı PUT isteğiyle uploadUrl adresine yükle; belirttiğin Content-Type değerini ve headers içinde döndürülen tüm üstbilgileri kullan. Veri kümesi yükleme URL'leri 12 saat geçerlidir ve yalnızca dosya oluşturmaya izin verir: aynı URL'ye gönderilen ikinci bir PUT, 412 döndürür; döndürülen üstbilgiler olmadan yapılan PUT ise 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 değerlerini içeren bir file nesnesi. Model yüklemelerinde bu işlem ağırlıkları ekler; veri kümesi arşivlerinde ise işlemeyi başlatmak için önce alım çağrısını yap.

md5 sağlanırsa saklanan nesneyle karşılaştırılarak doğrulanır. Eşleşmeme durumunda 400 döndürülür; henüz tamamlanmamış bir oturumda yüklenen dosya da silinir ve oturum tamamlanmamış olarak bırakılır. Bu nedenle yeni bir imzalı URL iste ve dosyayı yeniden yükle. Arşivi mevcut olan tamamlanmış bir veri kümesi oturumu yeniden tamamlanabilir; ancak farklı özetlere sahip birbiriyle yarışan tamamlama istekleri 409 döndürür. Model oturumları tamamlandığında kaldırılır. checksum, model dosyası üst 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ğla ve bunlara veri kümesi kaynakları olarak göz at. Entegrasyonlar belgelerine bak.

Depolamayı keşfetmek ve bağlamak için çalışma alanı yöneticisi erişimi ve Pro veya Enterprise planı gerekir (aksi durumda 403); entegrasyonları listelemek ve nesnelere göz atmak için düzenleyici erişimi gerekir.

Entegrasyonları listele#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Her biri id, provider, credentialIdentity, targets ve createdAt değerlerini içeren integrations döndürür. Kimlik bilgileri hiçbir zaman 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"]}

Depolamayı bağla#

POST /api/integrations/buckets

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

Keşif işlemindekiyle aynı kimlik bilgisi biçimlerini kullanır; ayrıca 1-50 paket veya kapsayıcı adından oluşan bir targets dizisi gerektirir. Saklanan entegrasyonu içeren 201 döndürü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:

Her kind öğesinin folder veya file olduğu entries değerini 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ıdaki verileri 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ına erişilemez. Ç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 entegrasyonu sayfasına 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 dönüştürür: çalışma alanı ayrıntıları, içe aktarılacak newDatasets, zaten içe aktarılmış (skippedCount), sürümü olmayan, desteklenmeyen ve çözümlenemeyen projelerin sayıları, bytesTotal ve kullanılabilir storage alanın. Roboflow API anahtarı istek gövdesinden okunur ve saklanmaz.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Roboflow'dan içe aktar#

POST /api/integrations/roboflow/import

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

Önizlemede döndürülen öğeleri kullanarak seçilen en fazla 500 Roboflow proje sürümü için alım işleri sıraya alınır.

{
    "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 için depolama alanı gerekir ve her veri kümesi planının içe aktarma başına boyut sınırına uymalıdır.

Hesap API'si#

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

Hesap Özeti#

GET /api/account/summary

Python SDK: client.account.summary()

Anahtarı veren ç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ına ait keyId, name, keyPrefix ve createdAt değerlerini içeren keys döndürür. API anahtarıyla kimlik doğrulanan istekler yalnızca üst 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 bu bölümden 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": 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 ve deployments için sayıları, storage için bayt değerlerini bildirir. limit değerinin -1 olması sınırsız olduğu anlamına gelir; percent ise sınıra ilişkin tam sayı yüzdesidir.

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

GET /api/users

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

Sorgu Parametreleri:

followerCount ve kimliği doğrulanmış çağrılarda isFollowed değerlerini içeren herkese açık user profilini 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 göz at.

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önemi, dönem sonu), metrics (depolama sınırı ve kullanımı), trainingCredit, features, creditsCents ve koltuk sayıları döndürülür.

İşlemleri Görüntüle#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Sorgu Parametreleri:

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

Keşfet API'si#

Toplulukla paylaşılan herkese açık projeleri ve veri kümelerini ara ya da görselleri gösterdiklerine göre ara. Keşfet belgelerine bak.

Herkese Açık İçeriği Ara#

GET /api/explore/search

Python SDK: client.explore.search()

Sorgu Parametreleri:

Yanıt: projects, datasets ve hasMore. type=images, eşleşmelerini bunun yerine images içinde, en iyi eşleşme ilk sırada olacak şekilde döndürür; her eşleşmede kaynak dataset ve 0–1 arası benzerlik score bulunur. Bu işlem q gerektirir ve herkese açık veri kümelerinde, API anahtarı gönderdiğinde ise kendi ve ekip veri kümelerinde arama yapar.

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

Python SDK'sı#

ultralytics-platform, OpenAPI sözleşmesinden oluşturulmuş, her uç nokta için bir yönteme sahip (client.datasets.list, client.models.predict, client.exports.create, ...) tür tanımlı bir Python istemcisidir. Her yöntem, yol parametrelerini konumsal olarak, diğer girdileri anahtar sözcük argümanları olarak ve isteğe bağlı istek başına 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:  # ULTRALYTICS_API_KEY'i veya yolo login tarafından kaydedilen anahtarı okur
    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ı oluşturur, bağlantı hataları ise APIConnectionError hatası oluşturur. Tam README için SDK deposuna göz at.

Python Entegrasyonu#

Eğitim ve çıkarım iş akışları için kimlik doğrulamayı, yüklemeleri ve gerçek zamanlı metrik akışını otomatik olarak yöneten Ultralytics Python paketini kullan. Python 3.11 ve üzeri sürümlerde pip install ultralytics, ultralytics-platform SDK'sını da yükler. model.train(project=...) Platform'u hedeflediğinde, eğitim geri çağırma işlevleri olayları SDK'nın client.training.metrics() aracılığıyla akışa aktarır ve kontrol noktası yükleme URL'lerini OpenAPI belgesindeki POST /api/webhooks/training/metrics ve POST /api/webhooks/models/upload işlemi olan client.models.upload_checkpoint() üzerinden ister; dolayısıyla bunları kendin çağırmana gerek yoktur.

Kurulum ve Yapılandırma#

Platform entegrasyonu için Python>=3.11 ve ultralytics>=8.4.120 gerekir:

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

# Platform veri kümen üzerinde eğitim yap
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

URI Biçimi:

Platform'a Gönderme#

Sonuçları bir Platform projesine gönder:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Sonuçlar Platform ile otomatik olarak senkronize edilir
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 makine ortamı (ana makine adı, işletim sistemi, Python, donanım, git commit'i, komut satırı)

API Örnekleri#

Platform'dan model yükle:

# Kendi modelin
model = YOLO("ul://username/project/model-name")

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

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

results = model("image.jpg")

# Sonuçlara eriş
for r in results:
    boxes = r.boxes  # Algılama kutuları
    masks = r.masks  # Segmentasyon maskeleri
    keypoints = r.keypoints  # Poz anahtar noktaları
    probs = r.probs  # Sınıflandırma olasılıkları

Modeli dışa aktar:

# ONNX'e aktar
model.export(format="onnx", imgsz=640, quantize=16)

# TensorRT'ye dışa aktar
model.export(format="engine", imgsz=640, quantize=16)

# CoreML'e aktar
model.export(format="coreml", imgsz=640)  # sınıflandırma için imgsz=224 kullan

Doğrulama:

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

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

Sık Sorulan Sorular#