Referência da REST API#

A Ultralytics Platform fornece uma REST API para acesso programático a conjuntos de dados, imagens, projetos, modelos, treino, exportações e implementações.

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

Visão geral da API#

A API está organizada em torno dos principais recursos da Platform:

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

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

Autenticação#

A maioria dos endpoints requer uma chave da API. Os endpoints que disponibilizam conteúdo público — ler um conjunto de dados, projeto ou modelo público, listar imagens de um conjunto de dados público, executar inferência num modelo público ou pesquisar em Explorar — também aceitam pedidos anónimos e simplesmente devolvem mais resultados quando é fornecida uma chave.

Obter uma chave da API#

1. Acede a Settings > API Keys
2. Clica em Create Key
3. Copia a chave gerada

Consulta Chaves da API para obter instruções detalhadas.

Cabeçalho de autorização#

Inclui a tua chave da API como token bearer:

Authorization: Bearer YOUR_API_KEY

Exemplo#

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

URL base#

Todos os endpoints da API utilizam:

https://platform.ultralytics.com/api

Caminhos dos recursos#

Os recursos são identificados pelos mesmos nomes legíveis por humanos que aparecem nos URLs da Platform, e não por IDs de base de dados:

• {owner} é um nome de utilizador pessoal ou identificador de espaço de trabalho de uma equipa: 4–32 caracteres alfanuméricos em minúsculas, com hífenes únicos entre segmentos.
• {dataset}, {project}, {model} e {deployment} seguem o mesmo padrão de minúsculas com hífenes, até 128 caracteres.
• {imageId} e {exportId} são IDs hexadecimais de 24 caracteres devolvidos pela API.
• Mudar o nome de um recurso através de PATCH altera simultaneamente o name apresentado e o nome no URL, e a resposta devolve o nome atual no URL para que possas continuar a utilizá-lo.

Limites de frequência#

A API aplica limites de janela deslizante por chave da API. Cada rota pertence a uma categoria, e cada categoria tem um contador independente, por isso 20 pedidos de previsão não consomem o teu limite predefinido.

As rotas da Platform exclusivas do navegador, como o checkout da faturação e a gestão de equipas, têm os seus próprios limites, que não se aplicam ao tráfego de chaves da API.

Quando sofre limitação, a API devolve 429 com cabeçalhos e um corpo JSON:

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

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

Endpoints dedicados (ilimitados)#

Os endpoints dedicados não estão sujeitos aos limites de taxa das chaves da API da Platform quando chamas diretamente o serviceUrl próprio da implementação (por exemplo, https://predict-abc123.run.app/predict). Nesse caso, o débito depende da configuração do serviço implementado.

Formato da resposta#

Respostas de sucesso#

As respostas são objetos JSON com campos específicos de cada recurso. Não existe um envelope genérico: os endpoints de listagem devolvem uma coleção nomeada juntamente com contagens, e as mutações devolvem os identificadores alterados.

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

As respostas que contêm dados também incluem region (us, eu ou ap), a região de armazenamento desse espaço de trabalho.

Respostas de erro#

Todas as respostas de erro são objetos JSON com uma mensagem error:

{
    "error": "Dataset not found"
}

Paginação#

O estilo de paginação depende da coleção:

API de conjuntos de dados#

Cria, consulta e gere conjuntos de dados de imagens anotadas para treinar modelos YOLO. Consulta a documentação de conjuntos de dados.

Listar conjuntos de dados#

GET /api/datasets/{owner}

SDK Python: client.datasets.list(owner)

Devolve os conjuntos de dados públicos do proprietário, além dos conjuntos de dados privados quando a tua chave pode visualizar esse espaço de trabalho.

Parâmetros de consulta:

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

Resposta:

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

Obter conjunto de dados#

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

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

Devolve o objeto completo do conjunto de dados sob uma chave dataset, incluindo classNames, splits, versions, source e o objeto metadata definido pelo utilizador.

Criar conjunto de dados#

POST /api/datasets

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

Corpo:

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

A resposta retorna o slug dataset que foi criado, portanto, leia-o antes de fazer o upload, a menos que definas requireExactSlug.

Resposta (201):

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

Atualizar conjunto de dados#

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

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

Corpo (atualização parcial):

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

Campos aceites: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter e starred. Envia um objeto metadata vazio ({}) para limpar os metadados personalizados. As chaves dos metadados estão limitadas a 128 caracteres e o objeto serializado a 500.000 caracteres.

Resposta:

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

A mudança do nome altera o nome no URL, por isso utiliza o valor dataset devolvido nos pedidos seguintes.

Eliminar dataset#

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

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

Move o conjunto de dados para a lixeira, onde pode ser recuperado durante 30 dias.

Clonar dataset#

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

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

Copia um conjunto de dados acessível, com as respetivas imagens e etiquetas, para o teu espaço de trabalho pessoal ou para um espaço de trabalho de equipa.

Corpo opcional (todos os campos são opcionais):

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

Resposta (201): id, owner, dataset, name, imageCount, classCount e region. Os conjuntos de dados suportados por uma fonte de armazenamento ligada devolvem 409, porque os respetivos ficheiros não são copiados.

Transferir uma exportação de conjunto de dados#

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

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

Devolve um URL de transferência NDJSON assinado. Omite v para exportar o estado atual do conjunto de dados, reutilizando a exportação em cache quando nada mudou desde a sua geração.

Parâmetros de consulta:

Resposta:

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

Pedir uma versão específica devolve downloadUrl e version em vez de cached.

Criar versão do conjunto de dados#

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

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

Cria um instantâneo numerado e imutável do conjunto de dados e armazena a sua exportação NDJSON. Requer acesso de editor.

Corpo (opcional):

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

Resposta:

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

reused é true quando o conjunto de dados não sofreu alterações desde a versão anterior e esse instantâneo é devolvido em alternativa.

Atualizar descrição da versão#

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

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

Corpo:

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

Resposta: {"ok": true}

Restaurar versão do conjunto de dados#

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

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

Reconstrói imagens, anotações e classes a partir de uma versão guardada sem copiar os bytes das imagens.

Corpo:

{
    "version": 2
}

Resposta: {"version": 2, "imageCount": 1000}

Obter estatísticas do conjunto de dados#

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

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

Devolve contagens de anotações por classe, histogramas de imagens e anotações e mapas de calor. Os conjuntos de dados grandes são amostrados; nesse caso, sampleSize indica quantas imagens contribuíram.

Resposta (abreviada):

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

Gerir classes#

Fundir classes (reatribui as anotações a uma classe-alvo e remove as classes de origem):

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

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

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

Eliminar classes (as respetivas anotações são eliminadas e os IDs das classes restantes diminuem):

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

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

{
    "classIds": [2, 4]
}

Ambas as operações devolvem success, os valores atualizados de classNames e classColors e um resumo do que mudou (mergedClassIds e targetClassId, ou deletedClassIds e deletedAnnotations).

Redistribuir divisões#

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

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

Reatribui aleatoriamente as imagens entre as divisões. As três percentagens têm de totalizar 100.

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

Resposta: success, as contagens resultantes de splits e modified (número de imagens movidas).

Embeddings do conjunto de dados#

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

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

GET devolve o resumo da análise (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST coloca uma análise de embeddings na fila e devolve 202 com um jobId. DELETE cancela a tarefa ativa e devolve o ID da tarefa cancelada ou null.

Agrupamento de imagens#

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

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

Devolve o layout 2D UMAP de uma análise concluída, paginado com offset e limit (predefinição e máximo de 50.000). Cada entrada contém id, umapX, umapY, split, classIds, width, height, bytes, labelCount e missing.

Listar modelos treinados num conjunto de dados#

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

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

Resposta:

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

Listar imagens do conjunto de dados#

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

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

Parâmetros de consulta:

Resposta:

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

Obter imagens selecionadas#

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

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

Retorna a mesma estrutura de imagem para até 1.000 IDs de imagem fornecidos e aceita os mesmos parâmetros de filtro e de consulta de URL que a operação de listagem.

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

Ingerir dados do conjunto de dados#

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

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

Processa um carregamento concluído, um arquivo remoto ou uma fonte de armazenamento ligada num conjunto de dados existente. Fornece exatamente uma fonte:

As sessões de carregamento são associadas a um conjunto de dados pelo assetId passado a POST /api/upload/signed-url, e a ingestão rejeita uma sessão pertencente a um conjunto de dados diferente.

Corpo (arquivo carregado):

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

Corpo (arquivo remoto ou NDJSON):

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

Corpo (importação de rótulos numa ingestão posterior):

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

Corpo (associação de metadados por imagem):

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

As chaves dos metadados devem corresponder ao caminho normalizado dentro do arquivo, incluindo as pastas. Nas importações NDJSON, cada registro pode conter o seu próprio objeto metadata, que tem precedência sobre uma entrada correspondente de imageMetadata. Os caminhos dos arquivos estão limitados a 1.024 caracteres, as chaves de metadados de nível superior a 128 caracteres e cada objeto de metadados — bem como o mapa imageMetadata inteiro — a 500.000 caracteres serializados.

Resposta (201):

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

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

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

import io
import zipfile
from pathlib import Path

import requests

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

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

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

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

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

API de imagens#

Inspeciona, anota, move e elimina imagens de conjuntos de dados pelo seu ID de imagem de 24 caracteres. Consulta a documentação de anotações.

Obter imagem#

GET /api/images/{imageId}

SDK Python: client.images.retrieve(image_id)

Retorna o objeto metadata (personalizado, definido pelo utilizador), properties (nome do arquivo, hash, dimensões, divisão, contagens, marcas temporais), labels e o classNames do conjunto de dados.

Atualizar imagem#

PATCH /api/images/{imageId}

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

Substitui as anotações ou os metadados personalizados — envia uma das duas estruturas, não ambas.

Corpo (anotações):

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

Corpo (metadados):

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

Eliminar imagem#

DELETE /api/images/{imageId}

SDK Python: client.images.delete(image_id)

Elimina permanentemente uma imagem e as suas anotações.

Anotar imagem automaticamente#

POST /api/images/{imageId}/predict

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

Executa a inferência YOLO na imagem e retorna as anotações previstas. Não as guarda — escreve os resultados de volta com PATCH /api/images/{imageId} quando estiveres satisfeito com eles.

Resposta: success, predictions (objetos de anotação), modelUsed e inferenceTime. Um modelo cujas classes não correspondam às do conjunto de dados retorna 422.

Auto-anotar um conjunto de dados#

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

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

Salva uma versão do conjunto de dados, depois coloca na fila uma execução que rotula as imagens sem rótulo do conjunto de dados com o modelo e retorna 202. O corpo aceita os mesmos campos modelId, confidence e iou do endpoint de imagem única, mais includeAnnotated (padrão false) para anotar também imagens que já possuem rótulos e um array opcional classMapping fornecendo o índice de classe do conjunto de dados para cada classe de modelo, ou null para ignorá-lo. Os rótulos existentes nunca são alterados, e a execução é cobrada pelas imagens que ela realmente processa. 402 significa que o saldo não cobre a estimativa, 409 que o conjunto de dados não está pronto, não tem imagens restantes para anotar ou já tem uma execução em andamento, e 422 que o conjunto de dados não tem classes: crie as classes com o endpoint de classes antes de chamar este endpoint, que é o que a etapa Mapear classes do aplicativo faz antes de iniciar uma execução.

GET no mesmo caminho (client.datasets.batch(owner, dataset)) retorna a execução em andamento e seu progresso, ou a última execução concluída até que seja dispensada; DELETE (client.datasets.delete_batch(owner, dataset)) cancela uma execução em andamento ou fecha a fatura e descarta o resumo concluído.

Mover imagens em massa#

PATCH /api/images/bulk

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

Move até 1.000 imagens de um conjunto de dados para uma divisão diferente.

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

Os conflitos de nome de arquivo ou conteúdo retornam 409 até escolheres uma conflictPolicy abrangente para todo o lote entre skip, keep_both ou replace. A resposta informa modifiedCount, skippedCount e targetSplit.

Eliminar imagens em massa#

DELETE /api/images/bulk

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

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

Elimina até 1.000 imagens de um único conjunto de dados e retorna deletedCount e deletedImageIds.

Obter URLs de imagens assinadas#

POST /api/images/urls

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

Retorna URLs assinadas temporárias para até 100 IDs de imagem de um conjunto de dados.

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

Resposta: urls e thumbnails, ambos indexados pelo ID da imagem.

API de projetos#

Organiza os teus modelos em projetos. Cada modelo pertence a um projeto. Consulta a documentação de projetos.

Listar projetos#

GET /api/projects/{owner}

SDK Python: client.projects.list(owner)

Parâmetros de consulta:

Obter projeto#

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

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

Retorna o objeto project, uma matriz models de resumos por modelo (estado, métricas, épocas, pesos, argumentos de treino) e isOwner.

Criar projeto#

POST /api/projects

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

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

Resposta (201): id, owner, project, region.

Atualizar projeto#

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

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

Campos aceites: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences e starred.

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

Envia um objeto metadata vazio ({}) para o limpar. Os metadados do projeto usam os mesmos limites de 128 caracteres por chave e de 500.000 caracteres por objeto serializado dos metadados do conjunto de dados.

Eliminar projeto#

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

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

Move o projeto e os seus modelos para o lixo, retornando cascadedModels.

Clonar projeto#

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

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

Clona um projeto acessível e os seus modelos concluídos. O corpo opcional aceita project, name, description, visibility, license e um owner de destino.

API de modelos#

Gere modelos YOLO treinados — consulta métricas, descarrega pesos, executa inferência e monitoriza o treino. Consulta a documentação de modelos.

Listar modelos num projeto#

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

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

Parâmetros de consulta:

Obter modelo#

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

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

Parâmetros de consulta:

A resposta predefinida contém o objeto model — estado, tarefa, métricas, trainArgs, trainResults, classNames, computeCost, metadata e mais — além de isOwner.

Criar modelo#

POST /api/models

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

Cria um registro de modelo não treinado ao qual podes associar pesos ou que podes treinar.

Resposta (201): id, owner, project, model, region.

Atualizar modelo#

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

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

Os campos aceitos incluem name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError e starred. Passar projectId sozinho move o modelo para outro projeto do mesmo proprietário; a resposta retorna o slug do modelo no destino, renamed: true quando esse slug já estiver em uso lá e 409 enquanto o modelo ainda estiver treinando.

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

O metadata personalizado é separado dos campos geridos pelo treino, como trainArgs, environment e trainResults, e usa os mesmos limites de tamanho dos metadados do conjunto de dados.

Eliminar modelo#

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

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

Move o modelo para o lixo durante 30 dias.

Descarregar arquivos do modelo#

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

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

Retorna URLs assinados de curta duração para os pesos do modelo.

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

Clonar modelo#

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

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

Copia um modelo acessível para um projeto existente.

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

Execute a inferência#

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

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

É possível fazer previsões com modelos públicos sem autenticação. Os modelos privados e partilhados exigem uma chave de API com acesso ao projeto principal.

Formulário multipartes:

Fornece file ou source. Os modelos de profundidade também aceitam bits (8, 12 ou 16) para selecionar a quantização PNG do mapa de profundidade. As solicitações que excedam os limites de entrada do serviço retornam 413.

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

Resposta:

Cada entrada em images contém shape, speed, results e, para tarefas de predição densa, um payload PNG semantic_mask ou depth (os valores de profundidade são pixel × max / divisor, com divisor 255 para o mapa predefinido de 8 bits e 65535 quando bits é 12 ou 16). O objeto metadata informa a contagem de imagens, os tempos das funções, a tarefa e as versões do serviço. Os caminhos internos dos modelos nunca são retornados.

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

Verificar o progresso do treino#

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

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

Retorna job, contendo o estado, o progresso das épocas, os tempos, os detalhes computacionais, os argumentos de treino, as métricas da época e detalhes de erro seguros, ou null quando o modelo nunca foi treinado. Os modelos em projetos públicos podem ser lidos sem autenticação.

Cancelar o Treino#

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

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

Termina a instância de computação em execução e marca o trabalho como cancelado. Retorna 409 quando o treino já não está ativo.

API de treino#

Inicia o treino de YOLO em GPUs na nuvem e monitoriza o progresso em tempo real. Consulta a documentação do treino na nuvem.

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

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

Obter disponibilidade de GPUs#

GET /api/training/gpu-availability

SDK Python: client.training.gpu_availability()

Retorna o estado atual do stock, indexado pelo ID da GPU. É público e não requer autenticação; passa managed=true para incluir a capacidade de treino gerida, que requer uma chave de API.

Iniciar treino#

POST /api/training/start

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

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

Resposta:

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

O treino retorna 402 quando o teu saldo de créditos é demasiado baixo e 503 quando não há capacidade disponível para a GPU solicitada.

API de exportação#

Converte modelos para formatos otimizados como ONNX, TensorRT, CoreML e LiteRT para implementação na edge. Consulta a documentação de implementação.

Listar exportações#

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

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

Parâmetros de consulta:

Criar exportação#

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

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

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

Resposta (201): id, format, status (queued ou running), gpuType, region. Uma exportação equivalente que já esteja em curso retorna 409.

Formatos compatíveis:

Utiliza o argumento format da tabela de exportação partilhada abaixo. PyTorch é o formato de origem e não é um destino de exportação da API.

nms=None por padrão utiliza saídas brutas para NMS externo. Define nms=False para selecionar uma cabeça livre de NMS disponível; os formatos não suportados recorrem ao seu caminho de saída nativo. As entradas nms acima identificam formatos que podem incorporar NMS com nms=True.

Obter estado da exportação#

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

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

Retorna o objeto export com status, format, args, gpuType, marcas temporais e, quando concluído, um objeto file contendo size, downloadUrl e downloadFilename.

Cancelar ou eliminar exportação#

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

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

Cancela uma exportação ativa ou elimina uma concluída e o respetivo ficheiro. A resposta indica qual das ações ocorreu:

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

API de implementações#

Implementa modelos em endpoints de inferência dedicados, com verificações de integridade e monitorização. Consulta a documentação dos endpoints.

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

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

Listar implementações#

GET /api/deployments/{owner}

SDK Python: client.deployments.list(owner)

Parâmetros de consulta:

Os utilizadores anónimos têm de filtrar por um modelo público; para listar um workspace completo é necessária autenticação.

Criar implementação#

POST /api/deployments/{owner}

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

Corpo:

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

Resposta (201): id, deployment, status (creating), message e region.

Obter implementação#

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

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

Retorna o objeto deployment com status, statusMessage, region, serviceUrl e resources.

Iniciar, parar ou substituir uma implementação#

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

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

Um único campo action seleciona a operação:

{ "action": "start" }

A substituição implementa uma nova revisão, preservando o ID da implementação, a região e o URL do endpoint; a revisão existente continua ativa se a implementação falhar. O modelo de substituição tem de estar concluído e ter pesos aos quais a tua chave possa aceder. As operações concluídas retornam 200 com status ready ou stopped; as operações ainda em implementação retornam 202 com deploying ou stopping.

Eliminar implementação#

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

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

Remove permanentemente o endpoint de inferência.

Verificação de integridade#

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

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

Faz ping e aquece o endpoint, retornando healthy, latencyMs e o código upstream status.

Executar inferência numa implementação#

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

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

Encaminha uma imagem ou um vídeo através do endpoint dedicado. Os contratos do pedido e da resposta correspondem aos da inferência de modelos.

Formulário multipartes:

Obter métricas#

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

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

Parâmetros de consulta:

A resposta completa contém summary (totais dos pedidos, taxa de erros e latência média e p50/p95/p99) e timeSeries (pedidos, erros, latência, CPU, memória e contagem de instâncias). A resposta do sparkline retorna requests24h, totalRequests, errorRate e avgLatencyMs.

Obter registos#

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

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

Parâmetros de consulta:

API do lixo#

Visualiza, restaura e elimina permanentemente projetos, datasets e modelos eliminados de forma reversível. Os itens são purgados automaticamente após 30 dias. Consulta a documentação do lixo.

Listar a Lixeira#

GET /api/trash

SDK Python: client.lifecycle.trash()

Parâmetros de consulta:

A resposta inclui items (cada um com daysRemaining), total, page, limit, totalPages e um summary com os totais por tipo.

Restaurar item#

POST /api/trash

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

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

Restaurar um projeto também restaura os modelos que foram enviados para o lixo com ele, indicados como restoredModels.

Eliminar permanentemente#

DELETE /api/trash

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

Eliminar um item:

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

Ou esvaziar todo o lixo:

{
    "all": true
}

A resposta indica deletedCount, além de cascadedModels e survivingDeployments quando aplicável.

API de carregamento#

Carrega ficheiros diretamente para o armazenamento na nuvem utilizando URLs assinados. A conclusão do carregamento de um modelo associa os respetivos pesos; a conclusão do carregamento de um arquivo de dataset regista a sessão, que de seguida passas para a ingestão do dataset. Consulta a documentação de dados.

Obter URL de carregamento assinado#

POST /api/upload/signed-url

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

Corpo:

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

Resposta:

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

Envia o arquivo com uma solicitação PUT para uploadUrl, usando o mesmo Content-Type que declaraste e cada cabeçalho retornado em headers. As URLs de upload de conjuntos de dados são válidas por 12 horas e servem apenas para criação: um segundo PUT para a mesma URL retorna 412, e um PUT sem os cabeçalhos retornados retorna 400.

Concluir carregamento#

POST /api/upload/complete

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

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

Resposta: success e um objeto file com size e contentType. Para modelos, isto associa os pesos; para arquivos de datasets, chama ingest de seguida para iniciar o processamento.

Quando md5 é fornecido, ele é verificado em relação ao objeto armazenado. Uma divergência retorna 400; em uma sessão que ainda não está completa, isso também exclui o arquivo enviado e deixa a sessão incompleta, portanto, solicita uma nova URL assinada e faz o upload novamente. Uma sessão de conjunto de dados concluída pode ser concluída novamente enquanto o arquivo compactado existir, mas conclusões concorrentes com resumos diferentes retornam 409; as sessões de modelos são removidas após a conclusão. checksum é armazenado como metadados do arquivo do modelo e não é verificado.

API de integrações de armazenamento#

Liga contas somente de leitura do Google Cloud Storage, Amazon S3 ou Azure Blob Storage e navega por elas como fontes de datasets. Consulta a documentação de integrações.

Listar integrações#

GET /api/integrations/buckets

SDK Python: client.storage_integrations.list()

Retorna integrations, cada um com id, provider, credentialIdentity, targets e createdAt. As credenciais nunca são retornadas.

Descobrir localizações#

POST /api/integrations/buckets/discover

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

Lista os buckets ou contentores legíveis com as credenciais fornecidas, sem os guardar.

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

Resposta: {"targets": ["my-bucket", "another-bucket"]}

Ligar armazenamento#

POST /api/integrations/buckets

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

Usa os mesmos formatos de credenciais da descoberta, além de um array targets obrigatório com 1 a 50 nomes de buckets ou contentores. Retorna 201 com a integração guardada. As credenciais temporárias do S3 (chaves de acesso ASIA) são rejeitadas.

Procurar objetos#

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

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

Parâmetros de consulta:

Retorna entries (cada kind é folder ou file) e um cursor opcional para a página seguinte.

Desligar armazenamento#

DELETE /api/integrations/buckets/{id}

SDK Python: client.storage_integrations.delete(id)

Remove as credenciais guardadas sem eliminar os dados do fornecedor. Os conjuntos de dados ligados continuam visíveis, mas os respetivos ficheiros permanecem indisponíveis até que a mesma conta de armazenamento seja ligada novamente. Requer acesso de administrador do espaço de trabalho.

API de importação de conjuntos de dados#

Importa conjuntos de dados de serviços de terceiros. Consulta a integração do Roboflow.

Pré-visualizar uma importação do Roboflow#

POST /api/integrations/roboflow/preview

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

Resolve uma chave de API do Roboflow num plano de importação: detalhes do espaço de trabalho, newDatasets que seriam importados, contagens de projetos ignorados, não suportados e não resolvidos, bytesTotal e a tua margem disponível storage. A chave de API do Roboflow é lida no corpo e não é persistida.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importar do Roboflow#

POST /api/integrations/roboflow/import

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

Coloca em fila trabalhos de ingestão para até 500 versões de projetos do Roboflow selecionadas, usando os itens retornados pela pré-visualização.

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

Resposta (201): arrays imported, failed e skipped. As importações requerem espaço de armazenamento disponível, e cada conjunto de dados deve respeitar o limite de tamanho por importação do teu plano.

API da conta#

Consulta a tua conta da Platform, chaves, armazenamento e perfis públicos. Consulta a documentação das definições.

Resumo da conta#

GET /api/account/summary

SDK Python: client.account.summary()

Retorna o plano, o saldo de créditos e as contagens de recursos do espaço de trabalho que emitiu a chave.

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

Listar chaves de API#

GET /api/api-keys

SDK Python: client.account.api_keys()

Retorna keys com keyId, name, keyPrefix e createdAt para o espaço de trabalho da chave. Os pedidos autenticados com chave de API recebem apenas metadados; os valores completos das chaves são apresentados ao proprietário do espaço de trabalho em Definições > Chaves de API na interface da Platform, onde as chaves também são criadas e revogadas.

Verificar utilização do armazenamento#

GET /api/storage

SDK Python: client.account.storage()

Parâmetros de consulta:

Resposta:

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

Obter um perfil público de utilizador#

GET /api/users

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

Parâmetros de consulta:

Retorna o perfil público user com followerCount e, para autores de pedidos autenticados, isFollowed.

Seguir ou deixar de seguir um utilizador#

PATCH /api/users

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

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

Resposta: followed e o followerCount atualizado.

API de faturação#

Consulta a utilização do plano e o teu registo de créditos. Consulta a documentação de faturação.

Ver plano e utilização#

GET /api/billing/usage-summary

SDK Python: client.billing.usage_summary()

Retorna plan (ID, estado, ciclo de faturação, fim do período), metrics (limite e utilização do armazenamento), trainingCredit, features, creditsCents e contagens de lugares.

Ver transações#

GET /api/billing/transactions

SDK Python: client.billing.transactions()

Parâmetros de consulta:

Cada transação inclui id, type (como purchase, training, monthly_grant ou refund), amountCents, balanceAfter, createdAt, um receiptUrl opcional e o contexto do modelo para custos de treino. Os detalhes internos de faturação nunca são retornados.

Explorar API#

Pesquisa projetos públicos e conjuntos de dados partilhados pela comunidade. Consulta a documentação do Explorar.

Pesquisar conteúdo público#

GET /api/explore/search

SDK Python: client.explore.search()

Parâmetros de consulta:

Resposta: projects, datasets e hasMore.

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

SDK de Python#

ultralytics-platform é um cliente Python tipado gerado a partir do contrato OpenAPI, com um método por endpoint (client.datasets.list, client.models.predict, client.exports.create, ...). Cada método aceita os parâmetros do caminho posicionalmente, outras entradas como argumentos nomeados e timeout e extra_headers opcionais por pedido.

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

from ultralytics_platform import Platform

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

AsyncPlatform expõe a mesma árvore de recursos para código async/await, as respostas malsucedidas geram APIError com status_code, body e json analisado, e as falhas de ligação geram APIConnectionError. Consulta o repositório do SDK para ver o README completo.

Integração com Python#

Para fluxos de trabalho de treinamento e inferência, usa o pacote Python da Ultralytics, que lida automaticamente com autenticação, uploads e transmissão de métricas em tempo real. No Python 3.11+, pip install ultralytics também instala o SDK ultralytics-platform. Quando model.train(project=...) tem como alvo a Platform, os retornos de chamada de treinamento transmitem eventos através de client.training.metrics() do SDK e solicitam URLs de upload de pontos de verificação através de client.models.upload_checkpoint(), as operações POST /api/webhooks/training/metrics e POST /api/webhooks/models/upload no documento OpenAPI, portanto não há nada para chamares por ti mesmo.

Instalação e configuração#

A integração com a plataforma requer Python>=3.11 e ultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

Verifica a instalação:

yolo check

Autenticação#

yolo login YOUR_API_KEY

Utilizar conjuntos de dados da Platform#

Faz referência a conjuntos de dados com URIs ul://:

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

Formato da URI:

Enviar para a Platform#

Envia resultados para um projeto da Platform:

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

O que é sincronizado:

• Métricas de treino (em tempo real)
• Pesos finais do modelo
• Gráficos de validação
• Saída do console
• Métricas do sistema
• Argumentos de treinamento e ambiente do host (nome do host, sistema operativo, Python, hardware, commit do git, linha de comandos)

Exemplos de API#

Carregar um modelo da Platform:

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

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

Executar inferência:

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

Exportar modelo:

# 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

Validação:

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

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

Perguntas frequentes#