Referência da REST API#

A Ultralytics Platform oferece uma REST API para acesso programático a conjuntos de dados, 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 está organizada em torno dos principais recursos da Platform:

Autenticação#

A maioria dos endpoints exige uma chave de API. Os endpoints que disponibilizam conteúdo público — como ler um conjunto de dados, projeto ou modelo público, listar imagens de conjuntos de dados públicos, executar inferência em um modelo público ou pesquisar em Explorar — também aceitam solicitações anônimas e simplesmente retornam mais dados quando uma chave é fornecida.

Obter uma chave de API#

1. Acesse Settings > API Keys
2. Clique em Add Key, mantenha Ultralytics como provedor, insira um nome e clique em Create Key
3. Copie a chave gerada

Consulte Chaves de API para ver instruções detalhadas.

Cabeçalho de autorização#

Inclua sua chave de API como um 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 usam:

https://platform.ultralytics.com/api

Caminhos dos recursos#

A maioria dos recursos é identificada pelos mesmos nomes legíveis por humanos que aparecem nos URLs da Platform, e não por IDs de banco de dados:

• {owner} é um nome de usuário pessoal ou identificador de espaço de trabalho de equipe: de 4 a 32 caracteres, alfanuméricos em minúsculas, 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}, {exportId} e {agentId} são IDs hexadecimais de 24 caracteres retornados pela API.
• Renomear um recurso por meio de PATCH altera simultaneamente o name de exibição e o nome do URL, e a resposta retorna o nome atual do URL para que você possa continuar usando-o.

Limites de taxa#

A API aplica limites por chave de API usando janelas deslizantes. Cada rota pertence a uma categoria, e cada categoria tem um contador independente; portanto, 20 solicitações de previsão não consomem sua cota padrão.

As rotas da plataforma exclusivas do navegador, como o checkout de cobrança e o gerenciamento de equipes, têm limites próprios que não se aplicam ao tráfego de chaves de API.

Quando o limite é atingido, a API retorna 429 com cabeçalhos e um corpo JSON:

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

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

Endpoints dedicados (ilimitados)#

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

Formato da resposta#

Respostas de sucesso#

As respostas são objetos JSON com campos específicos do recurso. Não há um envelope genérico: os endpoints de lista retornam uma coleção nomeada, geralmente acompanhada de contagens, e as mutações retornam os identificadores alterados.

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

As listas de recursos, as respostas de criação e clonagem e algumas leituras, como deployments, armazenamento e lixeira, também incluem region (us, eu ou ap), a região de armazenamento desse 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 conjuntos de dados#

Crie, explore e gerencie conjuntos de dados de imagens rotuladas para treinar modelos YOLO. Consulte a documentação de conjuntos de dados.

Listar conjuntos de dados#

GET /api/datasets/{owner}

SDK Python: client.datasets.list(owner)

Retorna os conjuntos de dados públicos do proprietário, além dos conjuntos de dados privados quando sua chave pode acessar 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 conjunto de dados#

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

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

Retorna o objeto completo do conjunto de dados sob uma chave dataset, incluindo classNames, splits, versions, source e o objeto metadata definido pelo usuário. Enquanto uma importação de 10.000 imagens ou mais está sendo processada, os editores também recebem processingProgress com stage, percent e, quando conhecidos, processed, total e objects (objetos na nuvem analisados).

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

Um slug dataset que já existe no workspace, inclusive na lixeira, retorna 409.

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 aceitos: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter, starred, blurFaces, kptSkeletonId (atribui um modelo de esqueleto de pose a um conjunto de dados de pose) e initializeClassNames (a atualização retorna 409, a menos que o conjunto de dados ainda não tenha classes ou anotações). Envie um objeto metadata vazio ({}) para limpar os metadados personalizados. As chaves dos metadados podem ter até 128 caracteres, e o objeto serializado, até 500.000 caracteres.

Resposta:

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

Renomear altera o nome do URL, então use o valor dataset retornado nas solicitações seguintes.

Eliminar conjunto de dados#

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

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

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

Clonar conjunto de dados#

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

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

Copia um conjunto de dados acessível, com suas imagens e rótulos, para 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. Conjuntos de dados vinculados a uma fonte de armazenamento conectada retornam 409 porque seus arquivos não são copiados.

Baixar uma exportação do conjunto de dados#

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

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

Retorna uma URL de download NDJSON assinada. Omita v para exportar o estado atual do conjunto de dados, reutilizando a exportação em cache quando nada tiver mudado desde sua geração.

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 conjunto de dados#

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

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

Cria uma versão numerada e imutável do conjunto de dados. Requer acesso de editor. Defina download como false para salvar a versão sem preparar um download NDJSON; nesse caso, downloadUrl é omitido. O SDK aceita download de ultralytics-platform>=0.1.73.

Corpo (opcional):

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

Resposta:

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

reused é true quando o conjunto de dados corresponde a uma versão existente, por exemplo, logo após restaurá-lo; nesse caso, essa versão é retornada e sua descrição é atualizada se você enviar uma.

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 salva, sem copiar os bytes das imagens.

Corpo:

{
    "version": 2
}

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

Comparar versões do conjunto de dados#

GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}

SDK Python: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)

Resposta (resumida):

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

summary aparece somente na primeira página e contém os totais exatos, além de um header que lista as classes adicionadas, removidas ou renomeadas e outros campos do conjunto de dados que diferem. O change de cada item é added, removed, modified (com o fields alterado) ou moved (divisão alterada), e labelsRemoved inclui os rótulos das imagens removidas. Se nextCursor estiver presente, passe-o como cursor para a próxima página. Com hash, a resposta é versions: a imagem conforme armazenada em cada versão, com seus rótulos e um imageUrl assinado. Qualquer ordem funciona; inverter base e head faz uma imagem removida ser indicada como adicionada. As comparações usam o limite de taxa padrão, e as solicitações sem hash também estão limitadas a 10 por minuto por usuário e conjunto de dados, independentemente da chave de API usada.

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; nesse caso, 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
}

Gerenciar classes#

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

Excluir classes (as anotações delas são excluídas 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]
}

As duas operações retornam success, os classNames e 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 imagens aleatoriamente entre as divisões. As três porcentagens devem totalizar 100.

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

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

Incorporações do conjunto de dados#

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

SDK do Python: 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 uma análise de incorporações na fila e retorna 202 com um jobId. DELETE cancela o trabalho ativo e retorna o ID do trabalho cancelado ou null.

Agrupamento de imagens#

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

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

Retorna a disposição 2D UMAP de uma análise concluída, paginada com offset e limit (padrão e máximo de 50.000). Cada entrada tem id, umapX, umapY, cluster, split, classIds, width, height, bytes, labelCount, labeled e missing. cluster é a ilha visual do ponto, classificada por tamanho (0 = maior, -1 = dispersa), ou null para disposições analisadas antes da adição do agrupamento.

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

Copiar ou mover imagens#

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

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

Copia até 1.000 imagens de outros conjuntos de dados para este, como faz a função copiar e colar do aplicativo, e retorna o número adopted.

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

Definir release ou classMapping preserva as etiquetas e divisões dos conjuntos de dados que podes editar: release: false copia imagens e release: true retira-as do conjunto de dados de origem. Se não especificares nenhum dos campos, são importadas imagens train sem etiquetas, o mesmo acontecendo ao copiar de uma origem só de leitura; mover a partir de uma origem só de leitura devolve 403. As imagens existentes são ignoradas; ao preservar etiquetas e divisões, os duplicados são verificados dentro da divisão de destino. As classes são correspondidas pelo nome, ignorando maiúsculas e minúsculas nos nomes com mais de dois caracteres; 422 devolve as classes de origem sem correspondência em unmatchedClasses, e classMapping mapeia cada uma para um índice de classe, um novo nome de classe ou null para remover as respetivas etiquetas. 409 indica que o destino é um conjunto de dados ligado ou que a origem ou o destino está ocupado. Ao preservar etiquetas e divisões, tarefas, canais de imagem, definições de pose ou escalas de profundidade incompatíveis também devolvem 409, mesmo para imagens sem etiquetas.

Ingerir dados do conjunto de dados#

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

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

Processa um upload concluído, um arquivo remoto ou uma origem de armazenamento conectada e adiciona os dados a um conjunto de dados existente. Forneça exatamente uma origem:

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 outro conjunto de dados.

Corpo (arquivo enviado):

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

Corpo (arquivo remoto ou NDJSON):

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

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

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

Corpo (anexaçã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. Em importações NDJSON, cada registro pode conter seu próprio objeto metadata, que tem precedência sobre uma entrada correspondente de imageMetadata. Os caminhos dos arquivos podem ter no máximo 1.024 caracteres, as chaves de metadados de nível superior podem ter no máximo 128 caracteres e cada objeto de metadados — assim como todo o mapa imageMetadata — pode ter no máximo 500.000 caracteres serializados.

Resposta (201):

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

import io
import zipfile
from pathlib import Path

import requests

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

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

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

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

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

API de imagens#

Inspecione, anote, mova e exclua imagens do conjunto de dados usando o 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 o objeto metadata (personalizado, definido pelo usuário), properties (nome do arquivo, hash, dimensões, divisão, contagens, registros de data e hora), labels e 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 — 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 }
}

Excluir 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 o modelo na imagem e retorna as anotações previstas. Elas não são salvas — grave os resultados usando PATCH /api/images/{imageId} quando estiver satisfeito com eles.

Resposta: success, predictions (objetos de anotação), confidences (pontuações alinhadas aos índices, vazio para modelos com prompts de classe), modelUsed, inferenceTime, para modelos com prompts de classe partial (true quando a saída truncada de um modelo generativo retornou apenas as caixas completas) e, para modelos de provedores pagos, um cost opcional (custo estimado do provedor em USD cobrado na sua chave do provedor, omitido quando não há estimativa disponível). Um modelo YOLO cujas classes não correspondam ao conjunto de dados retorna 422, assim como um modelo com prompts de classe usado em um conjunto de dados que não seja de detecção ou com menos de 1 ou mais de 200 classes, e um modelo de provedor pago sem uma chave do provedor salva em Configurações > Chaves de API no espaço de trabalho do conjunto de dados (code: missing_provider_api_key). Um erro do provedor inclui a mensagem do provedor: 422 quando o provedor responde com 400, 401, 403 ou 404 (uma chave, um modelo ou uma solicitação rejeitados), 429 para o limite de taxa e 503 para qualquer outro erro do provedor. Conjuntos de dados de profundidade retornam 400, e conjuntos de dados em armazenamento conectado ou com mais de 3 canais de imagem retornam 409.

Encontrar imagens semelhantes#

GET /api/images/{imageId}/similar

SDK Python: client.images.find_similar_images(image_id)

Retorna até 24 images visualmente semelhantes de conjuntos de dados públicos e dos seus conjuntos de dados pessoais e de equipe, cada um com score (0–1), um thumbnailUrl assinado e a origem dataset (owner, dataset, license). Imagens que já estão no conjunto de dados de origem e cópias da imagem consultada são excluídas. É necessária uma chave de API com acesso de visualização à imagem; uma imagem que ainda não foi incorporada é incorporada primeiro, e 503 significa que essa preparação falhou; tente novamente.

Anotar um conjunto de dados automaticamente#

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

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

Salva uma versão do conjunto de dados e, em seguida, coloca na fila uma execução que rotula as imagens sem rótulo do conjunto de dados usando o modelo e retorna 202. O corpo aceita os mesmos campos modelId, confidence, iou e classMapping do endpoint de imagem única, além de includeAnnotated (padrão false) para também anotar imagens que já têm rótulos. Um modelo com prompts de classe detecta as classes do conjunto de dados sem pontuações de confiança, e um modelo de provedor pago precisa de uma chave do provedor salva em Configurações > Chaves de API no espaço de trabalho do conjunto de dados (422, code: missing_provider_api_key, antes de a execução ser aprovada). Os rótulos existentes nunca são alterados, e a execução é cobrada pelas imagens que realmente processa. 402 significa que o saldo não cobre a estimativa; 409 significa que o conjunto de dados não está pronto, não tem mais imagens para anotar ou já tem uma execução em andamento; e 422 significa que o conjunto de dados não tem classes, ou que um modelo com prompts de classe recebeu um conjunto de dados que não é de detecção ou com menos de 1 ou mais de 200 classes: crie as classes com o endpoint de classes antes de chamar este endpoint, como faz a etapa Mapear classes do aplicativo 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; results dessa execução inclui partialImages quando a execução de um modelo generativo manteve apenas as caixas completas da saída truncada. DELETE (client.datasets.delete_batch(owner, dataset)) cancela uma execução em andamento ou conclui a cobrança e dispensa o resumo da execução concluída.

O mesmo endpoint desfoca rostos com "operation": "blur", confidence (padrão 0.25) e boxScale (0.5–1.5, padrão 1); imageId limita a execução a uma imagem. Ele não cria nenhuma versão nem altera os rótulos. Envie "preview": true para processar até seis imagens sem alterá-las e, em seguida, envie o jobId retornado como previewJobId com as mesmas configurações para aplicar as alterações; uma pré-visualização aplicada não pode ser reutilizada e retorna 409. Enquanto uma pré-visualização estiver pendente, passe o ID dela como previewJobId para DELETE para descartá-la.

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

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 outra divisão.

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

Conflitos de nome de arquivo ou conteúdo retornam 409 até você escolher uma conflictPolicy aplicada a todo o conjunto de skip, keep_both ou replace. A resposta informa 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 assinados de imagens#

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, thumbnails e depths (pré-visualizações dos alvos de profundidade para imagens de profundidade pareadas), todos indexados 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, um array models com resumos por modelo (status, métricas, épocas, pesos, argumentos de treinamento) e isOwner. Passe search (máximo de 200 caracteres) para filtrar models por nome do modelo ou metadados.

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.

Um slug project que já existe no workspace, inclusive na lixeira, retorna 409.

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 têm os mesmos limites de 128 caracteres para a chave e 500.000 caracteres para o objeto serializado que os metadados do conjunto de dados.

Excluir projeto#

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

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

Move o projeto e os respetivos modelos para o lixo, devolve cascadedModels e elimina permanentemente as respetivas implementações. Restaurar o projeto não restaura as implementações. 502 significa que a limpeza das implementações não foi concluída; os modelos permanecem no Lixo até a limpeza ser concluída.

Clonar projeto#

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

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

Clona um projeto acessível e os respetivos 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, transfere pesos, executa inferências 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 registo 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 aceites incluem name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError e starred. Passar apenas projectId move o modelo para outro projeto do mesmo proprietário; a resposta devolve o slug do modelo no projeto de destino, renamed: true se esse slug já estiver ocupado nesse projeto e 409 enquanto o modelo ainda estiver a ser treinado.

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

Os campos personalizados metadata são independentes dos campos controlados pelo treino, como trainArgs, environment e trainResults, e estão sujeitos aos mesmos limites de tamanho que os 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 e elimina permanentemente todas as implementações que o utilizam, incluindo as substituições pendentes. Restaurar o modelo não restaura as implementações.

Transferir ficheiros do modelo#

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

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

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

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

Encontrar imagens semelhantes às piores imagens de validação#

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

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

Devolve até 100 images, no mesmo formato de Encontrar imagens semelhantes, que se parecem com as imagens de validação em que esta execução de treino teve os piores resultados, excluindo imagens já presentes no conjunto de dados de treino. Passa hashes (separados por vírgulas, até 100) para pesquisar a partir de um subconjunto dessas piores imagens. Requer uma chave de API com acesso ao espaço de trabalho do modelo. A lista fica vazia quando a execução não registou resultados por imagem; 404 também significa que as piores imagens ainda não têm embeddings: executa primeiro embeddings do conjunto de dados no conjunto de dados de treino.

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

Executa a inferência#

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

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

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

Formulário multipart:

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. Os pedidos que excedem os limites de entrada do serviço devolvem 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 inclui shape, speed, results e, para tarefas de previsã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 indica o número de imagens, os nomes das classes do modelo, os tempos de execução das funções, a tarefa e as versões do serviço. Os caminhos internos dos modelos nunca são devolvidos.

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "classNames": ["person", "forklift"],
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Verificar o progresso do treino#

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

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

Devolve job, que contém o estado, o progresso das épocas, os tempos, os detalhes de computação, os argumentos de treino, as métricas das épocas e os detalhes de erro seguros, ou null quando o modelo nunca foi treinado. É possível consultar modelos em projetos públicos 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 a tarefa como cancelada. Devolve 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 de treino na nuvem.

Obter disponibilidade de GPU#

GET /api/training/gpu-availability

SDK Python: client.training.gpu_availability()

Devolve o estado atual da disponibilidade, identificado 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 devolve 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ções#

Converte modelos para formatos otimizados, como ONNX, TensorRT, CoreML e LiteRT, para implementação na periferia. 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

Cada formato só suporta as opções indicadas na coluna Argumentos da tabela de exportação abaixo: um valor não predefinido de batch, dynamic, opset, simplify, workspace ou optimize para um formato que não o suporte devolve 400. As exportações imx são apenas INT8 e estão disponíveis para modelos de deteção, segmentação, classificação e pose; os modelos YOLO26 e os tamanhos YOLOv8 ou YOLO11 diferentes de nano devolvem 400.

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

Formatos suportados:

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

nms=None usa por predefinição saídas brutas para NMS externo. Define nms=False para selecionar uma cabeça sem NMS disponível; os formatos não suportados recorrem ao respetivo caminho de saída nativo. As entradas nms acima identificam os 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)

Devolve o objeto export com status, format, args, gpuType (apenas TensorRT), carimbos temporais e — quando estiver concluída — um objeto file que contém 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 exportação concluída e o respetivo ficheiro. A resposta indica o que aconteceu:

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

API de implementações#

Implementa modelos em pontos finais de inferência dedicados, com verificações de estado e monitorização. Consulta a documentação de pontos finais.

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 espaço de trabalho inteiro, é necessário autenticar-se.

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)

Devolve o objeto deployment com status, statusMessage, region, serviceUrl, resources e o campo personalizado metadata, além de camera e cameraApplying para o proprietário.

Atualizar uma implementação#

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

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

Envia um destes corpos:

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

A mudança de nome define o valor deployment no URL para uma versão abreviada do novo nome, devolvida como deployment; o caminho antigo devolve 404 e serviceUrl mantém-se igual. Um objeto metadata vazio limpa os metadados personalizados. 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 da nova revisão falhar. O modelo de substituição tem de estar concluído e ter pesos acessíveis através da tua chave. A ação de câmara guarda uma câmara RTSP ou RTSPS na qual um endpoint pronto com recursos personalizados mantém a inferência em execução (consulta Câmara em segundo plano); "url": null remove-a, bem como o redimensionamento para o tamanho predefinido, e guardar uma câmara num endpoint de tamanho predefinido devolve 403. Uma alteração da câmara devolve 202 com status ready enquanto é aplicada: consulta a implementação até cameraApplying deixar de ser true e, em seguida, verifica camera; se a alteração falhar, a câmara anterior é mantida e statusMessage é definido. As operações concluídas devolvem 200 com status ready ou stopped; outras operações ainda em implementação devolvem 202 com deploying ou stopping.

Eliminar implantaçã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)

Envia uma solicitação ao endpoint e ativa-o, retornando healthy, latencyMs e o código status do serviço upstream.

Executar inferência numa 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 pedido e resposta correspondem aos da inferência de modelos. Os fluxos de câmaras não são encaminhados por proxy; envia-os para o URL do endpoint conforme descrito em Inferência com câmara em direto.

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 erros, latência média e p50/p95/p99) e timeSeries (solicitações, erros, latência, CPU, memória, número de instâncias). A resposta de gráfico compacto retorna requests24h (contagens horárias de solicitações; as horas sem solicitações são omitidas), totalRequests, errorRate e avgLatencyMs (a média das latências P95 horárias). Com view=overview, summary contém totalRequests, errorRate, e p95LatencyMs, enquanto timeSeries contém requests, errors e latencyP95.

Obter registos#

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

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

Parâmetros de consulta:

API de agentes#

Guarda e gere fluxos de trabalho de agentes. A API armazena definições de agentes; as execuções são iniciadas na tela Agents, onde https://platform.ultralytics.com/agents?workflow={id} abre um agente guardado. Os métodos do SDK Python precisam de ultralytics-platform>=0.1.74.

Todas as operações aceitam um parâmetro de consulta opcional owner com o nome de utilizador de um espaço de trabalho ao qual pertenças (predefinição: o teu próprio espaço de trabalho). Para listar, é necessário acesso de visualizador; para guardar e eliminar, é necessário acesso de editor.

Listar agentes#

GET /api/workflows

SDK Python: client.agents.list()

A resposta lista até 100 agentes em workflows, começando pelos atualizados mais recentemente, cada um com id, username, name, version, createdAt e updatedAt. Se pedires um id, também será retornado o graph do agente.

Guardar um agente#

PUT /api/workflows

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

Envia version: 0 para criar um agente. Para atualizar um agente, envia o respetivo id e o version retornado pela tua última listagem ou gravação; um version desatualizado retorna 409, por isso lista novamente o agente e tenta outra vez. Um grafo cujas ligações formem um ciclo ou atribuam a um bloco mais de uma entrada retorna 400.

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

A resposta retorna o agente id, o novo version e errors: blocos que a tela assinalaria, como um bloco Dataset sem conjunto de dados selecionado. O agente é guardado de qualquer forma. Consulta openapi.json para ver todos os tipos de bloco e as respetivas configurações.

Eliminar um agente#

DELETE /api/workflows?id={id}

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

Elimina o agente e cancela as respetivas execuções ativas. Os agentes eliminados não aparecem no Lixo e não podem ser restaurados.

API do lixo#

Consulta, restaura e elimina permanentemente projetos, conjuntos de dados e modelos eliminados logicamente. Os itens são removidos automaticamente após 30 dias. Consulta a documentação do lixo.

Listar lixo#

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. Com id, a resposta contém, em vez disso, resources: os modelos afetados e as implantações que seriam eliminadas permanentemente.

Restaurar item#

POST /api/trash

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

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

Ao restaurar um projeto, também são restaurados os modelos que foram movidos 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 e, quando aplicável, cascadedModels e survivingDeployments.

API de carregamento#

Carrega ficheiros diretamente para o armazenamento na nuvem usando URLs assinados. Ao concluir o carregamento de um modelo, os respetivos pesos são associados; ao concluir o carregamento de um arquivo de conjunto de dados, o arquivo é verificado e, em seguida, podes passar a sessão para a ingestão de conjuntos de dados, que também conclui o próprio carregamento se saltares essa etapa. 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" }
}

Carrega o ficheiro com uma solicitação PUT para uploadUrl, usando o mesmo Content-Type que declaraste e todos os cabeçalhos retornados em headers. Os URLs de carregamento de conjuntos de dados são válidos durante 12 horas e permitem apenas criar ficheiros: uma segunda solicitação PUT para o mesmo URL retorna 412, e uma solicitação PUT sem os cabeçalhos retornados devolve 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, isso anexa os pesos; para arquivos de conjuntos de dados, chama ingestão em seguida para iniciar o processamento.

Quando md5 é fornecido, o valor é comparado com o objeto armazenado. Uma incompatibilidade retorna 400; se a sessão ainda não estiver concluída, o ficheiro carregado também é eliminado e a sessão permanece incompleta. Nesse caso, solicita um novo URL assinado e carrega o ficheiro novamente. Uma sessão de conjunto de dados concluída pode ser concluída novamente enquanto o arquivo existir, mas conclusões concorrentes com resumos digitais diferentes retornam 409; as sessões de modelos são removidas ao serem concluídas. checksum é armazenado como metadado do ficheiro 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 consulta-as como fontes de conjuntos de dados. Consulta a documentação de integrações.

A descoberta e a ligação ao armazenamento exigem acesso de administrador do espaço de trabalho e um plano Pro ou Enterprise (403 caso contrário); a listagem de integrações e a consulta de objetos exigem acesso de editor.

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 acessíveis com as credenciais fornecidas, sem as 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 uma matriz targets obrigatória com 1 a 50 nomes de buckets ou contentores. Retorna 201 com a integração armazenada. As credenciais temporárias do S3 (chaves de acesso ASIA) são rejeitadas.

Consultar 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é voltares a ligar a mesma conta de armazenamento. 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 com Roboflow.

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

POST /api/integrations/roboflow/preview

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

Converte uma chave de API do Roboflow num plano de importação: detalhes do espaço de trabalho, newDatasets que seriam importados, contagens de projetos já importados (skippedCount), sem versão, não suportados e não resolvidos, bytesTotal e a margem disponível storage . A chave de API do Roboflow é lida no corpo da solicitação e não é guardada.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importar do Roboflow#

POST /api/integrations/roboflow/import

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

Coloca em fila tarefas de ingestão para até 500 versões selecionadas de projetos do Roboflow, 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): matrizes imported, failed e skipped. As importações requerem espaço disponível no armazenamento, e cada conjunto de dados tem de respeitar o limite de tamanho por importação do teu plano.

API da conta#

Consulta a tua conta Platform, as chaves, o armazenamento e os perfis públicos. Consulta a documentação de 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 referentes ao espaço de trabalho da chave. As solicitações autenticadas 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 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": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

usage informa as contagens de projects, datasets, models, images, annotations e deployments, e os bytes de storage. Um limit igual a -1 significa que o limite é ilimitado, e percent é uma percentagem inteira do limite.

Obter 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 quem estiver autenticado, 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#

Consulta o uso do plano e o teu extrato de créditos. Consulta a documentação de faturamento.

Consultar plano e uso#

GET /api/billing/usage-summary

SDK Python: client.billing.usage_summary()

Retorna plan (ID, estado, ciclo de faturamento, fim do período), metrics (limite e uso do armazenamento), trainingCredit, features, creditsCents e a quantidade de lugares.

Consultar 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 cobranças de treinamento. Os detalhes internos de faturamento nunca são retornados.

API do Explore#

Pesquisa projetos públicos e conjuntos de dados partilhados pela comunidade, ou pesquisa imagens pelo que mostram. Consulta a documentação de Explorar.

Pesquisar conteúdo público#

GET /api/explore/search

SDK Python: client.explore.search()

Parâmetros de consulta:

Resposta: projects, datasets e hasMore. type=images devolve as correspondências em images, começando pela melhor correspondência, cada uma com o respetivo dataset de origem e uma pontuação score de semelhança entre 0 e 1; requer q e pesquisa conjuntos de dados públicos, além dos teus conjuntos de dados e dos da tua equipa quando envias uma chave API.

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

SDK de Python#

ultralytics-platform é um cliente tipado de Python 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 como argumentos posicionais, os restantes dados de entrada 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:  # lê ULTRALYTICS_API_KEY ou a chave guardada por 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; respostas malsucedidas geram APIError com status_code, body e json analisado; 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 Ultralytics, que gere automaticamente a autenticação, os carregamentos e a transmissão de métricas em tempo real. No Python 3.11 ou superior, pip install ultralytics também instala o SDK ultralytics-platform. Quando model.train(project=...) tem como destino a Platform, os callbacks de treinamento transmitem eventos por meio de client.training.metrics() do SDK e pedem URLs de carregamento de checkpoints através de client.models.upload_checkpoint(), as operações POST /api/webhooks/training/metrics e POST /api/webhooks/models/upload do documento OpenAPI; não precisas de fazer chamadas manualmente.

Instalação e configuração#

A integração com a Platform 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")

# Treinar com o teu conjunto de dados na Platform
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

Formato do URI:

Enviar para a Platform#

Envia os resultados para um projeto da Platform:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Os resultados são sincronizados automaticamente com a Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

O que é sincronizado:

• Métricas de treinamento (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 anfitrião (nome do anfitrião, sistema operativo, Python, hardware, commit do git, linha de comandos)

Exemplos de API#

Carregar um modelo da Platform:

# O teu próprio modelo
model = YOLO("ul://username/project/model-name")

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

Executar inferência:

results = model("image.jpg")

# Aceder aos resultados
for r in results:
    boxes = r.boxes  # Caixas de deteção
    masks = r.masks  # Máscaras de segmentação
    keypoints = r.keypoints  # Pontos-chave da pose
    probs = r.probs  # Probabilidades de classificação

Exportar modelo:

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

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

# Exportar para CoreML
model.export(format="coreml", imgsz=640)  # usar imgsz=224 para classificação

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#