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

Link to this sectionAutenticaçã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 à conta — incluindo atividade, configurações, equipes, faturamento e fluxos de GDPR — atualmente requerem uma sessão de navegador autenticada e não estão disponíveis via API key.

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:

Link to this sectionLimites de Taxa#

A API impõe limites de taxa por API-key (janela deslizante, com suporte do 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 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)#

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 o seu serviço dedicado sem limitação de taxa da Plataforma. Você paga pela computação, portanto, obtém a taxa de transferência da configuração do seu serviço dedicado em vez dos limites de API compartilhados.

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.

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

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#

Carrega um ícone para o conjunto de dados (multipart form com ficheiro de imagem):

POST /api/datasets/{datasetId}/icon

Remove o ícone do conjunto de dados:

DELETE /api/datasets/{datasetId}/icon

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

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 do conjunto de dados com todas as imagens e etiquetas. Apenas conjuntos de dados públicos, próprios ou editáveis do workspace podem ser clonados. Requer uma sessão ativa no browser da plataforma — não disponível via API key.

Corpo (todos os campos são opcionais):

{
    "name": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "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 uma nova versão numerada do dataset. Apenas para o proprietário. A versão regista a contagem atual de imagens, classes, anotações e distribuição de divisões, e gera e armazena 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. Apenas para o proprietário.

Corpo do Pedido:

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

Resposta:

{
    "ok": true
}

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

Eliminar classes:

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

Link to this sectionRedistribuir Divisões#

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

Reatribuir imagens entre divisões train/val/test. As três requerem uma sessão ativa no browser da plataforma — não disponível via API key.

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 dataset para processar ficheiros ZIP ou TAR carregados, incluindo .tar.gz e .tgz, contendo imagens e rótulos.

O corpo do pedido aceita exatamente um de sessionId (uma sessão de carregamento de um arquivo enviado) ou sourceUrl (um URL remoto ZIP, TAR, TAR.GZ, TGZ ou NDJSON), mais um targetSplit opcional (train, val ou test) para substituir a estrutura de divisão do arquivo.

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]

Link to this sectionImagens do Dataset#

Link to this sectionListar Imagens#

GET /api/datasets/{datasetId}/images

Parâmetros de consulta:

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 público (com todos os seus modelos) para o teu espaço de trabalho. Requer uma sessão ativa de navegador na plataforma — não disponível via chave de API.

Link to this sectionÍcone do Projeto#

Carregar um ícone de projeto (formulário multipart com ficheiro de imagem):

POST /api/projects/{projectId}/icon

Remover o ícone do projeto:

DELETE /api/projects/{projectId}/icon

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

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 modelos que terminaram o treinamento (para uso em seletores de modelos e implantação).

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

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

Formulário Multipart:

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:

{
    "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 sectionObter Token de Predição#

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

Link to this sectionAquecer Modelo#

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

Link to this sectionAPI de Treinamento#

Inicie o treinamento YOLO em GPUs na nuvem (24 tipos de GPU de RTX 2000 Ada a B300) e monitore o progresso em tempo real. Veja a documentação de Treinamento na 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]

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 job de treinamento, métricas e progresso para um modelo. Projetos públicos são acessíveis anonimamente; projetos privados requerem uma sessão ativa de navegador na plataforma (esta rota não aceita autenticação por chave de API).

Link to this sectionCancelar Treinamento#

DELETE /api/models/{modelId}/training

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

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] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

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

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

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:

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

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

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

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:

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

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
}

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éditos, compre créditos, visualize o histórico de transações e configure a recarga automática. Consulte a documentação de faturamento.

Link to this sectionObter Saldo#

GET /api/billing/balance

Parâmetros de consulta:

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

Parâmetros de consulta:

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

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

Link to this sectionCancelar ou Retomar Assinatura#

DELETE /api/billing/subscription-checkout

Cancela uma assinatura Pro ao final do período, por padrão. Envie {"resume": true} para retomar um cancelamento já agendado antes do fim do período de faturamento.

Corpo:

{
    "resume": true
}

Link to this sectionRecarga Automática#

Adiciona créditos automaticamente quando o saldo cai abaixo de um limite.

Link to this sectionObter Configuração de Recarga Automática#

GET /api/billing/auto-topup

Parâmetros de consulta:

Link to this sectionAtualizar Configuração de Recarga Automática#

PATCH /api/billing/auto-topup

Corpo:

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

Link to this sectionMétodos de Pagamento#

Link to this sectionListar Métodos de Pagamento#

GET /api/billing/payment-methods

Link to this sectionCriar Setup Intent#

POST /api/billing/payment-methods/setup

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

Link to this sectionDefinir Método de Pagamento Padrão#

POST /api/billing/payment-methods/default

Corpo:

{
    "paymentMethodId": "pm_123"
}

Link to this sectionAtualizar Informações de Cobrança#

PATCH /api/billing/payment-methods

Corpo:

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

Link to this sectionExcluir Método de Pagamento#

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

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 sectionAPI de Upload#

Faça upload de arquivos diretamente para o armazenamento em nuvem usando URLs assinadas para transferências rápidas e confiáveis. Usa um fluxo de duas etapas: obtenha uma URL assinada e, em seguida, faça o upload do arquivo. Veja 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": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Resposta:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "gcsPath": "gs://bucket/users/user123/images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.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 que ela possa começar o processamento.

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

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

Link to this sectionAceitar Convite#

POST /api/invites/accept

Link to this sectionObter Informações do Convite#

GET /api/invites/info

Parâmetros de consulta:

Link to this sectionRevogar Convite#

DELETE /api/invites/{inviteId}

Link to this sectionReenviar Convite#

POST /api/invites/{inviteId}/resend

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, chaves de API, uso de armazenamento e configurações de privacidade de dados. Veja a documentação de Configurações.

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 de Perfil#

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

Faça upload ou remova o avatar do perfil.

Link to this sectionOnboarding#

POST /api/onboarding

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

Link to this sectionAPI de GDPR#

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

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

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

Link to this sectionCódigos de erro#

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

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

Link to this sectionWebhooks#

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

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

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. Você também pode explorar todos os endpoints de forma interativa em platform.ultralytics.com/api/docs.

Link to this sectionExistem bibliotecas de cliente de API?#

Atualmente, use o pacote Python da Ultralytics ou faça solicitações HTTP diretas. Bibliotecas de cliente oficiais para outras linguagens estão planejadas.

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

Link to this sectionComo encontro o ID do meu modelo ou conjunto de dados?#

IDs de recursos são retornados quando você cria recursos via API. Você também pode encontrá-los na URL da plataforma:

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

Use os endpoints de lista para pesquisar por nome ou filtrar por projeto.