Referência da REST API

Plataforma Ultralytics oferece uma REST API abrangente para acesso programático a conjuntos de dados, 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 centrais 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

A maioria das requisições de API requer autenticação via chave de API. Endpoints públicos (listando conjuntos de dados, projetos e modelos públicos) suportam acesso de leitura anônimo sem uma chave.

Obter Chave da API

1. Ir para Settings > Profile (seção Chaves de API)
2. Clique Create Key
3. Copie a chave gerada

Consulte Chaves de API para instruções detalhadas.

Cabeçalho de Autorização

Inclua sua chave de API em todas as requisições:

Authorization: Bearer ul_your_api_key_here

Exemplo

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

URL Base

Todos os endpoints da API usam:

https://platform.ultralytics.com/api

Limites de Taxa

A API utiliza um sistema de limitação de taxa de duas camadas para proteger contra abusos, mantendo o uso legítimo irrestrito:

• Por chave de API — Limites aplicados por chave de API em requisições autenticadas
• Por IP — 100 requisições/min por endereço IP em todos /api/* caminhos (aplica-se a requisições autenticadas e não autenticadas)

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

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

Limites por Chave de API

Os limites de taxa são aplicados automaticamente com base no endpoint chamado. Operações custosas têm limites mais rigorosos para evitar abusos, enquanto operações CRUD padrão compartilham um padrão generoso:

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

Endpoints Dedicados (Ilimitado)

Endpoints dedicados são não sujeito a limites de taxa de chave de API. Ao implantar um modelo em um endpoint dedicado, as solicitações para a URL desse 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ê está pagando pelo processamento, então obtém throughput ilimitado até a configuração de escalonamento do seu endpoint.

Formato da Resposta

Respostas de Sucesso

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

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

Respostas de Erro

{
    "error": "Invalid dataset ID"
}

API de Conjuntos de Dados

Gerenciar coleções de imagens rotuladas para o treinamento de modelos YOLO.

Listar Conjuntos de Dados

GET /api/datasets

Parâmetros de Consulta:

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

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

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 Conjunto de Dados

GET /api/datasets/{datasetId}

Retorna detalhes completos do conjunto de dados, incluindo metadados, nomes de classes e contagens de divisões.

Criar Conjunto de Dados

POST /api/datasets

Corpo:

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

Atualizar Conjunto de Dados

PATCH /api/datasets/{datasetId}

Corpo (atualização parcial):

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

Excluir Conjunto de Dados

DELETE /api/datasets/{datasetId}

Exclui o conjunto de dados com exclusão lógica (movido para a lixeira, recuperável por 30 dias).

Clonar Conjunto de Dados

POST /api/datasets/{datasetId}/clone

Cria uma cópia do conjunto de dados com todas as imagens e rótulos. Apenas conjuntos de dados públicos podem ser clonados.

Corpo (todos os campos opcionais):

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

Exportar Conjunto de Dados

GET /api/datasets/{datasetId}/export

Retorna uma resposta JSON com um URL de download assinado para a exportação mais recente do conjunto de dados.

Parâmetros de Consulta:

Resposta:

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

Criar Versão do Conjunto de Dados

POST /api/datasets/{datasetId}/export

Crie um novo snapshot de versão numerada do conjunto de dados. Apenas para o proprietário. A versão captura a contagem atual de imagens, contagem de classes, contagem de 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 description campo é 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

Atualizar a descrição de uma versão existente. Somente 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 armazenados em cache 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 conjunto de dados

GET /api/datasets/{datasetId}/models

Retorna modelos que foram treinados usando este conjunto de dados.

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
}

Autoanotar Conjunto de Dados

POST /api/datasets/{datasetId}/predict

Executar inferência YOLO em imagens de dataset para auto-gerar anotações. Utiliza um modelo selecionado para prever rótulos para imagens não anotadas.

Corpo:

Ingestão de Conjunto de Dados

POST /api/datasets/ingest

Crie um trabalho de ingestão de conjunto de dados para processar arquivos ZIP carregados contendo imagens e rótulos.

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

Imagens do Conjunto de Dados

Listar Imagens

GET /api/datasets/{datasetId}/images

Parâmetros de Consulta:

Obter URLs de Imagem 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 de Imagem

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

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

Atualizar Rótulos de Imagem

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

Corpo:

{
    "labels": [{ "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] }]
}

Operações de Imagem em Massa

Mover imagens entre divisões (treino/validação/teste) dentro de um conjunto de dados:

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

Excluir imagens em massa:

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

API de Projetos

Gerenciar workspaces de treinamento que agrupam modelos.

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 $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

Atualizar Projeto

PATCH /api/projects/{projectId}

Excluir Projeto

DELETE /api/projects/{projectId}

Exclui o projeto com exclusão lógica (movido para a lixeira).

Clonar Projeto

POST /api/projects/{projectId}/clone

Ícone do Projeto

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

POST /api/projects/{projectId}/icon

Remover o ícone do projeto:

DELETE /api/projects/{projectId}/icon

API de Modelos

Gerenciar checkpoints de modelos treinados dentro de projetos.

Listar Modelos

GET /api/models

Parâmetros de Consulta:

Listar Modelos Concluídos

GET /api/models/completed

Retorna modelos que concluíram o treinamento (para uso em seletores de modelo e implantação).

Obter Modelo

GET /api/models/{modelId}

Criar Modelo

POST /api/models

Corpo JSON:

Atualizar Modelo

PATCH /api/models/{modelId}

Excluir Modelo

DELETE /api/models/{modelId}

Baixar Arquivos do Modelo

GET /api/models/{modelId}/files

Retorna URLs de download assinadas para arquivos de modelo.

Clonar Modelo

POST /api/models/{modelId}/clone

Clonar um modelo público para um dos seus projetos.

Corpo:

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

track Download

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

track análises de download de modelo.

Executar Inferência

POST /api/models/{modelId}/predict

Formulário Multipart:

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

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 Predição

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

Obter um token de curta duração para requisições de predição diretas. O token ignora o proxy da API para inferência de menor latência a partir de aplicações do lado do cliente.

Modelo de Aquecimento

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

Pré-carregue um modelo para uma inferência inicial mais rápida. Chame isso antes de executar as previsões para evitar atrasos na requisição inicial.

API de Treinamento

Inicie, monitore e cancele trabalhos 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]

Começar Treinamento

POST /api/training/start

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

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

Obter Status do Treinamento

GET /api/models/{modelId}/training

Retorna o status atual do trabalho de treinamento, métricas e progresso para um modelo.

Cancelar Treinamento

DELETE /api/models/{modelId}/training

Termina a instância de computação em execução e marca a tarefa como cancelada.

API de Implantações

Crie e gerencie endpoints de inferência dedicados.

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 é acessível globalmente por meio 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

Retomar uma implantação interrompida.

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 integridade do endpoint de implantação.

Executar Inferência em Implantação

POST /api/deployments/{deploymentId}/predict

Enviar uma imagem diretamente para um endpoint de implantação para inferência. Funcionalmente equivalente a `model predict`, mas roteado através do endpoint dedicado para menor latência.

Formulário Multipart:

Obter Métricas

GET /api/deployments/{deploymentId}/metrics

Retorna contagens de requisiçõ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 para implantação em dispositivos de borda.

Listar Exportações

GET /api/exports

Parâmetros de Consulta:

Criar Exportação

POST /api/exports

Corpo:

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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

Formatos Suportados:

Obter Status da Exportação

GET /api/exports/{exportId}

Cancelar Exportação

DELETE /api/exports/{exportId}

track Download de Exportação

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

API de Atividade

track e gerencie eventos de atividade para sua conta.

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 da Lixeira

Gerenciar recursos excluídos temporariamente (retenção de 30 dias).

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 na lixeira.

API de Faturamento

Gerenciar créditos, assinaturas e métodos de pagamento.

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 atualização da assinatura Pro.

Corpo:

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

Criar Sessão do Portal

POST /api/billing/portal-session

Retorna a URL para o portal de faturamento para gerenciamento de assinaturas.

Recarga Automática

Adicionar créditos automaticamente quando o saldo estiver 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 Intenção de Configuração

POST /api/billing/payment-methods/setup

Retorna um segredo do 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

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

Recalcular Armazenamento

POST /api/storage

Aciona um recálculo do uso de armazenamento.

API de Upload

Uploads diretos de arquivos usam um fluxo de URL assinado em duas etapas.

Obter URL de Upload Assinada

POST /api/upload/signed-url

Solicitar um URL assinado para carregar um arquivo diretamente para o armazenamento em nuvem. O URL assinado ignora o servidor da API para grandes transferências de arquivos.

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

Upload Concluído

POST /api/upload/complete

Notifique a plataforma de que um upload de arquivo está completo 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

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 $API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

API de Equipes e Membros

Gerenciar a colaboração no workspace com equipes, membros e convites.

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 workspace 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 do Convite

GET /api/invites/info

Parâmetros de Consulta:

Revogar Convite

DELETE /api/invites/{inviteId}

Reenviar Convite

POST /api/invites/{inviteId}/resend

Explore API

Pesquisar Conteúdo Público

GET /api/explore/search

Parâmetros de Consulta:

Dados da Barra Lateral

GET /api/explore/sidebar

Retorna conteúdo selecionado para a barra lateral Explorar.

APIs de Usuário e 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 as configurações do perfil do usuário (nome de exibição, biografia, links sociais, etc.).

Ícone do Perfil

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

Carregar ou remover avatar de perfil.

Integração

POST /api/onboarding

Conclua o fluxo de integração (defina a região dos dados, nome de usuário).

API GDPR

Endpoints de conformidade GDPR para exportação e exclusão de dados.

Obter Status da Tarefa GDPR

GET /api/gdpr

Parâmetros de Consulta:

Retorna o status do trabalho. Para trabalhos de exportação concluídos, a resposta inclui um 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 em equipe:

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

Códigos de Erro

Python

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

Instalação e Configuração

pip install ultralytics

Verifique a instalação:

yolo check

Autenticação

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Utilizar Conjuntos de Dados da Plataforma

Conjuntos de dados de referência com ul:// URIs:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/your-dataset",
    epochs=100,
    imgsz=640,
)

Formato URI:

Enviando para a plataforma

Enviar resultados para um projeto da Plataforma:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

O que sincroniza:

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

Exemplos de API

Carregue 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

Modelo de exportação:

# 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/my-dataset")

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

Webhooks

Webhooks notificam seu servidor sobre eventos da Plataforma via callbacks HTTP POST:

FAQ

Como faço para paginar grandes resultados?

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

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

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

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

O endpoint de Pesquisa Explorar utiliza 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 funcionalidades como streaming de métricas em tempo real e uploads automáticos de modelos.

Existem bibliotecas de cliente API?

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

Como lido com os limites de taxa?

Use o comando Retry-After cabeçalho 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")

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

Os IDs de recurso são retornados ao criar recursos via API. Você também pode encontrá-los no URL da plataforma:

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

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

📅 Criado há 2 meses ✏️ Atualizado há 5 dias

Comentários