REST API Referansı#

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

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

API Genel Bakış#

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

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

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

Kimlik Doğrulama#

Kaynak API'leri, veri kümesi sınıfı ve bölme yönetimi, kopyalama, eğitim, dışa aktarma, dağıtımlar ve desteklenen hesap okumaları dahil olmak üzere API anahtarı kimlik doğrulaması kullanır. Halka açık uç noktalar, belirtilen durumlarda anonim erişimi destekler. Yalnızca tarayıcıya özel uygulama yolları hariç tutulmuştur.

API Anahtarı Al#

1. Settings > API Keys bölümüne git
2. Create Key öğesine tıkla
3. Oluşturulan anahtarı kopyala

Ayrıntılı talimatlar için API Keys sayfasına bak.

Yetkilendirme Başlığı#

API anahtarını tüm isteklerine dahil et:

Authorization: Bearer YOUR_API_KEY

Örnek#

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

Temel URL#

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

https://platform.ultralytics.com/api

Hız Sınırları#

API, her API anahtarı için Upstash Redis destekli kayan pencere sınırları uygular. Her rota aşağıdaki eşleşen kategoriyi kullanır.

İstekler kısıtlandığında (throttled), API yeniden deneme meta verileriyle birlikte 429 döndürür:

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

API Anahtarı Başına Sınırlar#

Hız sınırları, çağrılan uç noktaya bağlı olarak otomatik uygulanır. Maliyetli işlemler, kötüye kullanımı önlemek için daha sıkı sınırlara sahiptir, standart CRUD işlemleri ise cömert bir varsayılan paylaşır:

Her kategorinin API anahtarı başına bağımsız bir sayacı vardır. Örneğin, 20 tahmin isteği yapmak, 100 istek/dk varsayılan hakkını etkilemez.

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

Dedicated endpoints, uç nokta URL'sini doğrudan çağırarak (https://predict-abc123.run.app/predict örneğinde olduğu gibi) Platform API anahtarı oran sınırlarına tabi değildir. İş hacmi o zaman dağıtılan servis yapılandırmasına bağlıdır.

Yanıt Formatı#

Başarılı Yanıtlar#

Yanıtlar, kaynağa özel alanlar içeren JSON döner:

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

Hata Yanıtları#

{
    "error": "Dataset not found"
}

Veri Kümeleri API'si#

YOLO modellerini eğitmek için etiketlenmiş görüntü veri setleri oluştur, bunlara göz at ve bunları yönet. Datasets documentation sayfasına bak.

Veri Kümelerini Listele#

GET /api/datasets

Sorgu Parametreleri:

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

Yanıt:

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

Veri Kümesini Getir#

GET /api/datasets/{datasetId}

Sınıf adları, bölünme sayıları ve diğer Platform tarafından yönetilen özellikler dahil olmak üzere veri kümesi ayrıntılarını döndürür. Özel meta veriler, aşağıdaki meta veri uç noktasından ayrı olarak yüklenir.

{datasetId}, bir ID yerine bir veri kümesi kısaltması (slug) olduğunda username değerini geçir.

Veri Kümesi Oluştur#

POST /api/datasets

Gövde:

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

Yanıt:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

Veri Kümesini Güncelle#

PATCH /api/datasets/{datasetId}

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

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

Özel meta verileri temizlemek için boş bir metadata nesnesi ({}) gönder. Serileştirilmiş meta veri nesnesi 500.000 karakterle sınırlıdır ve her üst düzey anahtar 128 karakterle sınırlıdır.

Veri Kümesi Meta Verilerini Al#

GET /api/datasets/{datasetId}/metadata

Özel meta veri nesnesini ve Ultralytics tarafından yönetilen, salt okunur alan/değer çiftlerinden oluşan derlenmiş bir seti döndürür. Özel meta veriler, normal veri kümesi yüklerinden kasıtlı olarak hariç tutulmuştur. Kimlik doğrulama ve veri kümesi çalışma alanı erişimi gereklidir.

Veri Kümesi Simgesi#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

Çok parçalı (multipart) form alanı image olarak 5 MB'a kadar bir WebP simgesi yükle veya mevcut simgeyi kaldır.

Veri Kümesini Sil#

DELETE /api/datasets/{datasetId}

Veri setini yumuşak silme (soft-delete) ile sil (trash bölümüne taşınır, 30 gün boyunca kurtarılabilir).

Veri Kümesini Kopyala#

POST /api/datasets/{datasetId}/clone

Tüm görseller ve etiketlerle birlikte halka açık, sahip olunan veya düzenlenebilir bir çalışma alanı veri kümesinin kopyasını oluşturur.

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

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

Veri Kümesini Dışa Aktar#

GET /api/datasets/{datasetId}/export

En son veri kümesi dışa aktarımı için imzalı bir indirme URL'si içeren bir JSON yanıtı döndürür.

Sorgu Parametreleri:

Yanıt:

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

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

POST /api/datasets/{datasetId}/export

Veri setinin numaralandırılmış yeni bir sürüm anlık görüntüsünü (snapshot) oluştur. Bu işlem, Editör erişimi veya daha yüksek bir yetki gerektirir. Sürüm; mevcut görüntü sayısını, sınıf sayısını, etiket sayısını ve bölünme (split) dağılımını yakalar, ardından değiştirilemez bir NDJSON dışa aktarması oluşturup saklar.

İstek Gövdesi:

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

Tüm alanlar isteğe bağlıdır. description alanı, kullanıcı tarafından sağlanan bir sürüm etiketidir.

Yanıt:

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

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

PATCH /api/datasets/{datasetId}/export

Mevcut bir sürümün açıklamasını güncelle. Bu, Editör erişimi veya daha yüksek bir yetki gerektirir.

İstek Gövdesi:

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

Yanıt:

{
    "ok": true
}

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

POST /api/datasets/{datasetId}/restore

Veri kümesinin görsellerini, açıklamalarını ve sınıflarını, görsel baytlarını kopyalamadan kaydedilmiş bir sürümden yeniden oluştur.

{
    "version": 2
}

Sınıf İstatistiklerini Getir#

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

Sınıf dağılımını, konum ısı haritasını ve boyut istatistiklerini döndürür. Sonuçlar 5 dakikaya kadar önbelleğe alınır.

Yanıt:

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

Sınıfları Yönet#

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

POST /api/datasets/{datasetId}/classes/merge

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

Sınıf kimlikleri konumsaldır, bu nedenle birleştirme işlemi idempotent değildir. Tekrar denemeden önce veri kümesini yeniden getir.

Sınıfları sil:

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

Bölümleri Yeniden Dağıt#

POST /api/datasets/{datasetId}/splits/redistribute

Görselleri eğitim, doğrulama ve test bölmeleri arasında rastgele olarak yeniden ata. Yüzdelerin toplamı 100 olmalıdır.

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

Veri Kümesi Gömülüleri (Embeddings)#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET, mevcut UMAP analiz özetini ve aktif iş durumunu döndürür; POST bir gömülü analiz işini sıraya alır; DELETE aktif işi iptal eder.

Görüntü Kümeleme#

GET /api/datasets/{datasetId}/images/clustering

Kümeleme dağılım görünümü için UMAP 2D düzenini ve görüntü başına meta verileri döndürür (sayfalandırılmış ve hız sınırlamalı).

Veri Kümesinde Eğitilen Modelleri Getir#

GET /api/datasets/{datasetId}/models

Bu veri kümesi kullanılarak eğitilen modelleri döndürür.

Yanıt:

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

Veri Kümesini Otomatik Etiketle#

POST /api/datasets/{datasetId}/predict

Açıklamaları otomatik olarak oluşturmak için veri kümesi görüntülerinde YOLO çıkarımı çalıştır. Etiketlenmemiş görüntüler için etiketleri tahmin etmek üzere seçili bir model kullanır.

Gövde:

Veri Kümesi Alımı#

POST /api/datasets/ingest

Mevcut bir veri seti için veri seti içe aktarma (ingest) işi oluştur. Hedef veri seti, URL yolunda değil, her zaman JSON gövdesinde datasetId olarak iletilir.

İstek gövdesi, datasetId ile birlikte sessionId (yüklenmiş bir arşivin yükleme oturumu) veya sourceUrl (uzak bir ZIP, TAR, TAR.GZ, TGZ veya NDJSON URL'si) değerlerinden tam olarak birini gerektirir. Arşivin bölme yapısını geçersiz kılmak için isteğe bağlı targetSplit (train, val veya test) ekle. Özel meta veriler eklemek için her görselin arşiv içindeki tam göreli yolu veya NDJSON file değeriyle anahtarlanmış imageMetadata kullan.

Yüklenen arşivler için yükleme oturumu, POST /api/upload/signed-url değerine geçirilen assetId ile veri kümesine zaten bağlanmıştır; veri alımı (ingest), assetId değerinin gövdeyle (datasetId) eşleştiğini doğrular. İsteğe bağlı classMapping girdileri, gelen her sınıf adını mevcut sıfır tabanlı bir sınıf indeksine, yeniden kullanılacak veya oluşturulacak bir sınıf adına ya da sınıfı atlamak için null değerine eşler. Uzak sourceUrl içe aktarımları için önce veri kümesini oluştur, ardından veri alımı için datasetId değerini geçir.

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

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

Gövde (meta verilerle birlikte bir veya birden fazla görsel):

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

Yerel görseller, arşivin tek bir görsel veya çok sayıda görsel içermesinden bağımsız olarak mevcut arşiv yükleme akışını kullanır. Anahtar, klasörler dahil olmak üzere arşiv içindeki normalleştirilmiş yol ile eşleşmelidir. NDJSON içeri aktarımları için her görsel kaydı bunun yerine kendi metadata nesnesini içerebilir. Kayda özel metadata, eşleşen bir imageMetadata girdisine göre önceliğe sahiptir.

Meta veriler JSON formatındadır ve iç içe değerleri destekler. Arşiv yolları 1.024 karakterle, üst düzey meta veri anahtarları 128 karakterle ve her meta veri nesnesi 500.000 serileştirilmiş karakterle sınırlıdır. Eksiksiz imageMetadata eşlemesi veya bir NDJSON içeri aktarımındaki birleştirilmiş geçerli meta veriler de 500.000 serileştirilmiş karakterle sınırlıdır. Bu kısıtlamalar etkileşimli OpenAPI şemasında yer almaktadır.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

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

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

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

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

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

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

Gövde (daha sonraki veri girişi, etiketlerin içe aktarılması):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

Yanıt:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

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

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

Veri Kümesi Görüntüleri#

Görüntüleri Listele#

GET /api/datasets/{datasetId}/images

Sorgu Parametreleri:

Seçili Görselleri Getir#

POST /api/datasets/{datasetId}/images

Sağlanan 1.000 görsel kimliğine kadar aynı görsel şeklini döndürür. Liste işlemiyle aynı URL ve etiket sorgu kontrollerini kabul eder.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

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

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

(Tarayıcıda görüntülemek için) bir dizi görüntü karması için imzalı URL'leri al.

Görüntüyü Sil#

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

Görüntü Etiketlerini Getir#

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

Belirli bir görüntü için açıklamaları ve sınıf adlarını döndürür.

Görüntü Etiketlerini Güncelle#

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

Gövde:

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

Toplu Görüntü İşlemleri#

Görüntüleri bir veri kümesi içindeki bölmeler (train/val/test) arasında taşı:

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

Görüntüleri toplu sil:

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

Projeler API'si#

Modellerini projeler altında organize et. Her model bir projeye aittir. Projects documentation sayfasına bak.

Projeleri Listele#

GET /api/projects

Sorgu Parametreleri:

Projeyi Getir#

GET /api/projects/{projectId}

Proje Oluştur#

POST /api/projects

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

Projeyi Güncelle#

PATCH /api/projects/{projectId}

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

{
    "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 üst düzey anahtar ve 500.000 karakterlik serileştirilmiş nesne sınırlarını kullanır.

Proje Meta Verilerini Al#

GET /api/projects/{projectId}/metadata

Özel meta veri nesnesini ve Ultralytics tarafından yönetilen salt okunur alan/değer çiftlerini döndürür. Kimlik doğrulama ve proje çalışma alanı erişimi gereklidir.

Projeyi Sil#

DELETE /api/projects/{projectId}

Projeyi yumuşak silme (soft-delete) ile sil (trash bölümüne taşınır).

Projeyi Kopyala#

POST /api/projects/{projectId}/clone

Herkese açık, sahip olduğun veya düzenlenebilir bir çalışma alanı projesini ve modellerini hesabına veya çalışma alanına klonlar. İsteğe bağlı bir JSON gövdesi name, slug, description, visibility, license ve hedef owner geçersiz kılmalarını kabul eder.

Proje Simgesi#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

Çok parçalı (multipart) form alanı image olarak 5 MB'a kadar bir WebP simgesi yükle veya mevcut simgeyi kaldır.

Modeller API'si#

Eitilmiş YOLO modellerini yönet — metrikleri görüntüle, ağırlıkları indir, çıkarım çalıştır ve diğer formatlara dışarı aktar. Models documentation sayfasına bak.

Modelleri Listele#

GET /api/models

Sorgu Parametreleri:

Tamamlanan Modelleri Listele#

GET /api/models/completed

Eğitim ve dağıtım için tüm projelerde kullanılabilir ağırlıklara sahip en fazla 1.000 model döndürür. Çalışma alanı için owner değerini ilet.

Modeli Getir#

GET /api/models/{modelId}

Model Oluştur#

POST /api/models

JSON Gövdesi:

Modeli Güncelle#

PATCH /api/models/{modelId}

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

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

Temizlemek için boş bir metadata nesnesi ({}) gönder. Model özel meta verileri, eğitime ait model bilgilerinden, ortam ayrıntılarından ve eğitim argümanlarından ayrıdır ve veri kümesi meta verileriyle aynı serileştirilmiş nesne ve üst düzey anahtar sınırlarını kullanır.

Model Meta Verilerini Al#

GET /api/models/{modelId}/metadata

Özel meta veri nesnesini ve Ultralytics tarafından yönetilen salt okunur alan/değer çiftlerini döndürür. Kimlik doğrulama ve model çalışma alanı erişimi gereklidir.

Modeli Sil#

DELETE /api/models/{modelId}

Model Dosyalarını İndir#

GET /api/models/{modelId}/files

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

Modeli Kopyala#

POST /api/models/{modelId}/clone

Halka açık, sahip olunan veya düzenlenebilir bir çalışma alanı modelini projelerinden birine kopyala.

Gövde:

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

İndirmeyi İzle#

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

Model indirme analizlerini izle.

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

POST /api/models/{modelId}/predict

Halka açık modeller, kimlik doğrulaması olmadan tahmin edilebilir. Özel ve paylaşılan modeller, üst projeye erişimi olan bir API anahtarı gerektirir.

Çok Parçalı Form:

file veya source değerinden birini sağla. Maksimum yükleme boyutu 100 MB'tır.

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

Yanıt:

Yanıtlar, görsel başına shape, speed, results ve isteğe bağlı yoğun piksel haritası verilerini (bir anlamsal sınıf haritası veya depth = pixel × max / divisor içeren bir derinlik haritası — varsayılan 8 bitlik harita için 255 böleni, bits=12|16 ile 65535) artı görsel sayısı, işlev zamanlaması, görev ve servis sürümlerini içeren metadata değerini içerir. Dahili model yolları asla döndürülmez.

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

Eğitim API'si#

Bulut GPU'larında (RTX 2000 Ada'dan B300'e kadar 26 GPU türü) YOLO eğitimini başlat ve ilerlemeyi gerçek zamanlı olarak izle. Cloud Training documentation sayfasına bak.

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

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

Eğitimi Başlat#

POST /api/training/start

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

GPU Uygunluğunu Getir#

GET /api/training/gpu-availability

GPU türü kimliğine göre anahtarlanmış mevcut GPU stok durumunu (High, Medium, Low veya null) döndürür. Herkese açık, kimlik doğrulama gerektirmez; 5 dakika boyunca önbelleğe alınır.

Eğitim Durumunu Al#

GET /api/models/{modelId}/training

Mevcut eğitim işi durumunu, metrikleri, ilerlemeyi, zamanlamayı, GPU detaylarını ve hataları döndürür. Halka açık projeler kimlik doğrulaması olmadan erişilebilirdir; özel ve paylaşılan projeler, erişimi olan bir API anahtarı gerektirir.

Eğitimi İptal Et#

DELETE /api/models/{modelId}/training

Çalışan işlem örneğini sonlandırır ve işi iptal edildi olarak işaretler.

Dağıtım API'si#

Modelleri sağlık kontrolleri ve izleme özellikleriyle özel çıkarım uç noktalarına dağıt. Yeni dağıtımlar varsayılan olarak sıfıra ölçekleme (scale-to-zero) kullanır ve API isteğe bağlı bir resources nesnesini kabul eder. Endpoints documentation sayfasına bak.

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

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

Dağıtımları Listele#

GET /api/deployments

Sorgu Parametreleri:

Dağıtım Oluştur#

POST /api/deployments

Gövde:

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

Belirtilen bölgede özel bir çıkarım uç noktası oluşturur. Uç nokta benzersiz bir URL aracılığıyla küresel olarak erişilebilirdir.

Dağıtımı Getir#

GET /api/deployments/{deploymentId}

Dağıtımı Sil#

DELETE /api/deployments/{deploymentId}

Dağıtımı Başlat#

POST /api/deployments/{deploymentId}/start

Durdurulmuş bir dağıtımı devam ettir.

Dağıtımı Durdur#

POST /api/deployments/{deploymentId}/stop

Servisin minimum ve maksimum örnek sayısını sıfıra ayarlayarak istek sunmayı durdur.

Sağlık Kontrolü#

GET /api/deployments/{deploymentId}/health

Dağıtım uç noktasının sağlık durumunu döndürür.

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

POST /api/deployments/{deploymentId}/predict

Çıkarım için bir görüntüyü doğrudan dağıtım uç noktasına gönder. İşlevsel olarak model tahminiyle eşdeğerdir ancak daha düşük gecikme için özel uç nokta üzerinden yönlendirilir.

Çok Parçalı Form:

file veya source değerinden birini sağla. Yanıt, model tahminiyle aynı görüntü ve meta veri sözleşmesini kullanır ve dahili model yolunu asla döndürmez.

Metrikleri Getir#

GET /api/deployments/{deploymentId}/metrics

İstek sayılarını, gecikmeyi ve hata oranı metriklerini kıvılcım grafiği verileriyle döndürür.

Sorgu Parametreleri:

Günlükleri Getir#

GET /api/deployments/{deploymentId}/logs

Sorgu Parametreleri:

Dışa Aktarma (Export) API#

Kenar (edge) cihazda dağıtım için modelleri ONNX, TensorRT, CoreML ve LiteRT gibi optimize edilmiş formatlara dönüştür. Deploy documentation sayfasına bak.

Dışa Aktarımları Listele#

GET /api/exports

Sorgu Parametreleri:

Dışa Aktarma Oluştur#

POST /api/exports

Gövde:

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

Desteklenen Formatlar:

Aşağıdaki paylaşılan dışa aktarma tablosundan format argümanını kullan. PyTorch kaynak formattır ve bir API dışa aktarma hedefi değildir.

Dışa Aktarma Durumunu Al#

GET /api/exports/{exportId}

Dışa Aktarmayı İptal Et#

DELETE /api/exports/{exportId}

Dışa Aktarma İndirmesini İzle#

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

Etkinlik (Activity) API#

Hesabındaki son eylemlerin (eğitim çalıştırmaları, yüklemeler ve daha fazlası) akışını görüntüle. Activity documentation sayfasına bak.

Etkinlikleri Listele#

GET /api/activity

Sorgu Parametreleri:

Etkinlikleri Görüldü Olarak İşaretle#

POST /api/activity/mark-seen

Gövde:

{
    "all": true
}

Veya belirli kimlikleri ilet:

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

Bir çalışma alanındaki etkinlikleri işaretlemek için isteğe bağlı owner sorgu parametresini ilet.

Etkinlikleri Arşivle#

POST /api/activity/archive

Gövde:

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

Veya belirli kimlikleri ilet:

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

Çalışma alanı etkinliklerini arşivlemek veya geri yüklemek için isteğe bağlı owner sorgu parametresini ilet.

Çöp Kutusu (Trash) API#

Silinen öğeleri görüntüle ve geri yükle. Öğeler 30 gün sonra kalıcı olarak kaldırılır. Trash documentation sayfasına bak.

Çöp Kutusunu Listele#

GET /api/trash

Sorgu Parametreleri:

Öğeyi Geri Yükle#

POST /api/trash

Gövde:

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

Öğeyi Kalıcı Olarak Sil#

DELETE /api/trash

Gövde:

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

Çöp Kutusunu Boşalt#

DELETE /api/trash/empty

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

Faturalandırma API#

Kredi bakiyeni, plan kullanımını ve işlem geçmişini kontrol et. Billing documentation sayfasına bak.

Bakiye ve işlem uç noktaları, çalışma alanı sahibinin kullanıcı adını içeren isteğe bağlı bir owner sorgu parametresini kabul eder.

Bakiyeyi Al#

GET /api/billing/balance

Yanıt:

{
    "creditsCents": 2500,
    "plan": "free"
}

Kullanım Özetini Al#

GET /api/billing/usage-summary

Plan detaylarını, limitleri ve kullanım metriklerini döndürür.

İşlemleri Al#

GET /api/billing/transactions

İşlem geçmişini döndürür (en son işlem önce gelecek şekilde).

İşlemler, tutar, sonuç bakiyesi, tarih, isteğe bağlı model bağlamı ve makbuz URL'si gibi müşteri tarafındaki defter alanlarını içerir. Dahili notlar, Stripe ödeme/iade kimlikleri ve idempotent anahtarlar döndürülmez.

Depolama API'si#

Depolama kullanım dökümünü kategoriye (veri kümeleri, modeller, dışa aktarmalar) göre kontrol et ve en büyük öğelerini görüntüle.

Depolama Bilgisini Al#

GET /api/storage

Sorgu Parametreleri:

Yanıt:

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

Bulut Depolama Entegrasyonları#

Salt okunur GCS, S3 veya Azure Blob depolama entegrasyonlarına bağlan ve bunlara göz at:

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

Dört işlem de çalışma alanı için isteğe bağlı owner sorgu parametresini kabul eder. Nesne göz atma (object browsing) ayrıca zorunlu target ile isteğe bağlı prefix ve sağlayıcı cursor sorgu parametrelerini kabul eder. Bağlantı ve keşif istek gövdeleri, interaktif OpenAPI başvurusundaki sağlayıcı kimlik bilgisi şemalarını kullanır; kimlik bilgileri asla döndürülmez.

Yükleme API'si#

Hızlı ve güvenilir transferler için imzalı URL'ler kullanarak dosyaları doğrudan bulut depolama alanına yükle. Bir model yüklemesini tamamlamak, modelin ağırlıklarını ekler. Bir veri seti arşivi yüklemesini tamamlamak ise oturumu kaydeder; işlem başlatmak için bu sessionId değerini POST /api/datasets/ingest parametresine ilet. Data documentation sayfasına bak.

İmzalı Yükleme URL'sini Al#

POST /api/upload/signed-url

Doğrudan bulut depolamaya dosya yüklemek için imzalı bir URL talep et. İmzalı URL, büyük dosya transferleri için API sunucusunu atlar.

Gövde:

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Yanıt:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Yüklemeyi Tamamla#

POST /api/upload/complete

Platforma bir dosya yüklemesinin tamamlandığını bildir. Modeller için bu işlem, yüklenen ağırlıkları ekler. Veri seti arşivleri için bu işlem yükleme oturumunu doğrular ve kaydeder; veri seti işlemeye başlamak için sonrasında POST /api/datasets/ingest fonksiyonunu çağır.

Gövde:

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

Entegrasyonlar API#

Veri setlerini üçüncü taraf hizmetlerden içe aktar. Integrations documentation sayfasına bak.

Roboflow İçe Aktarmayı Önizle#

POST /api/integrations/roboflow/preview

Bir Roboflow API key değerini toplu içe aktarma planına çözümle: çalışma alanı bilgisi, yeni içe aktarılacak projeler, zaten içe aktarılmış versiyon sayısı (atlandı) ve desteklenmeyen proje türleri. Roboflow API key gövdede iletilir ve kalıcı olarak saklanmaz.

Roboflow'dan İçe Aktar#

POST /api/integrations/roboflow/import

Seçilen Roboflow projelerini çalışma alanına içe aktarmak için veri kümesi alım işlerini sıraya al. Depolama alanı boşluğu gerektirir ve her veri kümesi planının içe aktarma başına boyut sınırına uygun olmalıdır.

API Anahtarları API'si#

Programatik erişim için API anahtarlarını yönet. API Keys documentation sayfasına bak.

API Anahtarlarını Listele#

GET /api/api-keys

API anahtarıyla kimliği doğrulanan istemciler anahtar meta verilerini alır, şifresi çözülmüş mevcut anahtar değerlerini asla almaz. Yeni oluşturulan bir anahtar POST /api/api-keys tarafından bir kez döndürülür.

Düzenleyici (editor) erişimine sahip olduğun bir çalışma alanı için anahtarları yönetmek üzere isteğe bağlı owner sorgu parametresini ilet.

API Anahtarı Oluştur#

POST /api/api-keys

Gövde:

{
    "name": "training-server"
}

API Anahtarını Sil#

DELETE /api/api-keys

Sorgu Parametreleri:

Örnek:

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

Takımlar ve Üyeler API'si#

Takım çalışma alanları oluştur, üyeleri davet et ve iş birliği için rollerini yönet. Teams documentation sayfasına bak.

Takımları Listele#

GET /api/teams

Takım Oluştur#

POST /api/teams/create

Gövde:

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

Üyeleri Listele#

GET /api/members

Mevcut çalışma alanındaki üyeleri döndürür.

Üye Davet Et#

POST /api/members

Gövde:

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

Üye Rolünü Güncelle#

PATCH /api/members/{userId}

Üyeyi Kaldır#

DELETE /api/members/{userId}

Sahipliği Devret#

POST /api/members/transfer-ownership

Keşfet (Explore) API'si#

Topluluk tarafından paylaşılan halka açık veri setlerini ve projeleri ara ve onlara göz at. Explore documentation sayfasına bak.

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

GET /api/explore/search

Sorgu Parametreleri:

Kenar Çubuğu Verileri#

GET /api/explore/sidebar

Keşfet kenar çubuğu için küratörlü içeriği döndürür.

Kullanıcı ve Ayarlar API'leri#

Profilini, API anahtarlarını, depolama kullanımını ve takım çalışma alanlarını yönet. Settings documentation sayfasına bak.

Hesap Özeti#

GET /api/account/summary

Kimliği doğrulanmış hesabın planını, kredi bakiyesini, kaynak sayılarını ve ekip çalışma alanlarını döndürür.

Kullanıcı Adına Göre Kullanıcıyı Al#

GET /api/users

Sorgu Parametreleri:

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

PATCH /api/users

Gövde:

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

Kullanıcı Adı Kullanılabilirliğini Kontrol Et#

GET /api/username/check

Sorgu Parametreleri:

Ayarlar#

GET /api/settings
POST /api/settings

Kullanıcı profili ayarlarını (görünen ad, biyografi, sosyal medya bağlantıları vb.) al veya güncelle.

Çalışma Alanı Simgesi#

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

Çok parçalı form alanı image olarak 5 MB'a kadar bir WebP profil/çalışma alanı simgesi yükle veya simgeyi kaldır. Bir takım çalışma alanı için isteğe bağlı owner parametresini ilet.

Python Entegrasyonu#

Daha kolay entegrasyon için, kimlik doğrulama, yüklemeler ve gerçek zamanlı metrik akışını otomatik olarak yöneten Ultralytics Python paketini kullan.

Kurulum & Ayarlar#

pip install "ultralytics>=8.4.104"

Kurulumu doğrula:

yolo check

Kimlik Doğrulama#

yolo login YOUR_API_KEY

Platform Veri Kümelerini Kullanma#

Veri setlerine ul:// URI'leriyle başvuru yap:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

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

URI Formatı:

Platforma Gönderme#

Sonuçları bir Platform projesine gönder:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

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

Senkronize edilenler:

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

API Örnekleri#

Platformdan bir model yükle:

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

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

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

results = model("image.jpg")

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

Modeli dışa aktar:

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

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

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

Doğrulama:

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

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

SSS#

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

Çoğu uç nokta, her istekte kaç sonucun döndürüleceğini kontrol etmek için bir limit parametresi kullanır:

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

Etkinlik (Activity) ve Çöp Kutusu (Trash) uç noktaları da sayfa tabanlı sayfalandırma (pagination) için bir page parametresini destekler:

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

Explore Search uç noktası, sabit 20 sayfa boyutuyla page yerine offset kullanır:

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

API'yi SDK olmadan kullanabilir miyim?#

Yukarıda belgelenen halka açık REST işlemleri Python SDK olmadan kullanılabilir. SDK; gerçek zamanlı metrik akışı ve otomatik model yükleme gibi özellikler ekleyen kullanışlı bir sarmalayıcıdır (wrapper). Makine tarafından okunabilir sözleşmeyi platform.ultralytics.com/api/docs adresinden interaktif olarak inceleyebilirsin; yalnızca tarayıcı oturumuna dayalı hesap akışları Platform UI içinde kalır.

API istemci kütüphaneleri var mı?#

Ultralytics Python paketini kullan veya herhangi bir dilden doğrudan HTTP istekleri yap.

Hız sınırlarını (rate limits) nasıl yönetirim?#

Doğru süre boyunca beklemek için 429 yanıtındaki Retry-After başlığını 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")

Model veya veri kümesi kimliğimi (ID) nasıl bulurum?#

Kaynak kimlikleri (IDs) oluşturma, listeleme ve alma API yanıtları tarafından döndürülür. Platform sayfa URL'leri veritabanı kimlikleri yerine insan tarafından okunabilir kısa adlar (slugs) kullanır:

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

Bir model, veri seti, proje, dağıtım veya diğer kaynaklar için karşılık gelen _id değerini bulmak üzere liste uç noktalarını kullan.