Ir para o conteúdo

REST API

Ultralytics fornece uma REST API abrangente REST API acesso programático a conjuntos de dados, modelos, treinamento e implementaçõ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 solicitações de API exigem autenticação por meio de chave de API.

Obter chave API

  1. Vá para Definições > Chaves API
  2. Clique em Criar chave
  3. Copie a chave gerada

Consulte Chaves API para obter instruções detalhadas.

Cabeçalho de autorização

Inclua a sua chave API em todas as solicitaçõ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 pontos finais da API utilizam:

https://platform.ultralytics.com/api

Limites de taxa

PlanoPedidos/MinutoPedidos/dia
Gratuito601,000
Pro30050,000
EmpresaPersonalizadoPersonalizado

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

API de projetos

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

Modelos da lista

GET /api/models

Parâmetros de consulta:

ParâmetroTipoDescrição
projectIdcordaFiltrar por projeto
taskcordaFiltrar por tipo de tarefa

Obter modelo

GET /api/models/{modelId}

Carregar modelo

POST /api/models

Formulário multiparte:

CampoTipoDescrição
filearquivoModelo de ficheiro .pt
projectIdcordaProjeto-alvo
namecordaNome do modelo

Excluir Modelo

DELETE /api/models/{modelId}

Descarregar modelo

GET /api/models/{modelId}/files

Retorna URLs de download assinados para ficheiros de modelo.

Executar Inferência

POST /api/models/{modelId}/predict

Formulário multiparte:

CampoTipoDescrição
filearquivoArquivo de imagem
confflutuarLimiar de confiança
iouflutuarIoU

Resposta:

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

API de formação

Começar Treinamento

POST /api/training/start

Corpo:

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

Obter o estado da formação

GET /api/models/{modelId}/training

Cancelar Formação

DELETE /api/models/{modelId}/training

API de implementações

Implantações da lista

GET /api/deployments

Parâmetros de consulta:

ParâmetroTipoDescrição
modelIdcordaFiltrar por modelo

Criar implementação

POST /api/deployments

Corpo:

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

Obter implementação

GET /api/deployments/{deploymentId}

Iniciar implementação

POST /api/deployments/{deploymentId}/start

Interromper a implementação

POST /api/deployments/{deploymentId}/stop

Eliminar implementação

DELETE /api/deployments/{deploymentId}

Obter métricas

GET /api/deployments/{deploymentId}/metrics

Obter registos

GET /api/deployments/{deploymentId}/logs

Parâmetros de consulta:

ParâmetroTipoDescrição
severitycordaINFORMAÇÃO, AVISO, ERRO
limitintNúmero de entradas

API de exportação

Exportações da lista

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 estado da exportação

GET /api/exports/{exportId}

API de atividade

Acompanhe e gerencie os eventos de atividade da sua conta.

Atividade da lista

GET /api/activity

Parâmetros de consulta:

ParâmetroTipoDescrição
startDatecordaFiltrar por data (ISO)
endDatecordaFiltrar até à data (ISO)
searchcordaPesquisar em mensagens de eventos

Marcar eventos vistos

POST /api/activity/mark-seen

Arquivo de Eventos

POST /api/activity/archive

API do lixo

Gerir recursos eliminados temporariamente (retenção de 30 dias).

Lista Lixo

GET /api/trash

Restaurar item

POST /api/trash

Corpo:

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

Esvaziar cesto de lixo

POST /api/trash/empty

Elimina permanentemente todos os itens da lixeira.

API de faturação

Gerencie créditos e assinaturas.

Obter equilíbrio

GET /api/billing/balance

Resposta:

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

Micro-USD

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

Obter resumo de utilização

GET /api/billing/usage-summary

Retorna detalhes do plano, limites e métricas de utilização.

Criar sessão de checkout

POST /api/billing/checkout-session

Corpo:

{
    "amount": 25
}

Cria uma sessão de checkout Stripe para compras com cartão de crédito (US$ 5 a US$ 1.000).

Criar checkout de assinatura

POST /api/billing/subscription-checkout

Cria uma sessão de checkout Stripe para a subscrição Pro.

Criar sessão do portal

POST /api/billing/portal-session

Retorna a URL para o portal de faturamento do 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 sobre armazenamento

GET /api/storage

Resposta:

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

API do RGPD

Pontos finais de conformidade com o RGPD para exportação e eliminação de dados.

Exportar/Eliminar dados da conta

POST /api/gdpr

Corpo:

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

Ação irreversível

A eliminação da conta é permanente e não pode ser revertida. Todos os dados, modelos e implementações serão eliminados.

Chaves API API

Listar chaves API

GET /api/api-keys

Criar chave API

POST /api/api-keys

Corpo:

{
    "name": "training-server",
    "scopes": ["training", "models"]
}

Eliminar chave API

DELETE /api/api-keys/{keyId}

Códigos de erro

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

Suporte SDK

Para facilitar a integração, use oPython Ultralytics Python .

Requisito de versão do pacote

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

pip install "ultralytics>=8.4.0"

import os

from ultralytics import YOLO

# Set API key
os.environ["ULTRALYTICS_API_KEY"] = "ul_your_key"

# Train with Platform integration
model = YOLO("yolo11n.pt")
model.train(data="ul://username/datasets/my-dataset", project="username/my-project", name="experiment-1", epochs=100)

Webhooks

Os webhooks notificam o seu servidor sobre eventos da plataforma:

EventoDescrição
training.startedTreino iniciado
training.epochÉpoca concluída
training.completedTreino concluído
training.failedA formação falhou
export.completedPronto para exportação

A configuração do Webhook está disponível nos planos Enterprise.

FAQ

Como posso paginar resultados extensos?

Use page e limit parâmetros:

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

Posso usar a API sem um SDK?

Sim, todas as funcionalidades estão disponíveis via REST. O SDK é um invólucro de conveniência.

Existem bibliotecas de clientes API?

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

Como posso lidar com os limites de taxa?

Implementar recuo 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á 0 dias ✏️ Atualizado há 0 dias
glenn-jocher

Comentários