Ir para o conteúdo

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.

Início Rápido

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

# Run inference on a model
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

Autenticação

Todas as requisições de API exigem autenticação via chave de API.

Obter Chave da API

  1. Vá para Configurações > Chaves de API
  2. Clique em Criar Chave
  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

URL Base

Todos os endpoints da API usam:

https://platform.ultralytics.com/api

Limites de Taxa

PlanoRequisições/MinutoRequisições/Dia
Gratuito601,000
Pro30050,000
EmpresarialPersonalizadoPersonalizado

Os cabeçalhos de limite de taxa estão incluídos nas respostas:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

Formato da Resposta

Todas as respostas são JSON:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Respostas de Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid dataset ID",
    "details": { ... }
  }
}

API de Conjuntos de Dados

Listar Conjuntos de Dados

GET /api/datasets

Parâmetros de Consulta:

ParâmetroTipoDescrição
pageintNúmero da página (padrão: 1)
limitintItens por página (padrão: 20)
taskstringFiltrar por tipo de tarefa

Resposta:

{
    "success": true,
    "data": [
        {
            "id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "visibility": "private",
            "createdAt": "2024-01-15T10:00:00Z"
        }
    ]
}

Obter Conjunto de Dados

GET /api/datasets/{datasetId}

Criar Conjunto de Dados

POST /api/datasets

Corpo:

{
    "name": "my-dataset",
    "task": "detect",
    "description": "A custom detection dataset"
}

Excluir Conjunto de Dados

DELETE /api/datasets/{datasetId}

Exportar Conjunto de Dados

POST /api/datasets/{datasetId}/export

Retorna o URL de download no formato NDJSON.

Obter modelos treinados no conjunto de dados

GET /api/datasets/{datasetId}/models

Retorna uma lista de modelos que foram treinados usando este conjunto de dados, mostrando a relação entre os conjuntos de dados e os modelos que eles produziram.

Resposta:

{
    "success": true,
    "data": [
        {
            "id": "model_abc123",
            "name": "experiment-1",
            "projectId": "project_xyz",
            "trainedAt": "2024-01-15T10:00:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72
            }
        }
    ]
}

API de Projetos

Listar Projetos

GET /api/projects

Obter Projeto

GET /api/projects/{projectId}

Criar Projeto

POST /api/projects

Corpo:

{
    "name": "my-project",
    "description": "Detection experiments"
}

Excluir Projeto

DELETE /api/projects/{projectId}

API de Modelos

Listar Modelos

GET /api/models

Parâmetros de Consulta:

ParâmetroTipoDescrição
projectIdstringFiltrar por projeto
taskstringFiltrar por tipo de tarefa

Obter Modelo

GET /api/models/{modelId}

Carregar Modelo

POST /api/models

Formulário Multipart:

CampoTipoDescrição
filearquivoArquivo .pt do modelo
projectIdstringProjeto de destino
namestringNome do modelo

Excluir Modelo

DELETE /api/models/{modelId}

Baixar Modelo

GET /api/models/{modelId}/files

Retorna URLs de download assinadas para arquivos de modelo.

Executar Inferência

POST /api/models/{modelId}/predict

Formulário Multipart:

CampoTipoDescrição
filearquivoArquivo de imagem
conffloatLimite de confiança
ioufloatLimite de IoU

Resposta:

{
    "success": true,
    "predictions": [
        {
            "class": "person",
            "confidence": 0.92,
            "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
        }
    ]
}

API de Treinamento

Começar Treinamento

POST /api/training/start

Corpo:

{
    "modelId": "model_abc123",
    "datasetId": "dataset_xyz789",
    "epochs": 100,
    "imageSize": 640,
    "gpuType": "rtx-4090"
}

Obter Status do Treinamento

GET /api/models/{modelId}/training

Cancelar Treinamento

DELETE /api/models/{modelId}/training

API de Implantações

Listar Implantações

GET /api/deployments

Parâmetros de Consulta:

ParâmetroTipoDescrição
modelIdstringFiltrar por modelo

Criar Implantação

POST /api/deployments

Corpo:

{
    "modelId": "model_abc123",
    "region": "us-central1",
    "minInstances": 0,
    "maxInstances": 10
}

Obter Implantação

GET /api/deployments/{deploymentId}

Iniciar Implantação

POST /api/deployments/{deploymentId}/start

Parar Implantação

POST /api/deployments/{deploymentId}/stop

Excluir Implantação

DELETE /api/deployments/{deploymentId}

Obter Métricas

GET /api/deployments/{deploymentId}/metrics

Obter Logs

GET /api/deployments/{deploymentId}/logs

Parâmetros de Consulta:

ParâmetroTipoDescrição
severitystringINFO, WARNING, ERROR
limitintNúmero de entradas

API de Exportação

Listar Exportações

GET /api/exports

Criar Exportação

POST /api/exports

Corpo:

{
    "modelId": "model_abc123",
    "format": "onnx"
}

Formatos Suportados:

onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch

Obter Status da Exportação

GET /api/exports/{exportId}

API de Atividade

track e gerencie eventos de atividade para sua conta.

Listar Atividade

GET /api/activity

Parâmetros de Consulta:

ParâmetroTipoDescrição
startDatestringFiltrar da data (ISO)
endDatestringFiltrar até a data (ISO)
searchstringPesquisar em mensagens de evento

Marcar Eventos como Vistos

POST /api/activity/mark-seen

Arquivar Eventos

POST /api/activity/archive

API da Lixeira

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

Listar Lixeira

GET /api/trash

Restaurar Item

POST /api/trash

Corpo:

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

Esvaziar Lixeira

POST /api/trash/empty

Exclui permanentemente todos os itens na lixeira.

API de Faturamento

Gerenciar créditos e assinaturas.

Obter Saldo

GET /api/billing/balance

Resposta:

{
    "success": true,
    "data": {
        "cashBalance": 5000000,
        "creditBalance": 20000000,
        "reservedAmount": 0,
        "totalBalance": 25000000
    }
}

Micro-USD

Todos os valores estão em micro-USD (1.000.000 = $1,00) para contabilidade precisa.

Obter Resumo de Uso

GET /api/billing/usage-summary

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

Criar Sessão de Checkout

POST /api/billing/checkout-session

Corpo:

{
    "amount": 25
}

Cria uma sessão de checkout Stripe para compra de créditos ($5-$1000).

Criar Checkout de Assinatura

POST /api/billing/subscription-checkout

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

Criar Sessão do Portal

POST /api/billing/portal-session

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

Obter Histórico de Pagamentos

GET /api/billing/payments

Retorna a lista de transações de pagamento do Stripe.

API de Armazenamento

Obter Informações de Armazenamento

GET /api/storage

Resposta:

{
    "success": true,
    "data": {
        "used": 1073741824,
        "limit": 107374182400,
        "percentage": 1.0
    }
}

API GDPR

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

Exportar/Excluir Dados da Conta

POST /api/gdpr

Corpo:

{
    "action": "export"
}
AçãoDescrição
exportBaixar todos os dados da conta
deleteExcluir conta e todos os dados

Ação Irreversível

A exclusão da conta é permanente e não pode ser desfeita. Todos os dados, modelos e implantações serão excluídos.

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",
    "scopes": ["training", "models"]
}

Excluir Chave de API

DELETE /api/api-keys/{keyId}

Códigos de Erro

CódigoDescrição
UNAUTHORIZEDChave de API inválida ou ausente
FORBIDDENPermissões insuficientes
NOT_FOUNDRecurso não encontrado
VALIDATION_ERRORDados de requisição inválidos
RATE_LIMITEDMuitas requisições
INTERNAL_ERRORErro do servidor

Python

Para uma integração mais fácil, use o pacote Ultralytics Python.

Instalação e Configuração

pip install ultralytics

Verifique a instalação:

yolo check

Requisito de Versão do Pacote

A integração da plataforma requer ultralytics>=8.4.0. Versões anteriores NÃO funcionarão com a Plataforma.

Autenticação

Método 1: CLI (recomendado)

yolo settings api_key=YOUR_API_KEY

Método 2: Variável de ambiente

export ULTRALYTICS_API_KEY=YOUR_API_KEY

Método 3: No código

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:

ul://{username}/{resource-type}/{name}

Examples:
ul://john/datasets/coco-custom     # Dataset
ul://john/my-project               # Project
ul://john/my-project/exp-1         # Specific model
ul://ultralytics/yolo26/yolo26n    # Official model

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:

EventoDescrição
training.startedTarefa de treinamento iniciada
training.epochÉpoca concluída
training.completedTreinamento concluído
training.failedFalha no treinamento
export.completedExportação pronta

A configuração de webhook está disponível nos planos Enterprise.

FAQ

Como faço para paginar grandes resultados?

Use page e limit parâmetros:

GET /api/datasets?page=2 &
limit=50

Posso usar a API sem um SDK?

Sim, toda a funcionalidade está disponível via REST. O SDK é uma camada de conveniência.

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?

Implementar backoff exponencial:

import time


def api_request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url)
        if response.status_code != 429:
            return response
        wait = 2**attempt
        time.sleep(wait)
    raise Exception("Rate limit exceeded")


📅 Criado há 20 dias ✏️ Atualizado há 14 dias
glenn-jocherLaughing-q

Comentários