Referência da REST API#

Ultralytics Platform fornece uma REST API para acesso programático a datasets, imagens, projetos, modelos, treinamento, exportações e implantaçõ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 é organizada em torno dos recursos principais 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 de API. Endpoints que expõem conteúdo público — como ler um dataset, projeto ou modelo público, listar imagens públicas de datasets, executar inferência em um modelo público ou pesquisar no Explore — também aceitam solicitações anônimas e simplesmente retornam mais dados quando uma chave é fornecida.

Obter uma chave de API#

1. Vai para Settings > API Keys
2. Clique em Create Key
3. Copie a chave gerada

Consulta as Chaves de API para obteres instruções detalhadas.

Cabeçalho de Autorização#

Inclua sua chave de API como um token de portador (bearer token):

Authorization: Bearer YOUR_API_KEY

Exemplo#

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

Base URL#

Todos os endpoints da API usam:

https://platform.ultralytics.com/api

Caminhos de recursos#

Os recursos são endereçados pelos mesmos nomes legíveis por humanos que aparecem nas URLs da Platform, e não por IDs de banco de dados:

• {owner} é um nome de usuário pessoal ou um identificador de espaço de trabalho de equipe: de 4 a 32 caracteres, alfanuméricos minúsculos com hífens únicos entre os segmentos.
• {dataset}, {project}, {model} e {deployment} seguem o mesmo padrão em minúsculas com hífens, com até 128 caracteres.
• {imageId} e {exportId} são IDs hexadecimais de 24 caracteres retornados pela API.
• Renomear um recurso por meio de PATCH altera o name de exibição e o nome da URL juntos, e a resposta retorna o nome atual da URL para que você possa continuar a segui-lo.

Limites de Taxa#

A API aplica limites de janela deslizante por chave de API. Cada rota se enquadra em uma categoria, e cada categoria possui um contador independente, de modo que 20 solicitações de predição não consomem sua franquia padrão.

As rotas da Platform exclusivas para navegador, como finalização de compra de faturamento e gerenciamento de equipe, possuem seus próprios limites que não se aplicam ao tráfego de chaves de API.

Quando limitada, a API retorna 429 com ambos os 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)#

Endpoints dedicados não estão sujeitos aos limites de taxa de chave de API da Platform quando você chama o serviceUrl próprio da implantação diretamente (por exemplo, https://predict-abc123.run.app/predict). A taxa de transferência depende então da configuração do serviço implantado.

Formato de Resposta#

Respostas de Sucesso#

As respostas são objetos JSON com campos específicos de recursos. Não há envelope genérico: os endpoints de lista retornam uma coleção nomeada juntamente com contagens, e as mutações retornam 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 para esse workspace.

Respostas de Erro#

Cada resposta de erro é um objeto JSON com uma mensagem error:

{
    "error": "Dataset not found"
}

Paginação#

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

API de Datasets#

Crie, navegue e gerencie datasets de imagens rotuladas para treinar modelos YOLO. Consulte a documentação de Datasets.

Listar Datasets#

GET /api/datasets/{owner}

SDK Python: client.datasets.list(owner)

Retorna os datasets públicos do proprietário, além dos datasets privados quando sua chave puder visualizar esse workspace.

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

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

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

Retorna o objeto de dataset completo sob uma chave dataset, incluindo classNames, splits, versions, source e o objeto metadata definido pelo usuário.

Criar Dataset#

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

Resposta (201):

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

Atualizar Dataset#

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 aceitos: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter e starred. Envie um objeto metadata vazio ({}) para limpar os metadados personalizados. As chaves de metadados são limitadas a 128 caracteres e o objeto serializado a 500.000 caracteres.

Resposta:

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

A renomeação altera o nome da URL, portanto, use o valor retornado de dataset para solicitações subsequentes.

Eliminar Dataset#

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

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

Move o dataset para o trash, onde ele pode ser recuperado por 30 dias.

Clonar Dataset#

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

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

Copia um dataset acessível, com suas imagens e rótulos, para o seu workspace pessoal ou para um workspace de equipe.

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 datasets apoiados por uma fonte de armazenamento conectada retornam 409 porque seus arquivos não são copiados.

Baixar uma exportação de dataset#

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

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

Retorna uma URL de download NDJSON assinada. Omitir v para exportar o estado atual do dataset, reutilizando a exportação em cache quando nada tiver mudado desde que foi gerada.

Parâmetros de consulta:

Resposta:

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

Solicitar uma versão específica retorna downloadUrl e version em vez de cached.

Criar Versão do Dataset#

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

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

Cria um instantâneo numerado imutável do conjunto de dados e armazena sua exportação em 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 foi alterado desde a versão anterior e esse instantâneo foi retornado em vez disso.

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

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

Retorna contagens de anotações por classe, histogramas de imagens e anotações, e mapas de calor. Conjuntos de dados grandes são amostrados, caso em que sampleSize informa 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#

Mesclar classes (reassignir anotações a uma classe de destino e, em seguida, remover as 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
}

Excluir classes (suas anotações são excluídas e os IDs das classes restantes são deslocados para baixo):

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

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

{
    "classIds": [2, 4]
}

Ambas as operações retornam success, o classNames e o classColors atualizados, 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 imagens entre as divisões. As três porcentagens devem somar 100.

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

Resposta: success, as contagens resultantes em 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

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

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

Agrupamento de Imagens#

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

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

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

Listar Modelos Treinados em um 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 o mesmo formato de imagem para até 1.000 IDs de imagem fornecidos e aceita os mesmos parâmetros de filtro e consulta de URL que a operação de listagem.

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

Ingerir Dados no Conjunto de Dados#

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

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

Processa um envio concluído, um arquivo remoto ou uma fonte de armazenamento conectada em um conjunto de dados existente. Forneça exatamente uma fonte:

As sessões de upload são vinculadas a um conjunto de dados pelo assetId passado para POST /api/upload/signed-url, e a ingestão rejeita uma sessão que pertença a um conjunto de dados diferente.

Corpo (arquivo enviado):

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

Corpo (arquivo remoto ou NDJSON):

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

Corpo (importando rótulos em uma ingestão posterior):

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

Corpo (anexando 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 de metadados devem corresponder ao caminho normalizado dentro do arquivo compactado, incluindo pastas. Para importações em NDJSON, cada registro pode carregar seu próprio objeto metadata, que tem precedência sobre uma entrada correspondente em imageMetadata. Os caminhos do arquivo compactado são limitados a 1.024 caracteres, as chaves de metadados de nível superior a 128 caracteres e cada objeto de metadados — bem como todo o mapa imageMetadata — 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#

Inspecione, anote, mova e exclua imagens do conjunto de dados por seu ID de imagem de 24 caracteres. Consulte a Documentação de anotações.

Obter Imagem#

GET /api/images/{imageId}

SDK Python: client.images.retrieve(image_id)

Retorna metadata (personalizado, definido pelo usuário), properties (nome do arquivo, hash, dimensões, divisão, contagens, carimbos de data/hora), labels e o classNames do conjunto de dados.

Atualizar Imagem#

PATCH /api/images/{imageId}

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

Substitui ou as anotações ou os metadados personalizados — envie um dos dois formatos, não ambos.

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)

Exclui permanentemente uma imagem e suas anotações.

Anotar Imagem Automaticamente#

POST /api/images/{imageId}/predict

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

Executa a inferência do YOLO na imagem e retorna as anotações previstas. Ela não as salva — grave os resultados de volta com PATCH /api/images/{imageId} quando estiver satisfeito com eles.

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

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

Conflitos de nome de arquivo ou conteúdo retornam 409 até que você escolha um conflictPolicy para toda a cesta de skip, keep_both ou replace. A resposta relata modifiedCount, skippedCount e targetSplit.

Excluir Imagens em Massa#

DELETE /api/images/bulk

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

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

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

Obter URLs de Imagens Assinados#

POST /api/images/urls

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

Retorna URLs temporários assinados para até 100 IDs de imagem de um conjunto de dados.

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

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

API de Projetos#

Organize seus modelos em projetos. Cada modelo pertence a um projeto. Consulte 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 (status, métricas, épocas, pesos, argumentos de treinamento), 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 aceitos: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences e starred.

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

Envie um objeto metadata vazio ({}) para limpá-lo. Os metadados do projeto usam os mesmos limites de chave de 128 caracteres e de objeto serializado de 500.000 caracteres que os metadados do conjunto de dados.

Eliminar Projeto#

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

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

Move o projeto e seus modelos para a lixeira, retornando cascadedModels.

Clonar Projeto#

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

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

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

API de Modelos#

Gerencie modelos YOLO treinados — visualize métricas, baixe pesos, execute inferência e monitore o treinamento. Consulte a Documentação de modelos.

Listar Modelos em um 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 padrão contém o objeto model — status, tarefa, métricas, trainArgs, trainResults, classNames, computeCost, metadata e muito 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 você pode anexar pesos ou 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.

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

O metadata personalizado é separado dos campos pertencentes ao treinamento, como trainArgs, environment e trainResults, e usa os mesmos limites de tamanho que os metadados do conjunto de dados.

Excluir Modelo#

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

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

Move o modelo para o lixo por 30 dias.

Baixar Arquivos de Modelo#

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

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

Retorna URLs assinadas 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"
}

Executar inferência#

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

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

Modelos públicos podem ser previstos sem autenticação. Modelos privados e compartilhados exigem uma API key com acesso ao projeto principal.

Formulário Multipart:

Forneça file ou source. Modelos de profundidade também aceitam bits (8, 12 ou 16) para selecionar a quantização PNG do mapa de profundidade. Solicitações que excedem 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 carrega 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 padrão de 8 bits e 65535 quando bits é 12 ou 16). O objeto metadata relata a contagem de imagens, tempos de execução de funções, tarefa e versões de serviço. Caminhos de modelos internos 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 treinamento#

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

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

Retorna job, contendo status, progresso de épocas, tempo, detalhes de computação, argumentos de treino, métricas de época e detalhes seguros de erro, ou null quando o modelo nunca foi treinado. Modelos em projetos públicos são legíveis sem autenticação.

Cancelar Treinamento#

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

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

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

API de Treinamento#

Inicie o treinamento do YOLO em GPUs na nuvem e monitore o progresso em tempo real. Consulte a documentação de Treinamento em 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 GPU#

GET /api/training/gpu-availability

SDK Python: client.training.gpu_availability()

Retorna o status atual do estoque indexado por ID de GPU. Público e sem autenticação; passe managed=true para incluir capacidade de treinamento gerenciado, o que exige uma API key.

Iniciar Treinamento#

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 treinamento retorna 402 quando o seu saldo de créditos está muito baixo e 503 quando não há capacidade disponível para a GPU solicitada.

API de Exportações#

Converta modelos para formatos otimizados como ONNX, TensorRT, CoreML e LiteRT para implantação na borda. Consulte a documentação de Implantaçã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á está em andamento retorna 409.

Formatos Suportados:

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

Obter Status de 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, carimbos de data/hora e — assim que concluído — um objeto file contendo size, downloadUrl e downloadFilename.

Cancelar ou Excluir 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 exclui uma concluída e seu arquivo. A resposta relata o que aconteceu:

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

API de Implantações#

Implante modelos em endpoints de inferência dedicados com verificações de integridade e monitoramento. Consulte a documentação de 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 Implantações#

GET /api/deployments/{owner}

SDK Python: client.deployments.list(owner)

Parâmetros de consulta:

Chamadores anônimos devem filtrar por um modelo público; listar um espaço de trabalho inteiro requer autenticação.

Criar Implantaçã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 Implantaçã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 Implantaçã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 implanta uma nova revisão preservando o ID da implantação, a região e a URL do endpoint; a revisão existente permanece ativa se a implantação falhar. O modelo de substituição deve ser um modelo concluído com pesos que sua chave possa acessar. Operações concluídas retornam 200 com status, ready ou stopped; operações ainda em andamento retornam 202 com deploying ou stopping.

Excluir Implantação#

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

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

Remove permanentemente o endpoint de inferência.

Verificação de Saúde#

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

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

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

Executar Inferência em uma Implantação#

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

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

Encaminha uma imagem ou vídeo através do endpoint dedicado. Os contratos de solicitação e resposta correspondem à inferência de modelo.

Formulário Multipart:

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 de solicitações, taxa de erro, latência média e p50/p95/p99) e timeSeries (solicitações, erros, latência, CPU, memória, contagem de instâncias). A resposta de minigráfico retorna requests24h, totalRequests, errorRate e avgLatencyMs.

Obter Logs#

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

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

Parâmetros de consulta:

API de Lixeira#

Visualizar, restaurar e excluir permanentemente projetos, datasets e modelos excluídos temporariamente (soft-deleted). Os itens são expurgados automaticamente após 30 dias. Consulte a documentação do Lixo.

Listar 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 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 colocados no lixo com ele, relatados como restoredModels.

Excluir Permanentemente#

DELETE /api/trash

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

Excluir um item:

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

Ou esvaziar todo o lixo:

{
    "all": true
}

A resposta relata deletedCount, além de cascadedModels e survivingDeployments quando relevante.

API de Upload#

Envie arquivos diretamente para o armazenamento em nuvem usando URLs assinadas. Concluir o envio de um modelo anexa seus pesos; concluir o envio de um arquivo compactado de dataset registra a sessão, que você passa em seguida para a ingestão de dataset. Consulte a documentação de Dados.

Obter URL de Upload Assinada#

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

Envie o arquivo com uma solicitação PUT para uploadUrl, usando o mesmo Content-Type que você declarou.

Concluir Upload#

POST /api/upload/complete

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

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

Resposta: success e um objeto file com size e contentType. Para modelos, isso anexa os pesos; para arquivos compactados de dataset, chame ingest em seguida para iniciar o processamento.

API de Integrações de Armazenamento#

Conecte contas somente leitura do Google Cloud Storage, Amazon S3 ou Azure Blob Storage e navegue por elas como fontes de dataset. Consulte 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. Credenciais nunca são retornadas.

Descobrir Locais#

POST /api/integrations/buckets/discover

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

Lista os buckets ou containers legíveis com as credenciais fornecidas, sem salvá-las.

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

Conectar Armazenamento#

POST /api/integrations/buckets

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

Mesmos formatos de credenciais da descoberta, mais um array obrigatório targets de 1 a 50 nomes de buckets ou containers. Retorna 201 com a integração salva. Credenciais temporárias do S3 (chaves de acesso ASIA) são rejeitadas.

Navegar pelos 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 próxima página.

Desconectar Armazenamento#

DELETE /api/integrations/buckets/{id}

SDK Python: client.storage_integrations.delete(id)

Remove as credenciais salvas sem excluir os dados do provedor. Datasets conectados continuam visíveis, mas seus arquivos permanecem indisponíveis até que a mesma conta de armazenamento seja reconectada. Requer acesso de administrador do espaço de trabalho.

API de Importação de Dataset#

Importe datasets de serviços de terceiros. Consulte a integração com o 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 de manobra storage. A chave de API do Roboflow é lida a partir do 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, utilizando os itens devolvidos 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): Matrizes imported, failed e skipped. As importações requerem capacidade de armazenamento, e cada conjunto de dados deve caber no limite de tamanho por importação do teu plano.

API de Conta#

Inspeciona a tua conta da Platform, chaves, armazenamento e perfis públicos. Vê a documentação de Definições.

Resumo da Conta#

GET /api/account/summary

SDK Python: client.account.summary()

Devolve o plano, saldo de créditos e contagens de recursos para o 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()

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

Verificar Utilização de 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 de Utilizador Público#

GET /api/users

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

Parâmetros de consulta:

Devolve o perfil público user com followerCount e, para chamadores 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 Faturamento#

Verifica a utilização do plano e o teu registo de créditos. Vê a documentação de Faturação.

Ver Plano e Utilização#

GET /api/billing/usage-summary

SDK Python: client.billing.usage_summary()

Devolve plan (ID, estado, ciclo de faturação, fim do período), metrics (limite e utilização de 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 (tal como purchase, training, monthly_grant ou refund), amountCents, balanceAfter, createdAt, um receiptUrl opcional e contexto do modelo para cobranças de treino. Os detalhes de faturação interna nunca são devolvidos.

API de Exploração#

Procura projetos públicos e conjuntos de dados partilhados pela comunidade. Vê a documentação do Explore.

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"

Python SDK#

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 de caminho posicionalmente, outras entradas como argumentos de palavra-chave e timeout e extra_headers opcionais por requisição.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    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 o código async/await, respostas com falha geram APIError com status_code, body e json analisados, e falhas de conexão geram APIConnectionError. Consulte o repositório do SDK para ver o README completo.

Integração Python#

Para fluxos de trabalho de treino e inferência, usa o pacote Python Ultralytics, que lida com autenticação, uploads e transmissão de métricas em tempo real automaticamente.

Instalação e configuração#

pip install "ultralytics>=8.4.120"

Verifique a instalação:

yolo check

Autenticação#

yolo login YOUR_API_KEY

Usando conjuntos de dados da plataforma#

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 de URI:

Enviando para a plataforma#

Envie resultados para um projeto na plataforma:

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 treinamento (tempo real)
• Pesos finais do modelo
• Gráficos de validação
• Saída da consola
• Métricas do sistema

Exemplos de API#

Carregar um modelo da plataforma:

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

FAQ#