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 está 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

A maioria das solicitações de API requer autenticação por meio de chave de API. Os pontos finais públicos (listagem de conjuntos de dados, projetos e modelos públicos) suportam acesso de leitura anônimo sem chave.

Obter Chave da API

1. Ir para Settings > Profile (Secção Chaves 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 sem restrições:

• Por chave API — Limites aplicados por chave API em pedidos autenticados
• Por IP — 100 solicitações/minuto por endereço IP em todos os casos /api/* caminhos (aplica-se a pedidos autenticados e não autenticados)

Quando limitada, a API retorna 429 com metadados de repetição:

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

Limites por chave API

Os limites de taxa são aplicados automaticamente com base no ponto final que está a ser chamado. Operações dispendiosas têm limites mais restritos para evitar abusos, enquanto as operações CRUD padrão compartilham um padrão generoso:

Cada categoria tem um contador independente por chave API. Por exemplo, fazer 20 pedidos de previsão não afeta a sua cota padrão de 100 pedidos/minuto.

Terminais dedicados (ilimitado)

Terminais dedicados são não sujeito a limites de taxa de chave API. Quando implementa um modelo num ponto final dedicado, as solicitações para esse URL de ponto final (por exemplo, https://predict-abc123.run.app/predict) aceda diretamente ao seu serviço dedicado, sem limitação de taxa da plataforma. Está a pagar pela computação, portanto, obtém um rendimento ilimitado até à configuração de dimensionamento do seu terminal.

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

Gerencie coleções de imagens rotuladas para treinar 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ão.

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 temporariamente o conjunto de dados (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 são 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 uma URL de download assinada para o ficheiro de exportação do conjunto de dados.

Resposta:

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

Obter estatísticas da turma

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

Retorna a distribuição de classes, o mapa de calor de localização e as 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
}

Conjunto de dados com anotação automática

POST /api/datasets/{datasetId}/predict

Execute YOLO nas imagens do conjunto de dados para gerar anotações automaticamente. Utiliza um modelo selecionado para prever rótulos para imagens não anotadas.

Corpo:

Ingestão de conjuntos de dados

POST /api/datasets/ingest

Crie uma tarefa de ingestão de conjunto de dados para processar ficheiros 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

Lista de imagens

GET /api/datasets/{datasetId}/images

Parâmetros de Consulta:

Obter URLs de imagens assinadas

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

Obtenha URLs assinados para um lote de hashes de imagens (para exibição no navegador).

Apagar imagem

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

Obter etiquetas 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 imagens

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

Corpo:

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

Operações em massa com imagens

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

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

Eliminar imagens em massa:

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

API de Projetos

Gerencie espaços de trabalho 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 temporariamente o projeto (movido para a lixeira).

Projeto Clone

POST /api/projects/{projectId}/clone

Ícone do projeto

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

POST /api/projects/{projectId}/icon

Remova o ícone do projeto:

DELETE /api/projects/{projectId}/icon

API de Modelos

Gerencie pontos de verificação de modelos treinados dentro de projetos.

Listar Modelos

GET /api/models

Parâmetros de Consulta:

Lista de modelos concluídos

GET /api/models/completed

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

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}

Descarregar ficheiros modelo

GET /api/models/{modelId}/files

Retorna URLs de download assinadas para arquivos de modelo.

Modelo Clone

POST /api/models/{modelId}/clone

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

Corpo:

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

Descarregar faixa

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

Acompanhe as análises de download do 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 Predict

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

Obtenha um token de curta duração para solicitações de previsão direta. 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 primeira inferência mais rápida. Chame isso antes de executar previsões para evitar atrasos na solicitação inicial.

API de Treinamento

Inicie, monitore e cancele tarefas de formação 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 estado atual do trabalho de treino, métricas e progresso de um modelo.

Cancelar Treinamento

DELETE /api/models/{modelId}/training

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

API de Implantações

Crie e gerencie pontos finais 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 ponto de extremidade de inferência dedicado na região especificada. O ponto de extremidade é acessível globalmente através de um URL exclusivo.

Obter Implantação

GET /api/deployments/{deploymentId}

Excluir Implantação

DELETE /api/deployments/{deploymentId}

Iniciar Implantação

POST /api/deployments/{deploymentId}/start

Retomar uma implementação interrompida.

Parar Implantação

POST /api/deployments/{deploymentId}/stop

Pausar uma implementação em execução (interrompe a cobrança).

Verificação de Saúde

GET /api/deployments/{deploymentId}/health

Retorna o estado de integridade do ponto final da implementação.

Executar inferência na implementação

POST /api/deployments/{deploymentId}/predict

Envie uma imagem diretamente para um ponto final de implementação para inferência. Funcionalmente equivalente à previsão do modelo, mas encaminhado através do ponto final dedicado para menor latência.

Formulário Multipart:

Obter Métricas

GET /api/deployments/{deploymentId}/metrics

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

Parâmetros de Consulta:

Obter Logs

GET /api/deployments/{deploymentId}/logs

Parâmetros de Consulta:

API de monitorização

Métricas agregadas

GET /api/monitoring

Retorna métricas agregadas em todas as implementações do utilizador: total de solicitações, implementações ativas, taxa de erros e latência média.

API de Exportação

Converta modelos para formatos otimizados para implementação de ponta.

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}

Exportar faixa Transferir

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

Eliminar 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

Gerencie 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 (a mais recente 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 a 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

Adicione créditos automaticamente quando o saldo ficar 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

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

Eliminar 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 do armazenamento.

API de upload

Os uploads diretos de ficheiros utilizam um fluxo de URL assinado em duas etapas.

Obter URL de upload assinado

POST /api/upload/signed-url

Solicite um URL assinado para carregar um ficheiro diretamente para o armazenamento na nuvem. O URL assinado ignora o servidor API para transferências de ficheiros 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"
}

Carregamento completo

POST /api/upload/complete

Notifique a plataforma que o upload do ficheiro 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

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 equipas e membros

Gerencie a colaboração no espaço de trabalho com equipas, membros e convidados.

Lista de equipas

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 do membro

PATCH /api/members/{userId}

Remover Membro

DELETE /api/members/{userId}

Transferência de propriedade

POST /api/members/transfer-ownership

Convida

Aceitar convite

POST /api/invites/accept

Obter informações sobre convites

GET /api/invites/info

Parâmetros de Consulta:

Revogar convite

DELETE /api/invites/{inviteId}

Reenviar convite

POST /api/invites/{inviteId}/resend

Explore a 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 utilizador e definições

Obter utilizador por nome de utilizador

GET /api/users

Parâmetros de Consulta:

Seguir ou deixar de seguir um utilizador

PATCH /api/users

Corpo:

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

Verificar disponibilidade do nome de utilizador

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

Ícone do perfil

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

Carregar ou remover avatar do perfil.

Integração

POST /api/onboarding

Concluir o fluxo de integração (definir região de dados, nome de utilizador).

API GDPR

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

Obter o estado do trabalho do RGPD

GET /api/gdpr

Parâmetros de Consulta:

Retorna o estado da tarefa. Para tarefas de exportação concluídas, a resposta inclui um downloadUrl.

Iniciar exportação ou eliminar fluxo

POST /api/gdpr

Corpo:

{
    "action": "export"
}

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

Opcional para espaços de trabalho em equipa:

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

Códigos de Erro

Python

Para facilitar a integração, use oPython Ultralytics Python , 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

Os webhooks notificam o seu servidor sobre eventos da plataforma por meio de callbacks HTTP POST:

FAQ

Como faço para paginar grandes resultados?

A maioria dos terminais utiliza 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 pontos finais Activity e Trash também suportam um page parâmetro para paginação baseada em páginas:

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

O ponto final da pesquisa Explore 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, todas as funcionalidades estão disponíveis via REST. O Python é um wrapper prático que adiciona recursos 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 necessário:

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 dos recursos são devolvidos quando cria recursos através da API. Também pode encontrá-los na URL da plataforma:

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

Use os pontos finais da lista para pesquisar por nome ou filtrar por projeto.

📅 Criado há 1 mês ✏️ Atualizado há 5 dias

Comentários