Link to this sectionReferência da REST API#

A Ultralytics Platform fornece uma REST API abrangente para acesso programático a datasets, modelos, treinamentos e implementações.

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

Link to this sectionVisã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

Link to this sectionAutenticaçã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.

Link to this sectionObter API Key#

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

Veja API Keys para instruções detalhadas.

Link to this sectionCabeçalho de Autorização#

Inclua sua API key em todas as requisições:

Authorization: Bearer YOUR_API_KEY

Link to this sectionExemplo#

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

Link to this sectionBase URL#

Todos os endpoints da API usam:

https://platform.ultralytics.com/api

Link to this sectionLimites 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 retorna 429 com metadados de nova tentativa:

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

Link to this sectionLimites 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.

Link to this sectionEndpoints Dedicados (Ilimitados)#

Endendpoints dedicados não estão sujeitos aos limites de taxa da chave de API da plataforma quando chamas a URL do endpoint diretamente (por exemplo, https://predict-abc123.run.app/predict). O rendimento depende então da configuração do serviço implantado.

Link to this sectionFormato de Resposta#

Link to this sectionRespostas de Sucesso#

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

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

Link to this sectionRespostas de Erro#

{
    "error": "Dataset not found"
}

Link to this sectionAPI de Datasets#

Cria, navega e gere datasets de imagens rotuladas para treinar modelos YOLO. Consulta a documentação de Datasets.

Link to this sectionListar 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"
}

Link to this sectionObter Dataset#

GET /api/datasets/{datasetId}

Devolve detalhes completos do dataset, incluindo metadados, nomes de classes e contagens de divisões.

Passe username quando {datasetId} for um slug de dataset em vez de um ID.

Link to this sectionCriar Dataset#

POST /api/datasets

Corpo:

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

Resposta:

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

Link to this sectionAtualizar Dataset#

PATCH /api/datasets/{datasetId}

Corpo (atualização parcial):

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

Link to this sectionÍcone do conjunto de dados#

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

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

Link to this sectionEliminar Dataset#

DELETE /api/datasets/{datasetId}

Elimina suavemente o dataset (movido para o lixo, recuperável durante 30 dias).

Link to this sectionClonar 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"
}

Link to this sectionExportar 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
}

Link to this sectionCriar 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=..."
}

Link to this sectionAtualizar 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
}

Link to this sectionRestaurar 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
}

Link to this sectionObter 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
}

Link to this sectionGerir 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]
}

Link to this sectionRedistribuir 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
}

Link to this sectionEmbeddings 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.

Link to this sectionAgrupamento 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).

Link to this sectionObter 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
}

Link to this sectionAuto-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:

Link to this sectionIngestão de Dataset#

POST /api/datasets/ingest

Cria um trabalho de ingestão de dados para um conjunto de dados existente. O conjunto de dados alvo é sempre passado como datasetId no corpo JSON, não no caminho da URL.

O corpo da requisição exige o datasetId e exatamente um dos seguintes: sessionId (uma sessão de upload de arquivo enviado) ou sourceUrl (uma URL remota de ZIP, TAR, TAR.GZ, TGZ ou NDJSON). Adiciona o targetSplit opcional (train, val ou test) para sobrescrever a estrutura de divisão do arquivo.

Para arquivos enviados, a sessão de upload já está vinculada ao conjunto de dados pelo assetId passado para POST /api/upload/signed-url; a ingestão valida se o assetId corresponde ao datasetId no corpo. 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 ser reutilizado ou criado, ou null para ignorar a classe. Para importações remotas via sourceUrl, crie o conjunto de dados primeiro e, em seguida, passe seu datasetId para a ingestão.

Corpo (arquivo enviado):

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

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

Link to this sectionImagens do Dataset#

Link to this sectionListar Imagens#

GET /api/datasets/{datasetId}/images

Parâmetros de consulta:

Link to this sectionObter 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"]
}

Link to this sectionObter 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).

Link to this sectionEliminar Imagem#

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

Link to this sectionObter Rótulos da Imagem#

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

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

Link to this sectionAtualizar 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] }
    ]
}

Link to this sectionOperaçõ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

Link to this sectionAPI de Projetos#

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

Link to this sectionListar Projetos#

GET /api/projects

Parâmetros de consulta:

Link to this sectionObter Projeto#

GET /api/projects/{projectId}

Link to this sectionCriar 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"
  }' \
  https://platform.ultralytics.com/api/projects

Link to this sectionAtualizar Projeto#

PATCH /api/projects/{projectId}

Link to this sectionEliminar Projeto#

DELETE /api/projects/{projectId}

Elimina suavemente o projeto (movido para o lixo).

Link to this sectionClonar Projeto#

POST /api/projects/{projectId}/clone

Clona um projeto de workspace público, próprio ou editável e seus modelos para sua conta ou workspace. Um corpo JSON opcional aceita substituições de name, slug, description, visibility, license e owner de destino.

Link to this sectionÍcone do Projeto#

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

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

Link to this sectionAPI de Modelos#

Gerencie modelos YOLO treinados — visualize métricas, baixe pesos, execute inferência e exporte para outros formatos. Veja a documentação de Modelos.

Link to this sectionListar Modelos#

GET /api/models

Parâmetros de consulta:

Link to this sectionListar Modelos Concluídos#

GET /api/models/completed

Retorna até 1.000 modelos com pesos utilizáveis em todos os projetos para treinamento e implantação. Passe owner para um workspace.

Link to this sectionObter Modelo#

GET /api/models/{modelId}

Link to this sectionCriar Modelo#

POST /api/models

Corpo JSON:

Link to this sectionAtualizar Modelo#

PATCH /api/models/{modelId}

Link to this sectionExcluir Modelo#

DELETE /api/models/{modelId}

Link to this sectionBaixar Arquivos de Modelo#

GET /api/models/{modelId}/files

Retorna URLs de download assinadas para arquivos de modelo.

Link to this sectionClonar 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"
}

Link to this sectionRastrear Download#

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

Rastreie análises de download de modelo.

Link to this sectionExecutar 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:

Forneça file ou source. O tamanho máximo de upload é 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 mapa de pixels denso (um mapa de classes semânticas ou um mapa de profundidade onde depth = pixel × max / divisor — divisor 255 para o mapa padrão de 8 bits, 65535 com bits=12|16), além de metadata com contagem de imagens, tempo de execução da função, tarefa e versões do serviço. Caminhos de modelos internos nunca são retornados.

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

Link to this sectionAPI de Treinamento#

Inicia o treino do YOLO em GPUs na cloud (26 tipos de GPU, desde 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

Link to this sectionIniciar 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

Link to this sectionObter Disponibilidade de GPU#

GET /api/training/gpu-availability

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

Link to this sectionObter 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.

Link to this sectionCancelar Treinamento#

DELETE /api/models/{modelId}/training

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

Link to this sectionAPI de Implantações#

Implante modelos em endpoints de inferência dedicados com verificações de saúde e monitoramento. Novas implantações usam scale-to-zero por padrão, e a API aceita um objeto resources opcional. Veja a documentação de Endpoints.

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

Link to this sectionListar Implantações#

GET /api/deployments

Parâmetros de consulta:

Link to this sectionCriar 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.

Link to this sectionObter Implantação#

GET /api/deployments/{deploymentId}

Link to this sectionExcluir Implantação#

DELETE /api/deployments/{deploymentId}

Link to this sectionIniciar Implantação#

POST /api/deployments/{deploymentId}/start

Retome uma implantação parada.

Link to this sectionParar 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.

Link to this sectionVerificação de Saúde#

GET /api/deployments/{deploymentId}/health

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

Link to this sectionExecutar 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:

Forneça file ou source. A resposta usa o mesmo contrato de imagem e metadados que a predição de modelo e nunca retorna o caminho do modelo interno.

Link to this sectionObter 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:

Link to this sectionObter Logs#

GET /api/deployments/{deploymentId}/logs

Parâmetros de consulta:

Link to this sectionAPI de Exportação#

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

Link to this sectionListar Exportações#

GET /api/exports

Parâmetros de consulta:

Link to this sectionCriar 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:

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

{% set integrations_path = "../../integrations" %}

{%set integrations_path = integrations_path or "../integrations" %}

Link to this sectionObter Status de Exportação#

GET /api/exports/{exportId}

Link to this sectionCancelar Exportação#

DELETE /api/exports/{exportId}

Link to this sectionRastrear Download de Exportação#

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

Link to this sectionAPI de Atividade#

Visualize um feed de ações recentes na sua conta — execuções de treinamento, uploads e muito mais. Consulte a documentação de atividade.

Link to this sectionListar Atividade#

GET /api/activity

Parâmetros de consulta:

Link to this sectionMarcar Eventos como Vistos#

POST /api/activity/mark-seen

Corpo:

{
    "all": true
}

Ou passe IDs específicos:

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

Passe o parâmetro de consulta opcional owner para marcar eventos em um workspace.

Link to this sectionArquivar Eventos#

POST /api/activity/archive

Corpo:

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

Ou passe IDs específicos:

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

Passe o parâmetro de consulta opcional owner para arquivar ou restaurar eventos do workspace.

Link to this sectionAPI de Lixeira#

Visualize e restaure itens excluídos. Os itens são removidos permanentemente após 30 dias. Consulte a documentação da lixeira.

Link to this sectionListar Lixeira#

GET /api/trash

Parâmetros de consulta:

Link to this sectionRestaurar Item#

POST /api/trash

Corpo:

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

Link to this sectionExcluir Item Permanentemente#

DELETE /api/trash

Corpo:

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

Link to this sectionEsvaziar Lixeira#

DELETE /api/trash/empty

Exclui permanentemente todos os itens da lixeira.

Link to this sectionAPI de Faturamento#

Verifique seu saldo de crédito, uso do plano e histórico de transações. Consulte a documentação de faturamento.

Os endpoints de saldo e transação aceitam um parâmetro de consulta owner opcional com o nome de usuário do proprietário do espaço de trabalho.

Link to this sectionObter Saldo#

GET /api/billing/balance

Resposta:

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

Link to this sectionObter Resumo de Uso#

GET /api/billing/usage-summary

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

Link to this sectionObter 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.

Link to this sectionAPI de Armazenamento#

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

Link to this sectionObter 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"
            }
        ]
    }
}

Link to this sectionIntegraçõ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 workspace. A navegação de objetos também aceita target obrigatório mais parâmetros de consulta opcionais prefix e cursor do provedor. Os corpos de solicitação de conexão e descoberta usam os esquemas de credenciais do provedor na referência interativa da OpenAPI; as credenciais nunca são retornadas.

Link to this sectionAPI de Upload#

Envie arquivos diretamente para o armazenamento em nuvem usando URLs assinadas para transferências rápidas e confiáveis. Concluir um upload de modelo anexa seus pesos. Concluir um upload de arquivo de dataset registra a sessão; passe esse sessionId para POST /api/datasets/ingest para iniciar o processamento. Consulte a documentação de Dados.

Link to this sectionObter 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"
}

Link to this sectionConcluir Upload#

POST /api/upload/complete

Notifique a plataforma de que um upload de arquivo foi concluído. Para modelos, isso anexa os pesos enviados. Para arquivos de dataset, isso verifica e registra a sessão de upload; chame POST /api/datasets/ingest posteriormente para iniciar o processamento do dataset.

Corpo:

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

Link to this sectionAPI de Integrações#

Importa conjuntos de dados de serviços de terceiros. Consulta a Documentação de Integrações.

Link to this sectionPré-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.

Link to this sectionImportar 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.

Link to this sectionAPI de Chaves de API#

Gerencie suas chaves de API para acesso programático. Veja a documentação de Chaves de API.

Link to this sectionListar Chaves de API#

GET /api/api-keys

Clientes autenticados por API-key recebem metadados da chave, nunca valores de chave existentes descriptografados. Uma chave recém-criada é retornada uma vez por POST /api/api-keys.

Passe o parâmetro de consulta opcional owner para gerenciar chaves para um workspace onde você tem acesso de editor.

Link to this sectionCriar Chave de API#

POST /api/api-keys

Corpo:

{
    "name": "training-server"
}

Link to this sectionExcluir 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"

Link to this sectionAPI de Equipes e Membros#

Crie espaços de trabalho de equipe, convide membros e gerencie papéis para colaboração. Veja a documentação de Equipes.

Link to this sectionListar Equipes#

GET /api/teams

Link to this sectionCriar Equipe#

POST /api/teams/create

Corpo:

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

Link to this sectionListar Membros#

GET /api/members

Retorna os membros do espaço de trabalho atual.

Link to this sectionConvidar Membro#

POST /api/members

Corpo:

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

Link to this sectionAtualizar Papel de Membro#

PATCH /api/members/{userId}

Link to this sectionRemover Membro#

DELETE /api/members/{userId}

Link to this sectionTransferir Propriedade#

POST /api/members/transfer-ownership

Link to this sectionAPI de Exploração#

Pesquise e navegue por datasets públicos e projetos compartilhados pela comunidade. Veja a documentação de Exploração.

Link to this sectionPesquisar Conteúdo Público#

GET /api/explore/search

Parâmetros de consulta:

Link to this sectionDados da Barra Lateral#

GET /api/explore/sidebar

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

Link to this sectionAPIs de Usuário e Configurações#

Gerencie seu perfil, API keys, uso de armazenamento e workspaces de equipe. Consulte a documentação de Configurações.

Link to this sectionResumo da Conta#

GET /api/account/summary

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

Link to this sectionObter Usuário por Nome de Usuário#

GET /api/users

Parâmetros de consulta:

Link to this sectionSeguir ou Deixar de Seguir Usuário#

PATCH /api/users

Corpo:

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

Link to this sectionVerificar Disponibilidade de Nome de Usuário#

GET /api/username/check

Parâmetros de consulta:

Link to this sectionConfiguraçõ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.).

Link to this sectionÍcone do Workspace#

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

Envie um ícone de perfil/workspace WebP de até 5 MB como campo de formulário multipart image, ou remova-o. Passe owner opcional para um workspace de equipe.

Link to this sectionIntegraçã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.

Link to this sectionInstalação e configuração#

pip install "ultralytics>=8.4.104"

Verifique a instalação:

yolo check

Link to this sectionAutenticação#

yolo settings api_key=YOUR_API_KEY

Link to this sectionUsando conjuntos de dados da plataforma#

Referencie 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:

Link to this sectionEnviando 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

Link to this sectionExemplos 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)

Validação:

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

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

Link to this sectionFAQ#

Link to this sectionComo faço para paginar resultados grandes?#

A maioria dos endpoints usa um parâmetro limit para controlar quantos resultados são retornados por solicitação:

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

Os endpoints de Atividade e Lixeira também suportam um parâmetro page para paginação baseada em página:

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

O endpoint de Pesquisa Exploratória 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"

Link to this sectionPosso usar a API sem um SDK?#

As operações REST públicas documentadas acima estão disponíveis sem o SDK 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. Você pode explorar o contrato legível por máquina de forma interativa em platform.ultralytics.com/api/docs; fluxos de conta exclusivos de sessão de navegador permanecem na UI da Plataforma.

Link to this sectionExistem bibliotecas de cliente de API?#

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

Link to this sectionComo lido com limites de taxa?#

Use o cabeçalho Retry-After da resposta 429 para aguardar o tempo correto:

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

Link to this sectionComo 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 listagem para encontrar o _id correspondente para um modelo, dataset, projeto, implantação ou outro recurso.