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_USERNAMEAşağıdaki her uç nokta, bu referansla aynı sözleşmeden oluşturulan ultralytics-platform SDK'sındaki client.<resource>.<method>(...) çağrısını listeler.
Bu sayfa API'ye rehberli bir tur sunar. Oluşturulan ve sürekli güncel tutulan referans platform.ultralytics.com/api/docs adresinde; bu referansı destekleyen makine tarafından okunabilir OpenAPI 3.2 belgesi ise platform.ultralytics.com/openapi.json adresinde yayımlanır. Her ikisi de doğrudan sunucu tarafındaki sözleşmeden oluşturulduğundan, bu sayfa ile şema uyuşmadığında esas alınması gereken kaynak bunlardır.
API'ye Genel Bakış#
API, Platform'un temel kaynakları etrafında düzenlenmiştir:
| Kaynak | Açıklama | Temel İşlemler |
|---|---|---|
| Veri kümeleri | Etiketlenmiş görüntü koleksiyonları | CRUD, içe aktarma, sürümler, sınıflar, bölümler, klonlama, kopyalama |
| Görüntüler | Tekil görüntüler ve etiketler | Okuma, açıklama ekleme, bölümü değiştirme, silme, otomatik açıklama ekleme, yüzleri bulanıklaştırma |
| Projeler | Model çalışma alanları | CRUD, klonlama |
| Modeller | Eğitilmiş kontrol noktaları | CRUD, tahmin, indirme, klonlama, eğitim durumu |
| Eğitim | Bulut GPU eğitim işleri | GPU kullanılabilirliği, başlatma, ilerleme, iptal etme |
| Dışa aktarımlar | Biçim dönüştürme işleri | Oluşturma, listeleme, durum, iptal etme, mobil bağlantı |
| Dağıtımlar | Özel çıkarım uç noktaları | Oluşturma, güncelleme, başlatma/durdurma, tahmin, metrikler, günlükler |
| Ajanlar | Kaydedilmiş görsel iş akışları | Listeleme, kaydetme, silme |
| Çöp Kutusu | Geçici olarak silinmiş kaynaklar | Listeleme, geri yükleme, kalıcı olarak silme |
| Depolama | Bulut depolama entegrasyonları | Bağlanma, keşfetme, göz atma, bağlantıyı kesme |
| Hesap | Plan, krediler, depolama, profil | Hesap özeti, API anahtarları, depolama kullanımı, kullanıcı arama |
| Faturalandırma | Plan kullanımı ve defter | Kullanım özeti, işlemler |
| Keşfet | Herkese açık içerik arama | Projeleri, veri kümelerini, modelleri ve görselleri ara |
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#
Settings>API Keysbölümüne gitAdd Keyseçeneğine tıkla, sağlayıcı olarakUltralyticsseçeneğini bırak, bir ad gir veCreate Keyseçeneğine tıkla- 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_KEYAPI anahtarları, ul_ sabit önekinden sonra gelen 40 onaltılık karakterden oluşur ve toplam 43 karakter uzunluğundadır (örneğin ul_a1b2c3d4e5f6789012345678901234567890abcd). Üstbilgisi eksik, anahtarı hatalı biçimlendirilmiş veya anahtarı iptal edilmiş istekler 401 döndürür. Anahtarını gizli tut — sürüm denetimine asla ekleme veya herkese açık olarak paylaşma.
Örnek#
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/account/summaryTemel URL#
Tüm API uç noktaları şunu kullanır:
https://platform.ultralytics.com/apiKaynak Yolları#
Çoğu kaynağa, veritabanı kimlikleriyle değil, Platform URL'lerinde görünen aynı okunabilir adlarla erişilir:
| Kaynak | Yol | Örnek |
|---|---|---|
| Veri kümesi | /api/datasets/{owner}/{dataset} | /api/datasets/acme-vision/warehouse |
| Proje | /api/projects/{owner}/{project} | /api/projects/acme-vision/inspection |
| Model | /api/models/{owner}/{project}/{model} | /api/models/acme-vision/inspection/v3 |
| Dağıtım | /api/deployments/{owner}/{deployment} | /api/deployments/acme-vision/edge-1 |
| Görüntü | /api/images/{imageId} | /api/images/65f1c0a2b3d4e5f601234567 |
| Ajan | /api/workflows?id={agentId} | /api/workflows?id=65f1c0a2b3d4e5f601234567 |
{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ünennameadı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.
Ajanlar API'si dışında owner sorgu parametresi yoktur. Çalışma alanı kapsamındaki yollar, sahibi URL yolunda taşır; hesap kapsamındaki uç noktalar (/api/account/summary, /api/api-keys, /api/storage, /api/billing/*, /api/trash, /api/integrations/buckets) ise API anahtarını oluşturan çalışma alanında işlem yapar. Bir ekip çalışma alanında işlem yapmak için o çalışma alanında oluşturulmuş bir API anahtarı kullan veya Ajanlar API'sine owner değerini ilet.
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.
| Kategori | Sınır | Uygulandığı Yer |
|---|---|---|
| Varsayılan | Dakikada 100 istek | Aşağıda listelenmeyen tüm rotalar |
| Eğitim | Dakikada 10 istek | POST /api/training/start |
| Yükle | Dakikada 10 istek | İmzalı yükleme URL'leri, yükleme tamamlama ve veri kümesi içe aktarma |
| Tahmin | Dakikada 20 istek | Platform API rotaları üzerinden model ve dağıtım çıkarımı |
| Dışa Aktar | Dakikada 20 istek | Model dışa aktarımlarını listeleme ve oluşturma, veri kümesi sürümlerini oluşturma veya güncelleme; veri kümesi dışa aktarımını (GET) ve tek bir model dışa aktarımını okuma varsayılan sınırı kullanır |
| İndir | Dakikada 30 istek | Model dosyası indirmeleri |
| Değişiklik | Dakikada 10 istek | API anahtarlarını listeleme, bulut depolama entegrasyonlarını listeleme veya bağlama, depolama konumlarını keşfetme ve dağıtımları güncelleme (PATCH) |
| Veri Yükleme | Dakikada 20 istek | POST /api/datasets/{owner}/{dataset}/images (seçili bir görüntü kümesini getirme) ve GET /api/images/{imageId}/similar |
| Kümeleme | Dakikada 10 istek | GET /api/datasets/{owner}/{dataset}/images/clustering ve GET /api/models/{owner}/{project}/{model}/similar-images |
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.
Bir 429 aldığında yeniden denemeden önce Retry-After saniye (veya X-RateLimit-Reset gerçekleşene kadar) bekle. Üstelik gecikmeli yeniden deneme uygulaması için hız sınırı SSS'sine bak.
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"
}| HTTP Durumu | Anlam |
|---|---|
200 | Başarılı |
201 | Oluşturulma |
202 | Kabul edildi, işlem eşzamansız olarak devam ediyor |
400 | Geçersiz yol, sorgu veya istek gövdesi |
401 | Kimlik doğrulama eksik veya geçersiz |
402 | Yetersiz kredi (eğitim) |
403 | İzinler, plan veya kota yetersiz |
404 | Kaynak bulunamadı |
409 | Mevcut durumla çakışma (yinelenen ad, devam eden iş) |
413 | Tahmin girdisi çok büyük |
422 | Model sınıfları veri kümesiyle eşleşmiyor veya sağlayıcı anahtarı eksik ya da reddedilmiş (otomatik etiketleme) |
429 | Hız sınırı aşıldı |
500 | Sunucu hatası |
502 | Üst akış sağlayıcı veya hizmet çağrısı başarısız oldu |
503 | Bağımlı hizmet geçici olarak kullanılamıyor |
Sayfalandırma#
Sayfalandırma yöntemi koleksiyona bağlıdır:
| Yöntem | Uç Noktalar | Parametreler |
|---|---|---|
| Yalnızca limit | Veri kümeleri, projeler, modeller, dışa aktarımlar ve dağıtım listeleri | limit |
| Ofset ve limit | Veri kümesi görüntüleri, görüntü kümeleme, Keşfet araması | offset, limit ve yanıtta hasMore |
| İmleç | Veri kümesi görüntüleri (büyük veri kümeleri) | cursor, includeTotal ve nextCursor |
| Sayfa numarası | Çöp kutusu | page, limit ve totalPages |
| Opak sayfa belirteci | Dağıtım günlükleri | pageToken ve nextPageToken |
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:
| Parametre | Tür | Açıklama |
|---|---|---|
limit | int | Döndürülecek en fazla veri kümesi sayısı (varsayılan: 1000, en fazla: 1000) |
includeSamples | boolean | Örnek görüntü önizlemelerini ekle (varsayılan: true) |
includeImageUrls | boolean | Tam boyutlu örnek görüntü yedek URL'lerini ekle (varsayılan: false) |
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/datasetsPython 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"
}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
dataset | string | Evet | Platform URL'lerinde kullanılan veri kümesi adı (küçük harfli, tireyle ayrılmış, en fazla 128 karakter) |
name | string | Evet | Görünen ad (en fazla 100 karakter) |
description | string | Hayır | Açıklama (en fazla 1000 karakter) |
task | string | Hayır | Görev türü (varsayılan: detect) |
classNames | array | Hayır | Sınıf adları dizin sırasındadır (en fazla 25.000); yinelenen ad yoktur ve 2 karakterden uzun adlarda büyük/küçük harf duyarlılığı yoktur |
format | string | Hayır | Etiket biçimi: yolo (varsayılan), coco, raw, ndjson |
visibility | string | Hayır | public veya private (varsayılan: çalışma alanının varsayılan görünürlüğü) |
blurFaces | boolean | Hayır | Veri kümesine yüklenen görüntülerdeki yüzleri bulanıklaştır (Yüzleri Bulanıklaştır sayfasına bak) |
tags | array | Hayır | Her biri 50 karakterden oluşan en fazla 50 etiket |
license | string | Hayır | Veri kümesi lisans tanımlayıcısı |
metadata | object | Hayır | Özel JSON meta verileri |
owner | string | Hayır | Ekip çalışma alanı kullanıcı adı; varsayılan olarak kişisel çalışma alanın kullanılır |
Çalışma alanında, Çöp Kutusu'ndakiler dahil, zaten bulunan bir dataset kısa adı 409 döndürür.
Veri kümesi oluştururken veya güncellerken geçerli task değerleri: detect, segment, semantic, depth, classify, pose ve obb. Derinlik veri kümelerinde sınıf bulunmaz.
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}/clonePython SDK: client.datasets.clone(owner, dataset)
Erişebildiğin bir veri kümesini, görselleri ve etiketleriyle birlikte kişisel çalışma alanına veya bir ekip çalışma alanına kopyalar. İsteğe bağlı splits (train, val, test) veya imageIds (en fazla 1.000) veri kümesinin yalnızca bir bölümünü klonlar; version canlı görseller yerine kayıtlı bir sürümü klonlar; annotations: false görselleri etiketsiz kopyalar ve into yeni bir veri kümesi oluşturmak yerine görselleri etiketsiz olarak sahibi olduğun bir veri kümesine ekler. version, splits, imageIds, into veya annotations: false ile birlikte kullanılamaz.
İ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ğını kullanan veri kümeleri veya işlenmekte olan ya da bağlı bir into veri kümesi 409 döndürür. visibility belirtilmezse klon, hedef çalışma alanının varsayılan görünürlüğü Private olduğunda gizli olur; değilse kaynak veri kümesinin görünürlüğünü korur.
Veri Kümesi Dışa Aktarımını İndir#
GET /api/datasets/{owner}/{dataset}/exportPython 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:
| Parametre | Tür | Açıklama |
|---|---|---|
v | integer | Kaydedilmiş sürüm numarası (1'den başlar). Geçerli veri kümesini almak için belirtme. |
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}/exportPython 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}/exportPython 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}/restorePython 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)
| Parametre | Tür | Açıklama |
|---|---|---|
base | int | Karşılaştırmanın başlangıç sürümü |
head | int | Karşılaştırmanın hedef sürümü |
cursor | string | Önceki sayfadaki nextCursor |
hash | string | Bir öğenin hash değeri: değişiklikleri değil, her sürümde saklandığı hâliyle o görüntüyü döndürür |
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-statsPython 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/mergePython 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/deletePython 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).
Birleştirme veya silme işleminden sonra kalan kimlikler kaydığı için bu işlemler idempotent değildir. Başka bir sınıf işlemi yapmadan önce mevcut sınıf indekslerini almak için veri kümesini yeniden getir.
Bölümleri Yeniden Dağıt#
POST /api/datasets/{owner}/{dataset}/splits/redistributePython 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}/embeddingsPython SDK: client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)
GET analiz özetini döndürür (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST, bir embedding analizini sıraya alır ve jobId içeren 202 döndürür; veri kümesinin depolama alanında AI özellikleri kapalıysa veya depolama On Premise ise 409 döndürür. DELETE etkin işi iptal eder ve iptal edilen iş kimliğini veya null döndürür.
Görüntü Kümeleme#
GET /api/datasets/{owner}/{dataset}/images/clusteringPython 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}/modelsPython 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}/imagesPython SDK: client.datasets.images(owner, dataset)
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
limit | int | Döndürülecek en fazla görüntü sayısı (varsayılan: 50, en fazla: 5000) |
offset | int | Atlanacak görüntü sayısı (varsayılan: 0) |
cursor | string | İmleçle sayfalama için önceki sayfadaki son görüntü kimliği |
includeTotal | boolean | Eşleşen toplam sayıyı dahil et (varsayılan: true) |
split | string | Bölüme göre filtrele: train, val, test |
hasLabel | boolean | Açıklama durumuna göre filtrele |
hasError | boolean | İşleme hatası durumuna göre filtrele |
classIds | string | Virgülle ayrılmış sınıf kimlikleri; bunlardan herhangi birini içeren görüntüleri döndürür |
search | string | Dosya adında, sınıf adında ve özel meta verilerde alt dize eşleşmesi (en fazla 200 karakter); img_0042.jpg gibi görsel dosyası uzantısıyla biten bir terim yalnızca dosya adlarında eşleşir |
q | string | sort yerine alaka düzeyine göre sıralar: önce metin eşleşmeleri, ardından benzeyen en fazla 1.000 öğe; bir kimlik, özet veya dosya adı search olarak kullanılır (en fazla 200 karakter) |
sort | string | newest (varsayılan), oldest, name-asc, name-desc, height-asc, height-desc, width-asc, width-desc, size-asc, size-desc, labels-asc, labels-desc |
includeThumbnails | boolean | İmzalı küçük resim URL'lerini dahil et (varsayılan: true) |
includeImageUrls | boolean | İmzalı tam boyutlu görüntü URL'lerini dahil et (varsayılan: false) |
includeLabels | boolean | Sınırlandırılmış önizleme açıklamalarını dahil et (varsayılan: false) |
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}/imagesPython 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/adoptPython 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}/ingestPython 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:
| Alan | Tür | Açıklama |
|---|---|---|
sessionId | string | POST /api/upload/signed-url yükleme oturumu; POST /api/upload/complete çağrılmamışsa içe alma işlemi yüklemeyi doğrular ve tamamlar |
sourceUrl | string | ZIP, TAR, TAR.GZ, TGZ veya NDJSON dosyasının herkese açık HTTP ya da HTTPS URL'si (en fazla 4096 karakter) |
reference | object | Bağlı bir kaynak: bulut depolama (provider: "cloud", integrationId, target, prefix) veya şirket içi (provider: "local", keyId, root, prefix) |
targetSplit | string | train, val veya test; arşivin bölüm yapısını geçersiz kılar |
conflictPolicy | string | Dosya adı veya içerik çakışmaları için skip, keep_both ya da replace |
classMapping | object | Gelen sınıf adlarını bir sınıf indeksine, mevcut veya yeni bir sınıf adına ya da atlamak için null değerine eşler |
imageMetadata | object | Her görüntünün arşive göreli yolu veya NDJSON file değeriyle anahtarlanan özel meta veriler |
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.
İlk alım işlemi, arşivdeki sınıflardan otomatik olarak sınıflar oluşturur. Sonraki alımlarda classMapping içinde belirtilmeyen arşiv sınıfları, iki karakterden uzun adlarda büyük/küçük harf duyarlılığı olmadan mevcut veri kümesi sınıflarıyla ada göre eşleştirilir; eşleşmeyen sınıflar yeni sınıflar olarak eklenir. Etiketler yalnızca açıkça null olarak eşleştirilen sınıflar için atlanır.
Yanıt (201):
{
"jobId": "65f1c0a2b3d4e5f6012345aa",
"status": "queued"
}Python kullanarak meta verilerle tek bir görüntü yükle
Aynı kod bir görüntü grubunu da işler: ZIP dosyasına daha fazla dosya, imageMetadata içine de eşleşen girdiler ekle.
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 }
}Etiket koordinatları, YOLO'nun 0 ile 1 arasındaki normalleştirilmiş değerlerini kullanır. Sınırlayıcı kutular [x_center, y_center, width, height] kullanır. Segmentasyon etiketleri segments ve düzleştirilmiş bir çokgen köşe noktaları listesi olan [x1, y1, x2, y2, ...] değerini kullanır. Poz etiketleri, tek ve tutarlı bir düz biçimde keypoints kullanır: görünürlük için geleneksel olarak 0, 1 veya 2 değerlerini kullanan ikililer [x1, y1, x2, y2, ...] ya da üçlüler [x1, y1, v1, x2, y2, v2, ...]. Yönlendirilmiş kutular obb köşelerini kullanır. Kaydedilen koordinatlar 5 ondalık basamağa yuvarlanır ve bir görüntü en fazla 10.000 açıklama içerebilir.
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}/predictPython 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.
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
modelId | string | Evet | Tam nitelikli model URI'si, ul://{owner}/{project}/{model} veya 1–200 sınıflı bir algılama veri kümesi için sınıf istemli model kimliği (yoloe26x, visualPrompts ile segmentasyon ve OBB veri kümelerini de destekler): barındırılan bir model (qwen, gemma, nemotron, moondream, wevisone, florence2, owlv2, yoloe26x, sam3, sam3.1, groundingdino) veya openapi.json içindeki modelId enum değerinden bir ücretli sağlayıcı model kimliği |
confidence | float | Hayır | Güven eşiği, 0.01–1.0 (varsayılan: 0.25); visualPrompts olmayan sınıf istemli modellerde yok sayılır; bu modeller modele özgü eşikler kullanır. |
iou | float | Hayır | Maksimum olmayan bastırma için IoU eşiği, 0.0 – 0.95 (varsayılan: 0.5); visualPrompts içermeyen sınıf istemli modellerde yok sayılır |
visualPrompts | array | Hayır | modelId yoloe26x ile bir tespit, segmentasyon veya OBB veri kümesinde, bu görüntüdeki 1–200 açıklama nesnesi (classId ile birlikte bbox, segments veya obb) ya da sınıflarını modelin görüntüde yeniden bulduğu referenceImageId görüntüsündeki nesneler |
referenceImageId | string | Hayır | visualPrompts ile, istemlerin çizildiği aynı veri kümesindeki görüntünün kimliği; tahmin yapılan görüntü değilse |
classMapping | array | Hayır | Bir YOLO modeli için, her model sınıfının sırasıyla karşılık geldiği veri kümesi sınıfı dizini veya sınıfı çıkarmak için null; uzunluk yanlışsa ya da dizin veri kümesi sınıflarının dışındaysa 400 döndürülür. Sınıf istemli modellerde yok sayılır ve visualPrompts ile kullanılamaz. |
Yanıt: success, predictions (açıklama nesneleri), confidences (dizinle hizalanmış puanlar; visualPrompts olmayan sınıf istemli modeller için boş), modelUsed, inferenceTime, usage (dil modeli bunları bildirdiğinde [input tokens, output tokens]), sınıf istemli modeller için partial (yanıtı çıktı veya süre sınırı kısalttığında ya da bundan şüphelenildiğinde true; bu durumda döndürülen açıklamalarda bazı nesneler bulunmayabilir) ve ücretli sağlayıcı modelleri için isteğe bağlı cost (sağlayıcı anahtarına faturalandırılan tahmini sağlayıcı maliyeti, USD cinsinden; tahmin yoksa eklenmez). Sınıfları veri kümesiyle eşleşmeyen bir YOLO modeli 422 döndürür. Sınıf istemli bir model, algılama dışı bir veri kümesinde veya 1–200 sınıf aralığının dışında kullanıldığında (visualPrompts kullanmıyorsa), başka bir model ya da görevle birlikte visualPrompts, bilinmeyen bir classId, çok küçük veya görüntünün dışında bir istem ya da classMapping durumunda da aynı yanıt döner. Veri kümesinin çalışma alanındaki Ayarlar > API Anahtarları bölümünde kayıtlı sağlayıcı anahtarı olmayan ücretli bir sağlayıcı modeli code döndürür (missing_provider_api_key: referenceImageId). Bu veri kümesindeki bir görüntü olmayan 404, 422 döndürür. Sağlayıcı hatalarında sağlayıcının mesajı yer alır: sağlayıcı 400, 401, 402, 403 veya 404 yanıtını verdiğinde code (reddedilen bir anahtar, model veya istek ya da ödenmemiş sağlayıcı bakiyesi; provider_refused: 400 dışındaki tüm durumlar için), hız sınırı aşıldığında 429, diğer tüm sağlayıcı hatalarında 503 döner. Derinlik veri kümeleri 400 döndürür. Şirket İçi veri kümeleri, yapay zekâ özellikleri kapalı veya kimlik bilgisi bağlantısı kesilmiş bulut depolama veri kümeleri ve 3'ten fazla görüntü kanalı olan veri kümeleri 409 döndürür.
Benzer görüntüleri bul#
GET /api/images/{imageId}/similarPython SDK: client.images.find_similar_images(image_id)
Herkese açık veri kümelerinden ve senin kendi veri kümelerinden ve ekip veri kümelerinden görsel olarak benzer en fazla 24 images döndürür. Her sonuçta score (0-1), işaretli bir thumbnailUrl ve kaynak dataset (owner, dataset, license) bulunur. Kaynak veri kümesi ve sorgu görselinin kopyasını barındıran veri kümeleri hariç tutulur; includeSourceDataset=true bu veri kümelerini dahil eder ve yalnızca kopyaları hariç tutar. license (Kullanılabilir Lisanslar bölümündeki virgülle ayrılmış tanımlayıcılar; lisansı olmayan veri kümeleri için None) ve publicOnly=true (yalnızca herkese açık veri kümeleri) aramayı daraltır; arama yine en fazla 24 görsel döndürür. Görseli görüntüleme erişimi olan bir API anahtarı gerekir. Henüz gömme vektörüyle işlenmemiş bir görsel önce işlenir; 503 bu işlemin başarısız olduğu anlamına gelir, bu nedenle yeniden dene. Bulut depolama görselinin kendi veri kümesi yalnızca o çalışma alanı için dahil edilir; 409 ise görselin depolama alanında AI özelliklerinin kapalı olduğu veya veri kümesinin On Premise olduğu anlamına gelir.
Veri Kümesini Otomatik Açıkla#
POST /api/datasets/{owner}/{dataset}/predict/batchPython SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)
Bir veri kümesi sürümünü kaydeder (bulut depolama veri kümelerinde sürüm bulunmaz), ardından veri kümesindeki etiketsiz görüntüleri modelle etiketleyen bir çalıştırmayı kuyruğa alır ve 202 döndürür. İstek gövdesi, tek görüntü uç noktasındaki modelId, confidence, iou ve classMapping alanlarının aynısını ve zaten etiketli görüntülere de etiket eklemek için includeAnnotated alanını alır (varsayılan değer false). modelId yoloe26x, visualPrompts ve referenceImageId ile (bunlarla birlikte zorunludur; bunlar olmadan 422, ilgili görüntü artık veri kümesinde yoksa 404) çalıştırmanın görüntülerindeki örneklere benzeyen nesneler tespit, segmentasyon ve OBB veri kümelerinde bulunur (yalnızca etiketsiz görüntülerde; includeAnnotated belirtilmediği sürece); örnekler çalıştırma başladığında bir kez kodlanır. Bir sınıf istemi kullanan model veri kümesi sınıflarını güven skorları olmadan tespit eder ve ücretli bir sağlayıcı modeli için, çalıştırma kabul edilmeden önce veri kümesinin çalışma alanındaki Ayarlar > API Anahtarları bölümünde kayıtlı bir sağlayıcı anahtarı gerekir (422, code: missing_provider_api_key). Mevcut etiketler hiçbir zaman değiştirilmez, aynı sınıftaki mevcut bir etiketle iou değerinden fazla örtüşen tahminler atlanır ve çalıştırma, gerçekten işlediği görüntüler için ücretlendirilir. 402, bakiyenin tahmini maliyeti karşılayamayacağı anlamına gelir; 409, veri kümesinin hazır olmaması, depolama alanında AI özelliklerinin kapalı olması veya depolamanın şirket içi kurulumda olması, etiketlenecek görüntü kalmaması ya da hâlihazırda devam eden bir çalıştırma bulunması anlamına gelir; 422 ise veri kümesinde hiç sınıf bulunmaması ya da sınıf istemi kullanan bir modele tespit görevi dışındaki bir veri kümesi veya 1–200 sınıf aralığının dışında kalan bir veri kümesi verilmesi anlamına gelir: bu uç noktayı çağırmadan önce sınıflar uç noktası üzerinden sınıfları oluştur; uygulamadaki Sınıfları eşleştir 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/bulkPython 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/bulkPython 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/urlsPython 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:
| Parametre | Tür | Açıklama |
|---|---|---|
limit | int | Döndürülecek en fazla proje sayısı (varsayılan: 20, en fazla: 500) |
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/projectsPython SDK: client.projects.create(project=..., name=...)
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
project | string | Evet | Platform URL'lerinde kullanılan proje adı |
name | string | Evet | Görünen ad (en fazla 100 karakter) |
description | string | Hayır | Açıklama (en fazla 1000 karakter) |
visibility | string | Hayır | public veya private (varsayılan: çalışma alanının varsayılan görünürlüğü) |
tags | array | Hayır | En fazla 50 etiket |
license | string | Hayır | Proje lisans tanımlayıcısı |
metadata | object | Hayır | Özel JSON meta verileri |
owner | string | Hayır | Ekip çalışma alanı kullanıcı adı; varsayılan olarak kişisel çalışma alanın kullanılır |
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/projectsYanı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. Slug'ı değiştiren bir name değişikliği, projedeki herhangi bir model eğitime başlamaktayken 409 döndürür.
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}/clonePython 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, bir hedef owner ve tamamlanmış tüm modeller yerine klonlanacak model adlarının listesini içeren models alanlarını kabul eder. visibility belirtilmezse klon, hedef çalışma alanının varsayılan görünürlüğü Özel olduğunda gizli olur; aksi durumda kaynak projenin görünürlüğünü korur. Modelleri hedef çalışma alanının model sınırını aşacak bir klonlama 403 döndürür ve hiçbir şeyi kopyalamaz.
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)
Listelenen modellerin doğrulama plots ve trainResults bilgileri gösterilmez; Modeli Al bu bilgileri döndürür.
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
limit | int | Döndürülecek en fazla model sayısı (varsayılan: 20, maksimum: 100) |
Modeli Al#
GET /api/models/{owner}/{project}/{model}Python SDK: client.models.retrieve(owner, project, model)
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
analysis | int | Model yerine görüntü başına doğrulama analizini döndürmek için 1 olarak ayarla |
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/modelsPython SDK: client.models.create(body=...)
Ağırlık ekleyebileceğin veya eğitebileceğin, eğitilmemiş bir model kaydı oluşturur.
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
project | string | Evet | Hedef proje adı |
owner | string | Hayır | Çalışma alanı tanıtıcısı; varsayılan olarak kişisel çalışma alanın kullanılır |
model | string | Hayır | Platform URL'lerinde kullanılan model adı; belirtilmezse oluşturulur |
name | string | Hayır | Görünen ad (yalnızca model ile birlikte kabul edilir) |
description | string | Hayır | Açıklama (en fazla 1000 karakter) |
task | string | Hayır | detect, segment, semantic, depth, classify, pose veya obb |
metadata | object | Hayır | Özel JSON meta verileri |
trainArgs | object | Hayır | Kaydedilecek eğitim argümanları |
metrics | object | Hayır | mAP50, mAP50-95, precision, recall gibi metrikler |
epochs | sayı | Hayır | Önceden eğitilmiş bir modelin epoch sayısı |
version | string | Hayır | Sürüm etiketi (en fazla 50 karakter) |
Yanıt (201): id, owner, project, model, name, region. Yanıt, adlandırma çakışmaları çözümlendikten sonra seçilen model kısa adını ve görünen adını içerir.
.pt ağırlıklarını eklemek için assetType: "models" ile imzalı bir yükleme URL'si iste ve bu modelin id değerini assetId olarak gönder, dosyayı döndürülen URL'ye PUT ile yükle, ardından döndürülen sessionId ile POST /api/upload/complete çağrısını yap.
Modeli Güncelle#
PATCH /api/models/{owner}/{project}/{model}Python SDK: client.models.update(owner, project, model)
Kabul edilen alanlar şunlardır: name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError ve starred. Tek başına projectId iletmek, modeli aynı sahibin başka bir projesine taşır; yanıt, hedef projedeki modelin slug değerini, slug hedef projede zaten kullanılıyorsa renamed: true değerini ve model hâlâ eğitiliyorsa 409 değerini döndürür. Slug'ı değiştiren bir name değişikliği, eğitim başlarken 409 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}/filesPython SDK: client.models.files(owner, project, model)
Modelin ağırlıkları için modelin adını taşıyan kısa ömürlü imzalı URL'ler döndürür ({model}.pt).
{
"files": [
{
"name": "my-model.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-imagesPython 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örsellerine benzeyen en fazla 100 images döndürür; sonuç biçimi Find Similar Images ile aynıdır ve eğitim veri kümesinin zaten içerdiği görseller hariç tutulur. En kötü görsellerin bir alt kümesinde arama yapmak için hashes (virgülle ayrılmış, en fazla 100) değerini; aramayı Find Similar Images bölümündeki gibi daraltmak içinse license veya publicOnly değerini gönder. Modelin çalışma alanına erişimi olan bir API anahtarı gerekir. Çalıştırmada görsel başına sonuç kaydedilmemişse liste boş olur. 404, en kötü görsellerin henüz gömme vektörleriyle işlenmediği anlamına da gelir: önce eğitim veri kümesinde veri kümesi gömme vektörlerini oluştur.
Modeli klonla#
POST /api/models/{owner}/{project}/{model}/clonePython 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"
}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
project | string | Evet | Hedef proje adı |
owner | string | Hayır | Hedef çalışma alanı; varsayılan olarak kişisel çalışma alanın kullanılır |
model | string | Hayır | Hedef model adı |
name | string | Hayır | Hedef görünen ad |
description | string | Hayır | Klonun açıklaması |
Çıkarımı Çalıştır#
POST /api/models/{owner}/{project}/{model}/predictPython 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:
| Parametre | Tür | Varsayılan | Aralık | Açıklama |
|---|---|---|---|---|
file | file | - | - | Görüntü veya video dosyası (source ayarlanmadıysa gereklidir) |
conf | float | 0.25 | 0.01 – 1.0 | Minimum güven eşiği |
iou | float | 0.5 | 0.0 – 0.95 | NMS IoU eşiği |
imgsz | int | - | 32 – 1280 | Piksel cinsinden giriş görüntüsü boyutu; varsayılan olarak modelin eğitim boyutu kullanılır (mevcut değilse 640) |
normalize | bool | false | - | Sınırlayıcı kutu koordinatlarını 0 – 1 aralığında döndür |
decimals | int | 5 | 0 – 10 | Koordinat değerleri için ondalık hassasiyet |
vid_stride | int | 1 | ≥ 1 | Videonun her N'inci karesinde tahmin yap; görüntülerde bu parametre yok sayılır |
bits | int | 8 | 8, 12, 16 | Derinlik haritası niceleme; yalnızca derinlik modelleri için |
source | string | - | - | Görüntü URL'si veya base64 dizesi (file yerine kullanılabilir); Platform API'si üzerinden en fazla 4.096 karakter |
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/predictYanıt:
images içindeki her kayıt shape, speed, results (görüntü başına en fazla 1.000, RT-DETR modellerinde 300) ve yoğun tahmin görevlerinde semantic_mask veya depth PNG verisi taşır (derinlik değerleri pixel × max / divisor biçimindedir; varsayılan 8 bitlik harita için bölen 255, bits 12 veya 16 olduğunda ise 65535'tir). metadata nesnesi görüntü sayısını, işlev zamanlamalarını, 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 Denetle#
GET /api/models/{owner}/{project}/{model}/trainingPython 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}/trainingPython 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-availabilityPython 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/startPython SDK: client.training.start(model_id=..., train_args=...)
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
modelId | string | Evet | Eğitilecek modelin kimliği |
trainArgs | object | Evet | YOLO eğitim bağımsız değişkenleri; model, data ve epochs gereklidir. data, ul://username/datasets/slug veri kümesi URI'si veya coco8.yaml gibi yerleşik bir veri kümesi YAML dosyasıdır |
gpuType | string | Hayır | Kullanılacak bulut GPU'su (varsayılan: rtx-4090) |
captureDatasetVersion | boolean | Hayır | Bu çalıştırma için değişmez bir veri kümesi sürümü kaydet (varsayılan: false) |
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"modelId": "65f1c0a2b3d4e5f601234599",
"gpuType": "rtx-4090",
"trainArgs": {
"model": "yolo26n.pt",
"data": "ul://acme-vision/datasets/warehouse",
"epochs": 100,
"imgsz": 640,
"batch": 16
}
}' \
https://platform.ultralytics.com/api/training/startYanıt:
{
"modelId": "65f1c0a2b3d4e5f601234599",
"status": "starting",
"gpuType": "rtx-4090",
"estimatedCost": { "pricePerHour": 0.89, "gpuMemoryGb": 24 },
"billing": {
"estimatedCostCents": 178,
"estimatedCostDisplay": "$1.78",
"balanceCents": 2500
}
}data, veri kümesi kimliği veya ul:// olmadan Platform veri kümesi yolu olduğunda ya da model görevi veri kümesi görevinde eğitim yapamadığında eğitim 400 değerini döndürür; kredi bakiyen yetersiz olduğunda 402, veri kümesinin bulut depolama alanında AI özellikleri kapalı ya da bağlantısı kesilmiş olduğunda 409, istenen GPU için kapasite bulunmadığında ise 503 değerini döndürür.
rtx-2000-ada ile b300 arasında, rtx-4090, l40s, a100-80gb-pcie, a100-80gb-sxm, rtx-pro-6000, h100-sxm, h200-sxm ve b200 dâhil 26 GPU türü kullanılabilir. Tam liste için Bulut Eğitimi sayfasına bak.
Dışa Aktarımlar API'si#
Modelleri ONNX, TensorRT, CoreML ve LiteRT gibi eniyileştirilmiş biçimlere dönüştürerek uç cihazlara dağıt.
Dışa Aktarımları Listele#
GET /api/models/{owner}/{project}/{model}/exportsPython SDK: client.exports.list(owner, project, model)
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
status | string | queued, starting, running, completed, failed veya cancelled değerine göre filtrele |
limit | int | Döndürülecek en fazla dışa aktarım sayısı (varsayılan: 20, maksimum: 100) |
Dışa Aktarım Oluştur#
POST /api/models/{owner}/{project}/{model}/exportsPython SDK: client.exports.create(owner, project, model, format=...)
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
format | string | Evet | Hedef dışa aktarım biçimi (aşağıdaki tabloya bak) |
gpuType | string | Koşullu | format değeri engine olduğunda gereklidir; desteklenen bir GPU veya Jetson hedefi kullan |
args | object | Hayır | Dışa aktarma seçenekleri: imgsz, quantize, dynamic, simplify, opset, conf, iou, batch, workspace, nms, optimize ve name (RKNN, QNN, Hailo, Ascend ve Xilinx için hedef cihaz) |
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/exportsHer biçim yalnızca aşağıdaki dışa aktarma tablosunun Bağımsız Değişkenler sütunundaki seçenekleri dikkate alır: desteklemeyen bir biçim için varsayılan olmayan batch, dynamic, opset, simplify, workspace veya optimize değeri kullanılırsa 400 döndürülür. imx dışa aktarmaları yalnızca INT8 biçimindedir ve detect, segment, classify ve pose modellerinde kullanılabilir; adı YOLOv8n veya YOLO11n dışında bir YOLO modelini belirten model 400 döndürür.
Yanıt (201): id, format, status (queued veya running), region ve TensorRT dışa aktarımları için gpuType. Model için aynı biçimde bir dışa aktarma işlemi sürerken gelen yeni bir istek, args değerinden bağımsız olarak 409 döndürür.
Desteklenen Biçimler:
Aşağıdaki ortak dışa aktarma tablosunda, ST Edge AI dışındaki herhangi bir satırdaki format bağımsız değişkenini kullan. PyTorch kaynak biçimidir ve API dışa aktarma hedefi değildir.
| Biçim | format bağımsız değişkeni | Model | Üst veriler | Bağımsız değişkenler |
|---|---|---|---|---|
| PyTorch | - | yolo26n.pt | ✅ | - |
| TorchScript | torchscript | yolo26n.torchscript | ✅ | imgsz, quantize, dynamic, nms, batch, device |
| ONNX | onnx | yolo26n.onnx | ✅ | imgsz, quantize, dynamic, simplify, opset, nms, batch, data, fraction, device |
| OpenVINO | openvino | yolo26n_openvino_model/ | ✅ | imgsz, quantize, dynamic, nms, batch, data, fraction, device |
| TensorRT | engine | yolo26n.engine | ✅ | imgsz, quantize, dynamic, simplify, opset, workspace, nms, batch, data, fraction, device |
| CoreML | coreml | yolo26n.mlpackage | ✅ | imgsz, dynamic, quantize, nms, batch, device |
| Apple Core AI | coreai | yolo26n.aimodel | ✅ | imgsz, batch, quantize |
| TF SavedModel | saved_model | yolo26n_saved_model/ | ✅ | imgsz, quantize, opset, nms, batch, data, fraction, device |
| TF GraphDef | pb | yolo26n.pb | ❌ | imgsz, opset, batch, device |
| TF Edge TPU | edgetpu | yolo26n_edgetpu.tflite | ✅ | imgsz, quantize, opset, data, fraction, device |
| LiteRT | litert | yolo26n.tflite | ✅ | imgsz, quantize, batch, data, fraction, device |
| PaddlePaddle | paddle | yolo26n_paddle_model/ | ✅ | imgsz, batch, device |
| MNN | mnn | yolo26n.mnn | ✅ | imgsz, batch, dynamic, quantize, simplify, opset, nms, device |
| NCNN | ncnn | yolo26n_ncnn_model/ | ✅ | imgsz, quantize, device |
| IMX500 | imx | yolo11n_imx_model/ | ✅ | imgsz, quantize, data, fraction, nms, device |
| RKNN | rknn | yolo26n_rknn_model/ | ✅ | imgsz, batch, name, quantize, simplify, opset, data, fraction, device |
| ExecuTorch | executorch | yolo26n_executorch_model/ | ✅ | imgsz, quantize, batch, data, fraction, device |
| Axelera | axelera | yolo26n_axelera_model/ | ✅ | imgsz, batch, quantize, data, fraction, device |
| DEEPX | deepx | yolo26n_deepx_model/ | ✅ | imgsz, quantize, simplify, opset, data, optimize, device |
| Qualcomm QNN | qnn | yolo26n_qnn.onnx | ✅ | imgsz, batch, name, quantize, simplify, opset, data, fraction, device |
| Hailo | hailo | yolo26n_hailo_model/ | ✅ | imgsz, name, quantize, data, fraction, simplify, conf, iou, device |
| Huawei Ascend | ascend | yolo26n_ascend_model/ | ✅ | imgsz, batch, name, quantize, opset, simplify, nms, device |
| AMD Xilinx | xilinx | yolo26n_xilinx_model/ | ✅ | imgsz, name, quantize, data, fraction, opset, simplify, device |
| NXP | nxp | yolo26n_nxp.tflite | ✅ | imgsz, quantize, data, fraction, device |
| ST Edge AI | stedgeai | yolo26n_stedgeai.onnx | ✅ | imgsz, quantize, data, fraction, opset, simplify, device |
nms=None, harici NMS için varsayılan olarak ham çıktılar üretir (YOLO26, Axelera üzerinde NMS içermeyen başlığını korur). Kullanılabilir NMS içermeyen bir başlık seçmek için nms=False değerini ayarla; desteklenmeyen biçimler yerel çıktı yoluna geri döner. Yukarıdaki nms girdileri, nms=True ile NMS gömebilen biçimleri belirtir.
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.
Mobil İçe Aktarma Bağlantısı Oluştur#
POST /api/models/{owner}/{project}/{model}/exports/{exportId}/mobilePython SDK: henüz yok; HTTP isteğini doğrudan gönder.
Tamamlanmış bir CoreML, Core AI veya LiteRT dışa aktarımını Ultralytics YOLO uygulamasında açmak için importUrl ve expiresAt değerlerini döndürür. Bağlantının süresi 24 saat sonra dolar ve bağlantıya sahip olan herkes bu süre dolana kadar dışa aktarımı indirebilir. Tamamlanmamış veya uyumlu olmayan bir dışa aktarım 409 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:
| Parametre | Tür | Açıklama |
|---|---|---|
status | string | creating, deploying, ready, stopping, stopped veya failed |
model | string | {project}/{model} değerine göre filtrele; örneğin inspection/v3 |
limit | int | Döndürülecek en fazla dağıtım sayısı (varsayılan: 20, maksimum: 100) |
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"
}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
project | string | Evet | Modeli içeren proje |
model | string | Evet | Dağıtılacak model |
deployment | string | Evet | Platform URL'lerinde kullanılan dağıtım adı |
name | string | Evet | Görünen ad |
region | string | Evet | Desteklenen 42 dağıtım bölgesinden biri |
cpu | sayı | Hayır | vCPU çekirdekleri: 1 (varsayılan), 2, 4, 6 veya 8 |
memoryGi | sayı | Hayır | Bellek, GiB cinsinden: 2 (varsayılan), 4, 8, 16, 24 veya 32 |
Yanıt (201): id, deployment, status (creating), message ve region.
Varsayılan 1 vCPU / 2 GiB boyutu, boşta kaldığında sıfıra ölçeklenir ve ücretsiz dağıtım kotasını kullanabilir; diğer boyutlar kullanıma dayalı ücretlendirmeye tabidir. Geçerli değerler, her dağıtım okumasında resources nesnesinde döndürülür.
En düşük gecikme için kullanıcılarına yakın bir bölge seç. Platform kullanıcı arayüzü, mevcut 42 bölgenin tümü için gecikme tahminlerini gösterir.
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}/healthPython 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}/predictPython 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:
| Parametre | Tür | Varsayılan | Aralık | Açıklama |
|---|---|---|---|---|
file | file | - | - | Görüntü veya video dosyası (source ayarlanmadıysa gereklidir) |
conf | float | 0.25 | 0.01 – 1.0 | Minimum güven eşiği |
iou | float | 0.5 | 0.0 – 0.95 | NMS IoU eşiği |
imgsz | int | - | 32 – 1280 | Piksel cinsinden giriş görüntüsü boyutu; varsayılan olarak modelin eğitim boyutu kullanılır (mevcut değilse 640) |
normalize | bool | false | - | Sınırlayıcı kutu koordinatlarını 0 – 1 aralığında döndür |
decimals | int | 5 | 0 – 10 | Koordinat değerleri için ondalık hassasiyet |
vid_stride | int | 1 | ≥ 1 | Videonun her N'inci karesinde tahmin yap; görüntülerde bu parametre yok sayılır |
bits | int | 8 | 8, 12, 16 | Derinlik haritası niceleme; yalnızca derinlik modelleri için |
source | string | - | - | Görüntü URL'si veya base64 dizesi (file yerine kullanılabilir); Platform API'si üzerinden en fazla 4.096 karakter |
Metrikleri al#
GET /api/deployments/{owner}/{deployment}/metricsPython SDK: client.deployments.metrics(owner, deployment)
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
range | string | 1h, 6h, 24h (varsayılan), 7d veya 30d |
sparkline | boolean | Tam seriler yerine kompakt kontrol paneli özetini döndür (varsayılan: false) |
view | string | overview yalnızca istek, hata ve P95 gecikme metriklerini döndürür |
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}/logsPython SDK: client.deployments.logs(owner, deployment)
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
severity | string | Virgülle ayrılmış: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY |
limit | int | Döndürülecek kayıt sayısı (varsayılan: 50, en fazla: 200) |
pageToken | string | Önceki bir yanıttan alınan sayfalama belirteci |
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/workflowsPython SDK: client.agents.list()
| Parametre | Tür | Açıklama |
|---|---|---|
owner | string | Çalışma alanı kullanıcı adı (varsayılan: kendi kullanıcı adın) |
id | string | Bir agent'ı graph ile döndür |
search | string | Agent adına göre filtrele |
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/workflowsPython 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/trashPython SDK: client.lifecycle.trash()
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
type | string | all (varsayılan), project, dataset veya model |
page | int | Sayfa numarası (varsayılan: 1) |
limit | int | Sayfa başına öğe sayısı (varsayılan: 50, en fazla: 200) |
id | string | type ile project veya model göndererek, silme işleminden etkilenecek modelleri ve dağıtımları önizle |
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/trashPython 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/trashPython 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.
Kalıcı silme işlemi geri alınamaz. Kaynak ve ilişkili tüm veriler kaldırılır.
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-urlPython SDK: client.upload.signed_url(body=...)
Gövde:
{
"assetType": "datasets",
"assetId": "65f1c0a2b3d4e5f601234567",
"filename": "warehouse.zip",
"contentType": "application/zip",
"totalBytes": 52428800
}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
assetType | string | Evet | datasets veya models |
assetId | string | Evet | Hedef veri kümesinin veya modelin kimliği |
filename | string | Evet | Özgün dosya adı (en fazla 256 karakter) |
contentType | string | Evet | MIME türü |
totalBytes | sayı | Evet | Bayt cinsinden dosya boyutu |
assetType, datasets olduğunda filename, .zip, .tar, .tar.gz, .tgz veya .ndjson ile bitmelidir. Tek tek görüntüleri yüklemeden önce bir arşive paketle.
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/completePython 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#
Google Cloud Storage, Amazon S3 veya Azure Blob Storage hesaplarını bağla, veri kümesi kaynakları olarak görüntüle ve AI özelliklerini açıp kapat. 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/bucketsPython SDK: client.storage_integrations.list()
Her biri id, provider, credentialIdentity, targets, processing (AI özelliklerinin açık olup olmadığı) ve createdAt içeren integrations değerini döndürür. Kimlik bilgileri hiçbir zaman döndürülmez.
Konumları keşfet#
POST /api/integrations/buckets/discoverPython 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/bucketsPython SDK: client.storage_integrations.create(body=...)
Keşif uç noktasıyla aynı kimlik bilgisi biçimleri ve ayrıca 1–50 bucket veya kapsayıcı adından oluşması gereken targets dizisi. Saklanan entegrasyonu içeren 201 değerini döndürür. Bağlantı kurma işlemi, herhangi bir şey yazmadan her hedefin yazma erişimini kontrol eder. Geçici S3 kimlik bilgileri (ASIA erişim anahtarları) reddedilir.
Nesnelere göz at#
GET /api/integrations/buckets/{id}/objectsPython SDK: client.storage_integrations.objects(id, target=...)
Sorgu Parametreleri:
| Parametre | Tür | Zorunlu | Açıklama |
|---|---|---|---|
target | string | Evet | Paket veya kapsayıcı adı |
prefix | string | Hayır | Klasör öneki (en fazla 1024 karakter) |
cursor | string | Hayır | Önceki sayfadan sağlayıcı sayfalama imleci |
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.
AI Özelliklerini Ayarla#
PATCH /api/integrations/buckets/{id}Python SDK: client.storage_integrations.update(id, processing=False)
Entegrasyonun tüm hedefleri için AI özelliklerini açar ({"processing": true}) veya kapatır ve güncellenen entegrasyonu döndürür. Özellikleri kapatmak yeni işleri durdurur. Çalışma alanı yöneticisi erişimi gerekir.
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 ve Label Studio entegrasyonlarına bak.
Roboflow İçe Aktarmasını Önizle#
POST /api/integrations/roboflow/previewPython 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, en son sürümü zaten içe aktarılmış olan importedDatasets, zaten içe aktarılmış (skippedCount), sürümü olmayan, desteklenmeyen ve çözümlenemeyen projelerin sayıları, bytesTotal ve kullanılabilir storage kapasiten. Yeni veri kümeleri, dışa aktarma sizeBytes değerini içerir; zaten içe aktarılmış veri kümeleri ise dışa aktarma boyutu hâlâ hesaplanabiliyorsa bu değeri içerir. apiKey isteğe bağlıdır: belirtilmezse çalışma alanında kayıtlı Roboflow anahtarı kullanılır; ikisi de yoksa istek 400 döndürür. Çalışma alanı sahibinin gönderdiği anahtar, Roboflow çalışma alanı çözümlendiğinde çalışma alanı için kaydedilir.
{
"apiKey": "ROBOFLOW_API_KEY"
}Roboflow'dan içe aktar#
POST /api/integrations/roboflow/importPython SDK: client.datasets.import_roboflow(api_key=..., items=...)
Önizlemenin döndürdüğü öğeleri kullanarak seçilen en fazla 500 Roboflow proje sürümü için alım işleri kuyruğa ekler. apiKey isteğe bağlıdır ve önizlemede olduğu gibi kayıtlı anahtara geri döner, ancak hiçbir zaman kaydedilmez.
{
"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.
Label Studio İçe Aktarımını Önizle#
POST /api/integrations/label-studio/previewPython SDK: client.datasets.preview_label_studio(api_key=...)
Bağlı barındırılan Label Studio hesabındaki projeleri içe aktarma planı olarak listeler: newDatasets ve importedDatasets (her biri için projectId, projectName, öngörülen task ve imageCount), etiketleme kurulumu içe aktarılamayan projeler için unsupportedCount ve senin storage. apiKey, isteğe bağlı bir Label Studio kişisel erişim belirteci veya eski belirteçtir: bu olmadan çalışma alanında kayıtlı belirteç kullanılır; ikisi de yoksa istek 409 döndürür. Belirteci yalnızca çalışma alanı sahibi gönderebilir; projeler listelendiğinde belirteç çalışma alanı için kaydedilir. Başka biri belirteç gönderirse 403 alır.
{
"apiKey": "LABEL_STUDIO_ACCESS_TOKEN"
}Label Studio'dan içe aktar#
POST /api/integrations/label-studio/importPython SDK: client.datasets.import_label_studio(project_ids=...)
Çalışma alanında kayıtlı belirteci kullanarak 500'e kadar Label Studio proje kimliğinin her biri için bir veri kümesi içe aktarma işlemi kuyruğa alır. Görev, her projenin etiketleme yapılandırmasından yeniden okunur; bu nedenle istekte seçilemez.
{
"projectIds": [101, 102]
}Yanıt (201): imported, failed ve skipped dizileri. İçe aktarma için depolama alanı gerekir; her projeye bu alanın eşit bir payı verilir ve bu pay planının içe aktarma başına boyut sınırını aşamaz.
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/summaryPython 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": []
}Kişisel hesaplarda teams, üyesi olduğun ekip çalışma alanlarını listeler. Her çalışma alanıyla birlikte role ve planının süresinin dolması gibi nedenlerle çalışma alanına şu anda erişilemiyorsa deniedReason döndürülür. Ekip çalışma alanları boş bir liste döndürür.
API Anahtarlarını Listele#
GET /api/api-keysPython 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/storagePython SDK: client.account.storage()
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
details | boolean | En fazla depolama alanı kullanan on kaydı dahil et (varsayılan: false) |
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/usersPython SDK: client.account.profile(username=...)
Sorgu Parametreleri:
| Parametre | Tür | Zorunlu | Açıklama |
|---|---|---|---|
username | string | Evet | Aranacak kullanıcı adı |
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/usersPython 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.
Faturalandırma tutarları ABD senti cinsinden tam sayılardır; burada 100 = $1.00.
Planı ve Kullanımı Görüntüle#
GET /api/billing/usage-summaryPython 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/transactionsPython SDK: client.billing.transactions()
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
from | string | En eski işlem zaman damgası (ISO 8601) |
to | string | En yeni işlem zaman damgası (ISO 8601) |
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#
Topluluğun paylaştığı herkese açık projeleri, veri kümelerini ve modelleri ara ya da görsellerde neler olduğunu veya bir fotoğrafı ara. Keşfet belgelerine göz at.
Herkese Açık İçeriği Ara#
GET /api/explore/searchPython SDK: client.explore.search()
Sorgu Parametreleri:
| Parametre | Tür | Açıklama |
|---|---|---|
q | string | Arama terimi (en fazla 200 karakter); veri kümeleri ve modellerde önce metin eşleşmeleri, ardından görselleri eşleşen veri kümeleri (veya bunlarda eğitilmiş modeller) gösterilir |
type | string | all (varsayılan; projeler ve veri kümeleri), projects, datasets, models veya images (sort yok sayılır) |
sort | string | relevance (varsayılan), newest, oldest, stars, name-asc, name-desc, count-desc, count-asc; relevance, q için veri kümesi ve model eşleşmelerini sıralar, aksi durumda en yeniden eskiye doğru sıralar |
offset | int | Atlanacak sonuç sayısı (varsayılan: 0) |
limit | int | Kaynak türü başına en fazla sonuç sayısı (varsayılan: 20, en fazla: 100) |
task | string | Virgülle ayrılmış görev filtreleri: detect, segment, semantic, depth, classify, pose, obb |
license | string | Virgülle ayrılmış lisans tanımlayıcıları; örneğin CC-BY-4.0,MIT; görüntüler, ait oldukları veri kümesinin lisansıyla eşleşir. |
author | string | Sahibin kullanıcı adına göre filtrele |
starred | boolean | Yalnızca kimliği doğrulanmış kullanıcının yıldızladığı içeriği döndürür; API anahtarı gerektirir |
minImages | int | Yalnızca en az bu sayıda görsel içeren veri kümelerini döndür; type=images kullanıldığında yalnızca bu tür veri kümelerindeki görselleri döndür |
maxImages | int | Yalnızca en fazla bu sayıda görsel içeren veri kümelerini döndür; type=images kullanıldığında yalnızca bu tür veri kümelerindeki görselleri döndür |
Yanıt: projects, datasets ve hasMore. type=images, eşleşmelerini bunun yerine images içinde döndürür; en iyi eşleşme ilk sıradadır ve her eşleşmede kaynak dataset ile 0–1 aralığında bir benzerlik score bulunur. q ile herkese açık veri kümelerinde; API anahtarı gönderdiğinde kendi veri kümelerinde ve ekip veri kümelerinde de arama yapar. q olmadan, filtreleri uygulayarak en yeni herkese açık veri kümelerinin her birinden score 1 ile sıralanmamış bir görüntü listeler.
type=models, models içinde herkese açık modelleri listeler; resmî @ultralytics modelleri hariç, eğitim veri kümesi başına (eğitim veri kümesi olmayanlarda proje başına) bir model listelenir ve resmî modellerin her biri kendi girdisini korur; klonlar ve eğitimi henüz tamamlanmamış modeller listelenmez. q ile önce eşleşen resmî modeller, sonra adı veya projesi eşleşen modeller, ardından görselleri en iyi eşleşen herkese açık veri kümelerinde eğitilmiş modeller gösterilir. q olmadan, herkese açık veri kümelerinde eğitilmiş modeller en yeniden eskiye doğru listelenir. task ve author dikkate alınır; relevance, newest veya oldest ile sıralama yapılır; diğer sıralama seçeneklerinde en yeni modeller önce listelenir.
curl "https://platform.ultralytics.com/api/explore/search?type=datasets&task=detect&sort=stars&limit=20"Görselle Ara#
POST /api/explore/searchPython SDK: client.explore.search_by_image() (ultralytics-platform>=0.1.107)
Herkese Açık İçeriği Ara üzerinden bir fotoğrafı base64 image olarak (en fazla 3 MiB, hiçbir zaman saklanmaz), type gövdesi içindeki bir JSON gövdesinde images (varsayılan), datasets veya models ve sort, offset, limit, task, license, author, starred, minImages ve maxImages seçeneklerinden herhangi biriyle gönder. Yanıt aynı yapıya sahiptir; image gönderen bir istek ayrıca vector döndürür: daha fazla sayfa, başka filtreler veya başka bir type için image yerine bunu gönder; böylece fotoğraf yalnızca bir kez okunur. type=images, metin aramasında olduğu gibi puanlanmış görselleri döndürür; type=datasets, varsayılan sort=relevance sıralamasında en iyi eşleşmeler önce olacak şekilde, eşleşen görselleri içeren herkese açık veri kümelerini döndürür (diğer sıralama seçeneklerinde olağan şekilde sıralanırlar) ve bu görseller her veri kümesinin sampleImages bölümünde öne çıkar; type=models, bu veri kümelerinde eğitilmiş herkese açık modelleri en iyi eşleşmeler önce olacak şekilde döndürür. image gönderen her istek, kullanıcı başına (API anahtarı olmadan IP adresi başına) dakikada 20 istek olan ayrı bir sınıra da dahildir. 400, geçersiz parametreler veya okunamayan bir fotoğraf anlamına gelir; 503 ise aramanın meşgul olduğu anlamına gelir, bu durumda kısa süre sonra yeniden dene.
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 checkKimlik Doğrulama#
yolo login YOUR_API_KEYPlatform 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:
| Kalıp | Açıklama |
|---|---|
ul://username/datasets/slug | Veri kümesi |
ul://username/project/model-name | Belirli model |
ul://ultralytics/yolo26/yolo26n | Resmî model |
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 kullanDoğ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#
Platform URL'sinde görünen sahip ve ad bölümlerini kullan.
https://platform.ultralytics.com/acme-vision/inspection/v3adresindeki bir model,GET /api/models/acme-vision/inspection/v3olarak gösterilir. Veritabanı kimlikleri yanıtlarda (idolarak) yine döndürülür ve bazı rotalar bu kimlikleri doğrudan alır — görüntü rotaları birimageId, yüklemeler birassetId,POST /api/training/startise birmodelIdalır.Koleksiyona göre değişir. Liste uç noktalarının çoğu
limitkabul eder:curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://platform.ultralytics.com/api/datasets/acme-vision?limit=50"Veri kümesi görüntüleri, kümeleme ve Keşfet araması
offsetdeğerinilimitile birlikte kullanır vehasMoredeğerini bildirir:curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&limit=20&sort=stars"Çok büyük görüntü kümelerinde,
nextCursorolarak döndürülen imleçle ilerlemek en iyisidir:curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://platform.ultralytics.com/api/datasets/acme-vision/warehouse/images?limit=1000&includeTotal=false&cursor=NEXT_CURSOR"Çöp kutusu
pagekullanır; dağıtım günlükleri isenextPageTokenolarak döndürülen opakpageTokendeğerini kullanır.Evet. Bu sayfadaki her işlem basit bir HTTPS isteğidir ve sözleşmenin tamamı OpenAPI 3.2 biçiminde platform.ultralytics.com/openapi.json adresinde yayımlanmıştır; bu sözleşmeyi herhangi bir dildeki istemci oluşturucusuna verebilirsin.
ultralytics-platformpaketi tam olarak bunu yapar: sözleşmeden oluşturulmuş tür tanımlı bir istemcidir.ultralyticspaketi ise eğitim ve çıkarım sırasında gerçek zamanlı metrik akışı ve otomatik model yükleme özellikleri ekler. Faturalandırma ödemesi ve ekip yönetimi gibi yalnızca tarayıcı oturumuyla kullanılabilen hesap işlemleri Platform arayüzünde kalır.Doğru süre kadar beklemek için
429yanıtındakiRetry-Afterüstbilgisini kullan:import time import requests def api_request_with_retry(url, headers, max_retries=3): for attempt in range(max_retries): response = requests.get(url, headers=headers) if response.status_code != 429: return response wait = int(response.headers.get("Retry-After", 2**attempt)) time.sleep(wait) raise RuntimeError("Rate limit exceeded")404, kaynağın mevcut olmadığı veya anahtarın tarafından hiçbir şekilde görüntülenemediği anlamına gelir.403, kaynağın bulunduğu ancak eylemin anahtarının sağladığından daha fazla erişim gerektirdiği anlamına gelir — bir veri kümesini değiştirmek için düzenleyici erişimi, bir dağıtımı silmek için sahip erişimi, depolama bağlantısını kesmek için yönetici erişimi ya da dışa aktarma ve dağıtımlar için daha üst bir plan veya kota.Herkese açık veri kümelerini, projeleri ve modelleri; bunların görsellerini, imzalı görsel URL'lerini, sınıf istatistiklerini, gömme durumunu, kümeleme düzenini, bir veri kümesi üzerinde eğitilmiş modelleri ve dışa aktarma listesini okuma; herkese açık bir modelin eğitim ilerlemesini kontrol etme; herkese açık bir modelin dosyalarını indirme; herkese açık bir modelin dışa aktarımı için mobil içe aktarma bağlantısı oluşturma; herkese açık bir modelde çıkarım çalıştırma; herkese açık bir kullanıcı profilini arama; tek bir herkese açık modele göre filtrelenmiş dağıtımları listeleme ve Explore'da arama. Yönetilen kapasite talep etmediğin sürece
GET /api/training/gpu-availabilityherkese açıktır. Diğer tüm işlemler için bir anahtar gerekir; herkese açık bir uç noktada anahtar kullanman özel kaynaklarını da görünür kılar.
Yorumlar
Bir soru sor, sonuçlarını paylaş veya başka birine yardım et.