Referência da REST API

A Ultralytics Platform fornece uma REST API abrangente para acesso programático a datasets, modelos, treinamento 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] --> B[Datasets]
    A --> C[Projects]
    A --> D[Models]
    A --> E[Deployments]
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]
    B -->|auto-annotate| B

Autenticação

APIs de recursos como datasets, projetos, modelos, treinamento, exportações e previsões utilizam autenticação por API-key. Endpoints públicos (listagem de datasets, projetos e modelos públicos) suportam acesso de leitura anônimo sem chave. Rotas orientadas a conta — incluindo atividades, configurações, equipes, faturamento e fluxos GDPR — exigem atualmente uma sessão de navegador autenticada e não estão disponíveis via API-key.

Obter API-key

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

Consulte API Keys para 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:

Limites de taxa

A API aplica limites de taxa por API-key (janela deslizante, com suporte Upstash Redis) para proteger contra abusos, mantendo o uso legítimo sem restrições. O tráfego anônimo é adicionalmente protegido pelos controles de abuso de nível de plataforma da Vercel.

Quando houver limitação de taxa, a API retorna 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 sendo chamado. Operações custosas possuem limites mais rígidos para prevenir abusos, enquanto operações CRUD padrão compartilham um 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 cota padrão de 100 requisições/min.

Endpoints dedicados (Ilimitados)

Endpoints dedicados não estão sujeitos aos limites de taxa da API-key. Quando você implanta um modelo em um endpoint dedicado, as requisições para essa URL de endpoint (por exemplo, https://predict-abc123.run.app/predict) vão diretamente para seu serviço dedicado sem limitação de taxa da plataforma. Você paga pela computação, então recebe throughput da configuração do seu serviço dedicado em vez dos limites da API compartilhada.

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

Datasets API

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

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 completos do dataset, incluindo metadados, nomes das classes e contagens de divisões.

Criar Dataset

POST /api/datasets

Corpo:

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

Atualizar Dataset

PATCH /api/datasets/{datasetId}

Corpo (atualização parcial):

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

Excluir Dataset

DELETE /api/datasets/{datasetId}

Exclusão lógica do dataset (movido para a lixeira, recuperável por 30 dias).

Clonar Dataset

POST /api/datasets/{datasetId}/clone

Cria uma cópia do dataset com todas as imagens e rótulos. Apenas datasets públicos podem ser clonados. Requer uma sessão ativa no navegador da plataforma — não disponível via chave de API.

Corpo (todos os campos são opcionais):

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

Exportar Dataset

GET /api/datasets/{datasetId}/export

Retorna uma resposta JSON com uma URL de download assinada 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 snapshot de versão numerada do dataset. Apenas para o proprietário. A versão captura a contagem atual de imagens, classes, anotações e distribuição de divisões, então gera e armazena uma exportação NDJSON imutável.

Corpo da Requisição:

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

Todos os campos são opcionais. O campo description é um rótulo fornecido pelo usuário 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. Apenas para o proprietário.

Corpo da Requisição:

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

Resposta:

{
    "ok": true
}

Obter Estatísticas de Classe

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

Retorna a distribuição de classes, mapa de calor de localização e estatísticas de dimensão. Os resultados são cacheados por 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
}

Obter Modelos Treinados no Dataset

GET /api/datasets/{datasetId}/models

Retorna 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 em imagens do dataset para auto-gerar 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 um job de ingestão de dataset para processar arquivos ZIP ou TAR enviados, incluindo .tar.gz e .tgz, contendo imagens e rótulos.

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

Imagens do Dataset

Listar Imagens

GET /api/datasets/{datasetId}/images

Parâmetros de Consulta:

Obter URLs de Imagens Assinadas

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

Obter URLs assinadas para um lote de hashes de imagem (para exibição no navegador).

Excluir Imagem

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

Obter Rótulos da Imagem

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

Retorna anotações e nomes de classe 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 Massa com Imagens

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

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

Excluir imagens em massa:

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

API de Projetos

Organize seus modelos em projetos. Cada modelo pertence a um projeto. Veja 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"}' \
  https://platform.ultralytics.com/api/projects

Atualizar Projeto

PATCH /api/projects/{projectId}

Excluir Projeto

DELETE /api/projects/{projectId}

Exclusão lógica do projeto (movido para a lixeira).

Clonar Projeto

POST /api/projects/{projectId}/clone

Clona um projeto público (com todos os seus modelos) para o seu workspace. Requer uma sessão ativa no navegador da plataforma — não disponível via chave de API.

Ícone do Projeto

Enviar um ícone de projeto (multipart form com arquivo de imagem):

POST /api/projects/{projectId}/icon

Remover o ícone do projeto:

DELETE /api/projects/{projectId}/icon

Ambos requerem uma sessão ativa no navegador da plataforma — não disponível via chave de API.

API 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.

Listar Modelos

GET /api/models

Parâmetros de Consulta:

Listar Modelos Concluídos

GET /api/models/completed

Retorna modelos que terminaram o treinamento (para uso em seletores de modelos e implantação).

Obter Modelo

GET /api/models/{modelId}

Criar Modelo

POST /api/models

Corpo JSON:

Atualizar Modelo

PATCH /api/models/{modelId}

Eliminar 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 público para um dos seus projetos. Requer uma sessão ativa no navegador da plataforma — não disponível via chave de API.

Corpo:

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

Rastrear Download

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

Rastreia a análise de download de modelos.

Executar Inferência

POST /api/models/{modelId}/predict

Formulário Multipart:

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:

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

Obter Token de Previsão

POST /api/models/{modelId}/predict/token

Aquecer Modelo

POST /api/models/{modelId}/predict/warmup

API de Treinamento

Inicie o treinamento do YOLO em GPUs em nuvem (24 tipos de GPU de RTX 2000 Ada a B300) e monitore o progresso em tempo real. Veja a documentação de Treinamento em Nuvem.

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

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 Status de Treinamento

GET /api/models/{modelId}/training

Retorna o status atual do trabalho de treinamento, métricas e progresso de um modelo. Projetos públicos são acessíveis anonimamente; projetos privados requerem uma sessão ativa no navegador da plataforma (esta rota não aceita autenticação via chave de API).

Cancelar Treino

DELETE /api/models/{modelId}/training

Encerra a instância de computação em execução e marca o trabalho como cancelado. Requer uma sessão ativa no navegador da plataforma — não disponível via chave de API.

API de Implantações

Implante modelos em endpoints de inferência dedicados com verificações de integridade 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] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

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

Pause uma implantação em execução (interrompe a cobrança).

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 roteada através do endpoint dedicado para menor latência.

Formulário Multipart:

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 Monitoramento

Métricas Agregadas

GET /api/monitoring

Retorna métricas agregadas de todas as implantações do usuário: total de requisições, implantações ativas, taxa de erro e latência média.

API de Exportação

Converta modelos para formatos otimizados como ONNX, TensorRT, CoreML e TFLite para implantação em dispositivos de borda. Consulte 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:

Obter Status da Exportação

GET /api/exports/{exportId}

Cancelar Exportação

DELETE /api/exports/{exportId}

Rastrear Download da Exportação

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

API de Atividade

Visualize um feed de ações recentes em sua conta — execuções de treinamento, uploads e muito mais. Consulte 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"]
}

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
}

API de Lixeira

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

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

Verifique seu saldo de créditos, compre créditos, visualize o histórico de transações e configure a recarga automática. Consulte a documentação de Faturamento.

Obter Saldo

GET /api/billing/balance

Parâmetros de Consulta:

Resposta:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

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

Parâmetros de Consulta:

Criar Sessão de Checkout

POST /api/billing/checkout-session

Corpo:

{
    "amount": 25,
    "owner": "team-username"
}

Cria uma sessão de checkout para compra de crédito.

Criar Checkout de Assinatura

POST /api/billing/subscription-checkout

Cria uma sessão de checkout para upgrade de assinatura Pro.

Corpo:

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Cancelar ou Retomar Assinatura

DELETE /api/billing/subscription-checkout

Cancela uma assinatura Pro no final do período por padrão. Envie {"resume": true} para retomar um cancelamento já agendado antes do término do período de cobrança.

Corpo:

{
    "resume": true
}

Recarga Automática

Adicionar créditos automaticamente quando o saldo cair abaixo de um limite.

Obter Configuração de Recarga Automática

GET /api/billing/auto-topup

Parâmetros de Consulta:

Atualizar Configuração de Recarga Automática

PATCH /api/billing/auto-topup

Corpo:

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Métodos de Pagamento

Listar Métodos de Pagamento

GET /api/billing/payment-methods

Criar Intent de Configuração

POST /api/billing/payment-methods/setup

Retorna um segredo de cliente para adicionar um novo método de pagamento.

Definir Método de Pagamento Padrão

POST /api/billing/payment-methods/default

Corpo:

{
    "paymentMethodId": "pm_123"
}

Atualizar Informações de Faturamento

PATCH /api/billing/payment-methods

Corpo:

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Excluir Método de Pagamento

DELETE /api/billing/payment-methods/{id}

API de Armazenamento

Verifique o detalhamento do seu uso de armazenamento por categoria (datasets, modelos, exportações) e veja seus itens maiores.

Obter Informações de Armazenamento

GET /api/storage

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

API de Upload

Carregue arquivos diretamente para o armazenamento em nuvem usando URLs assinadas para transferências rápidas e confiáveis. Utiliza um fluxo de duas etapas: obtenha uma URL assinada e, em seguida, carregue o arquivo. Consulte a documentação de Dados.

Obter URL de Upload Assinada

POST /api/upload/signed-url

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

Corpo:

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Resposta:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Concluir Upload

POST /api/upload/complete

Notifique a plataforma de que um upload de arquivo foi concluído para que ela possa iniciar o processamento.

Corpo:

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API de Chaves de API

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

Listar Chaves de API

GET /api/api-keys

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

Crie espaços de trabalho de equipe, convide membros e gerencie funções para colaboração. Consulte a documentação de Equipes.

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 Função de Membro

PATCH /api/members/{userId}

Remover Membro

DELETE /api/members/{userId}

Transferir Propriedade

POST /api/members/transfer-ownership

Convites

Aceitar Convite

POST /api/invites/accept

Obter Informações de Convite

GET /api/invites/info

Parâmetros de Consulta:

Revogar Convite

DELETE /api/invites/{inviteId}

Reenviar Convite

POST /api/invites/{inviteId}/resend

Explorar API

Pesquise e navegue por datasets públicos e projetos compartilhados pela comunidade. Consulte 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

Gerencie seu perfil, chaves de API, uso de armazenamento e configurações de privacidade de dados. Consulte a documentação de Configurações.

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 do usuário (nome de exibição, biografia, links sociais, etc.).

Ícone de Perfil

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

Carregar ou remover avatar de perfil.

Onboarding

POST /api/onboarding

Concluir fluxo de onboarding (definir região de dados, nome de usuário).

API de GDPR

Solicite uma exportação de todos os seus dados ou exclua permanentemente sua conta. Consulte a documentação de Configurações.

Obter Status do Trabalho de GDPR

GET /api/gdpr

Parâmetros de Consulta:

Retorna o status do trabalho. Para trabalhos de exportação concluídos, a resposta inclui uma downloadUrl.

Iniciar Fluxo de Exportação ou Exclusão

POST /api/gdpr

Corpo:

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

Opcional para espaços de trabalho de equipe:

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Códigos de erro

Integração com Python

Para uma integração mais fácil, usa 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

Verifica a instalação:

yolo check

Autenticação

yolo settings api_key=YOUR_API_KEY

Usando Datasets da Plataforma

Referencia datasets 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 Platform

Envia resultados para um projeto da Platform:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

O que é sincronizado:

• Métricas de treino (tempo real)
• Pesos finais do modelo
• Gráficos de validação
• Saída do console
• Métricas do sistema

Exemplos de API

Carrega um modelo da Platform:

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

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

Executa 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

Exporta modelo:

# Export to ONNX
model.export(format="onnx", imgsz=640, half=True)

# Export to TensorRT
model.export(format="engine", imgsz=640, half=True)

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

Webhooks

A Platform usa webhooks internos para transmitir métricas de treino em tempo real do SDK Python ultralytics (executado em GPUs na nuvem ou máquinas remotas/locais) de volta para a Platform — loss por época, mAP, estatísticas do sistema e status de conclusão. Esses webhooks são autenticados via webhookSecret HMAC fornecido por trabalho de treino e não se destinam a ser consumidos por aplicações de utilizador.

Perguntas Frequentes

Como faço a paginação de grandes resultados?

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 Activity e Trash 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 Explore Search 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?

Sim, toda a funcionalidade está disponível via REST. O SDK Python é um wrapper de conveniência que adiciona recursos como streaming de métricas em tempo real e uploads automáticos de modelos. Também podes explorar todos os endpoints interativamente em platform.ultralytics.com/api/docs.

Existem bibliotecas cliente de API?

Atualmente, usa o pacote Python da Ultralytics ou faz solicitações HTTP diretas. Bibliotecas cliente oficiais para outras linguagens estão planeadas.

Como lido com limites de taxa?

Usa o header Retry-After da resposta 429 para esperar a quantidade de tempo certa:

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 Exception("Rate limit exceeded")

Como encontro o meu ID de modelo ou dataset?

IDs de recursos são retornados quando crias recursos via API. Também podes encontrá-los na URL da plataforma:

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

Usa os endpoints de listagem para pesquisar por nome ou filtrar por projeto.