Referência da REST API#

Ultralytics Platform fornece uma API REST abrangente para acesso programático a conjuntos de dados, modelos, treinamentos e implantações.

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

Visão Geral da API#

A API é organizada em torno dos recursos principais da plataforma:

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

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

Autenticação#

As APIs de recursos utilizam autenticação por API-key, incluindo gerenciamento de classes e divisões de datasets, clonagem, treinamento, exportações, implantações e leituras de conta suportadas. Endpoints públicos suportam acesso anônimo onde indicado. Rotas de aplicação exclusivas para navegador estão excluídas.

Obter API Key#

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 API key em todas as requisições:

Authorization: Bearer YOUR_API_KEY

Exemplo#

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

Base URL#

Todos os endpoints da API usam:

https://platform.ultralytics.com/api

Limites de Taxa#

A API aplica limites baseados em janela deslizante e suportados pelo Upstash Redis por chave de API. Cada rota utiliza a categoria correspondente abaixo.

Quando limitada, a API devolve 429 com metadados de nova tentativa:

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

Limites por API Key#

Os limites de taxa são aplicados automaticamente com base no endpoint que está sendo chamado. Operações custosas possuem limites mais rigorosos para evitar abusos, enquanto operações CRUD padrão compartilham um limite padrão generoso:

Cada categoria possui um contador independente por API key. Por exemplo, fazer 20 requisições de previsão não afeta sua franquia padrão de 100 requisições/min.

Endpoints Dedicados (Ilimitados)#

Os pontos de extremidade dedicados não estão sujeitos aos limites de taxa de chaves da API da plataforma quando chamas o URL do ponto de extremidade diretamente (por exemplo, https://predict-abc123.run.app/predict). O débito depende então da configuração do serviço implantado.

Formato de Resposta#

Respostas de Sucesso#

As respostas retornam JSON com campos específicos do recurso:

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

Respostas de Erro#

{
    "error": "Dataset not found"
}

API de Datasets#

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

Listar Datasets#

GET /api/datasets

Parâmetros de consulta:

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

Resposta:

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

Obter Dataset#

GET /api/datasets/{datasetId}

Retorna os detalhes do conjunto de dados, incluindo nomes de classes, contagens de divisões e outras propriedades gerenciadas pela Platform. Os metadados personalizados são carregados separadamente a partir do endpoint de metadados abaixo.

Passa username quando {datasetId} for um slug de conjunto de dados em vez de um ID.

Criar Dataset#

POST /api/datasets

Corpo:

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

Resposta:

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

Atualizar Dataset#

PATCH /api/datasets/{datasetId}

Corpo (atualização parcial):

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

Envia um objeto metadata vazio ({}) para limpar os metadados personalizados. O objeto de metadados serializado é limitado a 500.000 caracteres, e cada chave de nível superior é limitada a 128 caracteres.

Obter Metadados do Conjunto de Dados#

GET /api/datasets/{datasetId}/metadata

Retorna o objeto de metadados personalizados e um conjunto selecionado de pares de campo/valor gerenciados pela Ultralytics e somente para leitura. Os metadados personalizados são omitidos intencionalmente das cargas úteis normais do conjunto de dados. Autenticação e acesso ao workspace do conjunto de dados são necessários.

Ícone do conjunto de dados#

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

Carrega um ícone WebP até 5 MB como campo de formulário multipart image ou remove o ícone atual.

Eliminar Dataset#

DELETE /api/datasets/{datasetId}

Elimina logicamente o conjunto de dados (movido para o lixo, recuperável durante 30 dias).

Clonar Dataset#

POST /api/datasets/{datasetId}/clone

Cria uma cópia de um dataset de workspace público, próprio ou editável com todas as imagens e labels.

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

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

Exportar Dataset#

GET /api/datasets/{datasetId}/export

Devolve uma resposta JSON com um URL de transferência assinado para a exportação mais recente do dataset.

Parâmetros de consulta:

Resposta:

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

Criar Versão do Dataset#

POST /api/datasets/{datasetId}/export

Cria um novo instantâneo de versão numerada do dataset. Isto requer acesso de Editor ou superior. A versão captura a contagem atual de imagens, contagem de classes, contagem de anotações e distribuição de divisões, gerando e armazenando em seguida uma exportação NDJSON imutável.

Corpo do Pedido:

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

Todos os campos são opcionais. O campo description é um rótulo fornecido pelo utilizador para a versão.

Resposta:

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

Atualizar Descrição da Versão#

PATCH /api/datasets/{datasetId}/export

Atualiza a descrição de uma versão existente. Isto requer acesso de Editor ou superior.

Corpo do Pedido:

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

Resposta:

{
    "ok": true
}

Restaurar Versão do Dataset#

POST /api/datasets/{datasetId}/restore

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

{
    "version": 2
}

Obter Estatísticas de Classe#

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

Devolve a distribuição de classes, mapa de calor de localização e estatísticas de dimensão. Os resultados são colocados em cache até 5 minutos.

Resposta:

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

Gerir Classes#

Mesclar classes (reassinar anotações de classes de origem para uma de destino e, em seguida, remover as origens):

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

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

IDs de classe são posicionais, portanto, a mesclagem não é idempotente. Recupere o dataset novamente antes de tentar novamente.

Eliminar classes:

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

{
    "classIds": [2, 4]
}

Redistribuir Divisões#

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

Reatribua imagens aleatoriamente entre as divisões de treino, validação e teste. As porcentagens devem totalizar 100.

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

Embeddings do Conjunto de Dados#

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

O GET devolve o resumo atual da análise UMAP e o estado do trabalho ativo; o POST coloca na fila um trabalho de análise de embeddings; o DELETE cancela o trabalho ativo.

Agrupamento de Imagens#

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

Devolve o layout 2D UMAP e os metadados por imagem para a vista de dispersão de agrupamento (paginado e com limite de taxa).

Obter Modelos Treinados no Dataset#

GET /api/datasets/{datasetId}/models

Devolve os modelos que foram treinados usando este dataset.

Resposta:

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

Auto-anotar Dataset#

POST /api/datasets/{datasetId}/predict

Executa inferência YOLO nas imagens do dataset para gerar automaticamente anotações. Usa um modelo selecionado para prever rótulos para imagens não anotadas.

Corpo:

Ingestão de Dataset#

POST /api/datasets/ingest

Cria uma tarefa de ingestão de conjuntos de dados para um conjunto de dados existente. O conjunto de dados de destino é sempre passado como datasetId no corpo JSON, e não no caminho do URL.

O corpo do pedido requer datasetId mais exatamente um de sessionId (uma sessão de carregamento de um arquivo carregado) ou sourceUrl (um URL remoto ZIP, TAR, TAR.GZ, TGZ ou NDJSON). Adiciona o opcional targetSplit (train, val ou test) para substituir a estrutura de divisões do arquivo. Para anexar metadados personalizados, utiliza imageMetadata, indexado pelo caminho exato relativo ao arquivo de cada imagem ou pelo valor NDJSON file.

Para arquivos carregados, a sessão de carregamento já está associada ao conjunto de dados pelo assetId passado para POST /api/upload/signed-url; a ingestão valida que assetId corresponde ao corpo datasetId. Entradas opcionais de classMapping mapeiam cada nome de classe de entrada para um índice de classe existente baseado em zero, um nome de classe a reutilizar ou criar, ou null para ignorar a classe. Para importações remotas de sourceUrl, cria primeiro o conjunto de dados e, em seguida, passa o seu datasetId para a ingestão.

Corpo (arquivo enviado):

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

Corpo (uma ou várias imagens com metadados):

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

As imagens locais utilizam o fluxo de carregamento de arquivos existente, quer o arquivo contenha uma imagem quer várias. A chave deve corresponder ao caminho normalizado dentro do arquivo, incluindo pastas. Para importações NDJSON, cada registo de imagem pode conter o seu próprio objeto metadata. O metadata local do registo tem precedência sobre uma entrada correspondente em imageMetadata.

Os metadados são em formato JSON e suportam valores aninhados. Os caminhos de arquivos estão limitados a 1.024 caracteres, as chaves de metadados de nível superior a 128 caracteres e cada objeto de metadados a 500.000 caracteres serializados. O mapa completo imageMetadata ou os metadados efetivos combinados numa importação NDJSON também estão limitados a 500.000 caracteres serializados. Estas restrições estão incluídas no esquema OpenAPI interativo.

import io
import zipfile
from pathlib import Path

import requests

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

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

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

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

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

Corpo (arquivo remoto ou NDJSON):

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

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

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

Resposta:

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

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

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

Imagens do Dataset#

Listar Imagens#

GET /api/datasets/{datasetId}/images

Parâmetros de consulta:

Obter Imagens Selecionadas#

POST /api/datasets/{datasetId}/images

Retorna o mesmo formato de imagem para até 1.000 IDs de imagem fornecidos. Aceita os mesmos controles de consulta de URL e label da operação de listagem.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Obter URLs de Imagens Assinados#

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

Obtém URLs assinados para um lote de hashes de imagem (para exibição no navegador).

Eliminar Imagem#

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

Obter Rótulos da Imagem#

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

Devolve anotações e nomes de classes para uma imagem específica.

Atualizar Rótulos da Imagem#

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

Corpo:

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

Operações em Lote de Imagens#

Mover imagens entre divisões (train/val/test) dentro de um dataset:

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

Eliminar imagens em lote:

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

API de Projetos#

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

Listar Projetos#

GET /api/projects

Parâmetros de consulta:

Obter Projeto#

GET /api/projects/{projectId}

Criar Projeto#

POST /api/projects

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

Atualizar Projeto#

PATCH /api/projects/{projectId}

Corpo (atualização parcial):

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

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

Obter Metadados do Projeto#

GET /api/projects/{projectId}/metadata

Retorna o objeto de metadados personalizados e pares de campo/valor gerenciados pela Ultralytics e somente para leitura. Autenticação e acesso ao workspace do projeto são necessários.

Eliminar Projeto#

DELETE /api/projects/{projectId}

Elimina logicamente o projeto (movido para o lixo).

Clonar Projeto#

POST /api/projects/{projectId}/clone

Clona um projeto de espaço de trabalho público, próprio ou editável e respetivos modelos para a tua conta ou espaço de trabalho. Um corpo JSON opcional aceita substituições de name, slug, description, visibility, license e do destino owner.

Ícone do Projeto#

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

Carrega um ícone WebP até 5 MB como campo de formulário multipart image ou remove o ícone atual.

API de Modelos#

Gere modelos YOLO treinados — visualiza métricas, transfere pesos, executa inferência e exporta para outros formatos. Consulta a documentação de modelos.

Listar Modelos#

GET /api/models

Parâmetros de consulta:

Listar Modelos Concluídos#

GET /api/models/completed

Devolve até 1.000 modelos com pesos utilizáveis em todos os projetos para treino e implantação. Passa owner para um espaço de trabalho.

Obter Modelo#

GET /api/models/{modelId}

Criar Modelo#

POST /api/models

Corpo JSON:

Atualizar Modelo#

PATCH /api/models/{modelId}

Corpo (atualização parcial):

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

Envia um objeto metadata vazio ({}) para limpá-lo. Os metadados personalizados do modelo são separados das informações do modelo pertencentes ao treinamento, detalhes do ambiente e argumentos de treinamento, e usam os mesmos limites de objeto serializado e chave de nível superior que os metadados do conjunto de dados.

Obter Metadados do Modelo#

GET /api/models/{modelId}/metadata

Retorna o objeto de metadados personalizados e pares de campo/valor gerenciados pela Ultralytics e somente para leitura. Autenticação e acesso ao workspace do modelo são necessários.

Excluir Modelo#

DELETE /api/models/{modelId}

Baixar Arquivos de Modelo#

GET /api/models/{modelId}/files

Retorna URLs de download assinadas para arquivos de modelo.

Clonar Modelo#

POST /api/models/{modelId}/clone

Clone um modelo de workspace público, próprio ou editável para um dos seus projetos.

Corpo:

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

Rastrear Download#

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

Rastreie análises de download de modelo.

Executar inferência#

POST /api/models/{modelId}/predict

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

Formulário Multipart:

Fornece file ou source. O tamanho máximo de carregamento é 100 MB.

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

Resposta:

As respostas contêm shape, speed, results por imagem e dados opcionais de mapas de píxeis densos (um mapa de classes semânticas ou um mapa de profundidade onde depth = pixel × max / divisor — divisor 255 para o mapa predefinido de 8 bits, 65535 com bits=12|16), além de metadata com a contagem de imagens, o tempo de execução da função, a tarefa e as versões dos serviços. Os caminhos internos dos modelos nunca são devolvidos.

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

API de Treinamento#

Inicia o treino YOLO em GPUs na cloud (26 tipos de GPU desde a RTX 2000 Ada até à B300) e monitoriza o progresso em tempo real. Consulta a documentação de treino na cloud.

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

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

Iniciar Treinamento#

POST /api/training/start

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

Obter Disponibilidade de GPU#

GET /api/training/gpu-availability

Devolve o estado atual do stock de GPU (High, Medium, Low ou null) indexado pelo ID do tipo de GPU. Público, sem necessidade de autenticação; em cache durante 5 minutos.

Obter Status de Treinamento#

GET /api/models/{modelId}/training

Retorna o status atual do trabalho de treinamento, métricas, progresso, tempo, detalhes da GPU e erros. Projetos públicos são acessíveis sem autenticação; projetos privados e compartilhados exigem uma API key com acesso.

Cancelar Treinamento#

DELETE /api/models/{modelId}/training

Finaliza a instância de computação em execução e marca o trabalho como cancelado.

API de Implantações#

Implanta modelos em pontos de extremidade de inferência dedicados com verificações de estado e monitorização. As novas implantações utilizam a redução a zero por predefinição, e a API aceita um objeto opcional resources. Consulta a documentação de pontos de extremidade.

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

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

Listar Implantações#

GET /api/deployments

Parâmetros de consulta:

Criar Implantação#

POST /api/deployments

Corpo:

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

Cria um endpoint de inferência dedicado na região especificada. O endpoint é globalmente acessível através de uma URL única.

Obter Implantação#

GET /api/deployments/{deploymentId}

Excluir Implantação#

DELETE /api/deployments/{deploymentId}

Iniciar Implantação#

POST /api/deployments/{deploymentId}/start

Retome uma implantação parada.

Parar Implantação#

POST /api/deployments/{deploymentId}/stop

Interrompe o atendimento de solicitações definindo as instâncias mínima e máxima do serviço como zero.

Verificação de Saúde#

GET /api/deployments/{deploymentId}/health

Retorna o status de saúde do endpoint de implantação.

Executar Inferência na Implantação#

POST /api/deployments/{deploymentId}/predict

Envie uma imagem diretamente para um endpoint de implantação para inferência. Funcionalmente equivalente à predição de modelo, mas roteado através do endpoint dedicado para menor latência.

Formulário Multipart:

Fornece file ou source. A resposta utiliza o mesmo contrato de imagem e metadados que a predição do modelo e nunca devolve o caminho interno do modelo.

Obter Métricas#

GET /api/deployments/{deploymentId}/metrics

Retorna contagens de solicitações, latência e métricas de taxa de erro com dados de sparkline.

Parâmetros de consulta:

Obter Logs#

GET /api/deployments/{deploymentId}/logs

Parâmetros de consulta:

API de Exportação#

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

Listar Exportações#

GET /api/exports

Parâmetros de consulta:

Criar Exportação#

POST /api/exports

Corpo:

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

Formatos Suportados:

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

Obter Status de Exportação#

GET /api/exports/{exportId}

Cancelar Exportação#

DELETE /api/exports/{exportId}

Rastrear Download de Exportação#

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

API de Atividade#

Consulta um feed de ações recentes na tua conta — execuções de treino, carregamentos e muito mais. Consulta a documentação de atividade.

Listar Atividade#

GET /api/activity

Parâmetros de consulta:

Marcar Eventos como Vistos#

POST /api/activity/mark-seen

Corpo:

{
    "all": true
}

Ou passe IDs específicos:

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

Passa o parâmetro de consulta opcional owner para marcar eventos num espaço de trabalho.

Arquivar Eventos#

POST /api/activity/archive

Corpo:

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

Ou passe IDs específicos:

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

Passa o parâmetro de consulta opcional owner para arquivar ou restaurar eventos do espaço de trabalho.

API de Lixeira#

Visualiza e restaura itens eliminados. Os itens são removidos permanentemente após 30 dias. Consulta a documentação do lixo.

Listar Lixeira#

GET /api/trash

Parâmetros de consulta:

Restaurar Item#

POST /api/trash

Corpo:

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

Excluir Item Permanentemente#

DELETE /api/trash

Corpo:

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

Esvaziar Lixeira#

DELETE /api/trash/empty

Exclui permanentemente todos os itens da lixeira.

API de Faturamento#

Verifica o teu saldo de créditos, a utilização do plano e o histórico de transações. Consulta a documentação de faturamento.

Os pontos de extremidade de saldo e transações aceitam um parâmetro de consulta opcional owner com o nome de utilizador do proprietário do espaço de trabalho.

Obter Saldo#

GET /api/billing/balance

Resposta:

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

Obter Resumo de Uso#

GET /api/billing/usage-summary

Retorna detalhes do plano, limites e métricas de uso.

Obter Transações#

GET /api/billing/transactions

Retorna o histórico de transações (mais recentes primeiro).

As transações incluem campos contábeis voltados ao cliente, como valor, saldo resultante, data, contexto de modelo opcional e URL de recibo. Notas internas, IDs de pagamento/reembolso Stripe e chaves de idempotência não são retornados.

API de Armazenamento#

Verifique a análise do uso do seu armazenamento por categoria (datasets, modelos, exportações) e veja seus itens maiores.

Obter Informações de Armazenamento#

GET /api/storage

Parâmetros de consulta:

Resposta:

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

Integrações de Armazenamento em Nuvem#

Conecte e navegue em integrações de armazenamento GCS, S3 ou Azure Blob somente leitura:

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

Todas as quatro operações aceitam o parâmetro de consulta opcional owner para um espaço de trabalho. A navegação de objetos também aceita o parâmetro obrigatório target mais os parâmetros de consulta opcionais prefix e o fornecedor cursor. Os corpos dos pedidos de ligação e descoberta utilizam os esquemas de credenciais do fornecedor na referência OpenAPI interativa; as credenciais nunca são devolvidas.

API de Upload#

Carrega ficheiros diretamente para o armazenamento na cloud utilizando URLs assinados para transferências rápidas e fiáveis. A conclusão de um carregamento de modelo anexa os respetivos pesos. A conclusão de um carregamento de arquivo de conjunto de dados regista a sessão; passa esse sessionId para POST /api/datasets/ingest para iniciar o processamento. Consulta a documentação de dados.

Obter URL de Upload Assinada#

POST /api/upload/signed-url

Solicite uma URL assinada para fazer o upload de um arquivo diretamente para o armazenamento em nuvem. A URL assinada contorna o servidor da API para transferências de arquivos grandes.

Corpo:

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

Resposta:

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

Concluir Upload#

POST /api/upload/complete

Notifica a plataforma de que o carregamento de um ficheiro foi concluído. Para modelos, isto anexa os pesos carregados. Para arquivos de conjuntos de dados, isto verifica e regista a sessão de carregamento; chama POST /api/datasets/ingest a seguir para iniciar o processamento do conjunto de dados.

Corpo:

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

API de Integrações#

Importa conjuntos de dados de serviços de terceiros. Consulta a documentação de integrações.

Pré-visualizar Importação do Roboflow#

POST /api/integrations/roboflow/preview

Resolve uma API key do Roboflow para um plano de importação em massa: informações do workspace, quais projetos seriam importados recentemente, contagem de versões já importadas (ignoradas) e tipos de projeto não suportados. A API key do Roboflow é passada no corpo e não é guardada.

Importar do Roboflow#

POST /api/integrations/roboflow/import

Coloca na fila trabalhos de ingestão de conjuntos de dados para importar os projetos Roboflow selecionados para o teu workspace. Requer capacidade de armazenamento e cada conjunto de dados deve cumprir o limite de tamanho por importação do teu plano.

API de Chaves de API#

Gere as tuas chaves de API para acesso programático. Consulta a documentação de chaves de API.

Listar Chaves de API#

GET /api/api-keys

Os clientes autenticados com chave de API recebem metadados da chave, nunca valores de chaves existentes desencriptados. Uma chave recém-criada é devolvida uma vez por POST /api/api-keys.

Passa o parâmetro de consulta opcional owner para gerir chaves para um espaço de trabalho onde tens acesso de editor.

Criar Chave de API#

POST /api/api-keys

Corpo:

{
    "name": "training-server"
}

Excluir Chave de API#

DELETE /api/api-keys

Parâmetros de consulta:

Exemplo:

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

API de Equipes e Membros#

Cria espaços de trabalho de equipa, convida membros e gere funções para colaboração. Consulta a documentação de equipas.

Listar Equipes#

GET /api/teams

Criar Equipe#

POST /api/teams/create

Corpo:

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

Listar Membros#

GET /api/members

Retorna os membros do espaço de trabalho atual.

Convidar Membro#

POST /api/members

Corpo:

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

Atualizar Papel de Membro#

PATCH /api/members/{userId}

Remover Membro#

DELETE /api/members/{userId}

Transferir Propriedade#

POST /api/members/transfer-ownership

API de Exploração#

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

Pesquisar Conteúdo Público#

GET /api/explore/search

Parâmetros de consulta:

Dados da Barra Lateral#

GET /api/explore/sidebar

Retorna conteúdo curado para a barra lateral de Exploração.

APIs de Usuário e Configurações#

Gere o teu perfil, chaves de API, utilização de armazenamento e espaços de trabalho de equipa. Consulta a documentação de definições.

Resumo da Conta#

GET /api/account/summary

Retorna o plano da conta autenticada, saldo de crédito, contagens de recursos e workspaces de equipe.

Obter Usuário por Nome de Usuário#

GET /api/users

Parâmetros de consulta:

Seguir ou Deixar de Seguir Usuário#

PATCH /api/users

Corpo:

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

Verificar Disponibilidade de Nome de Usuário#

GET /api/username/check

Parâmetros de consulta:

Configurações#

GET /api/settings
POST /api/settings

Obter ou atualizar configurações do perfil de usuário (nome de exibição, bio, links sociais, etc.).

Ícone do Workspace#

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

Carrega um ícone de perfil/espaço de trabalho WebP até 5 MB como campo de formulário multipart image ou remove-o. Passa o opcional owner para um espaço de trabalho de equipa.

Integração Python#

Para uma integração mais fácil, use o pacote Python da Ultralytics, que lida automaticamente com autenticação, uploads e streaming de métricas em tempo real.

Instalação e configuração#

pip install "ultralytics>=8.4.104"

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#

Como faço para paginar resultados grandes?#

A maioria dos pontos de extremidade utiliza um parâmetro limit para controlar quantos resultados são devolvidos por pedido:

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

Os pontos de extremidade de Atividade e Lixo também suportam um parâmetro page para paginação baseada em páginas:

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

O endpoint de busca Explore usa offset em vez de page, com um tamanho de página fixo de 20:

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

Posso usar a API sem um SDK?#

As operações REST públicas documentadas acima estão disponíveis sem o SDK do Python. O SDK é um wrapper de conveniência que adiciona recursos como streaming de métricas em tempo real e uploads automáticos de modelos. Podes explorar o contrato legível por máquina interativamente em platform.ultralytics.com/api/docs; os fluxos de conta exclusivos para sessões de navegador permanecem na interface da Platform.

Existem bibliotecas de cliente de API?#

Usa o pacote Python do Ultralytics ou faz solicitações HTTP diretas a partir de qualquer linguagem.

Como lido com limites de taxa?#

Usa o cabeçalho Retry-After da resposta 429 para esperar o tempo certo:

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise RuntimeError("Rate limit exceeded")

Como encontro o ID do meu modelo ou conjunto de dados?#

Os IDs de recursos são retornados pelas respostas de API de criação, listagem e obtenção. As URLs das páginas da plataforma usam slugs legíveis por humanos, e não IDs de banco de dados:

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

Usa os endpoints de lista para encontrar o _id correspondente para um modelo, conjunto de dados, projeto, implantação ou outro recurso.