Ir al contenido

Referencia de la REST API

Plataforma Ultralytics proporciona una REST API completa para el acceso programático a conjuntos de datos, modelos, entrenamiento y despliegues.

Inicio 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

Autenticación

Todas las solicitudes a la API requieren autenticación mediante clave API.

Obtener clave de API

  1. Ve a Configuración > Claves API
  2. Haz clic en Crear clave
  3. Copia la clave generada

Consulta Claves API para obtener instrucciones detalladas.

Encabezado de autorización

Incluye tu clave API en todas las solicitudes:

Authorization: Bearer ul_your_api_key_here

Ejemplo

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

URL base

Todos los puntos finales de la API utilizan:

https://platform.ultralytics.com/api

Límites de Tasa

PlanSolicitudes/MinutoSolicitudes/Día
Gratuito601,000
Pro30050,000
EmpresarialPersonalizadoPersonalizado

Los encabezados de límite de tasa se incluyen en las respuestas:

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

Formato de Respuesta

Todas las respuestas son JSON:

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

Respuestas de Error

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

API de Conjuntos de Datos

Listar conjuntos de datos

GET /api/datasets

Parámetros de consulta:

ParámetroTipoDescripción
pageintNúmero de página (predeterminado: 1)
limitintElementos por página (predeterminado: 20)
taskstringFiltrar por tipo de tarea

Respuesta:

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

Obtener Conjunto de Datos

GET /api/datasets/{datasetId}

Crear Conjunto de Datos

POST /api/datasets

Cuerpo:

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

Eliminar conjunto de datos

DELETE /api/datasets/{datasetId}

Exportar Conjunto de Datos

POST /api/datasets/{datasetId}/export

Devuelve la URL de descarga en formato NDJSON.

Obtener modelos entrenados en el conjunto de datos

GET /api/datasets/{datasetId}/models

Devuelve una lista de modelos que se entrenaron utilizando este conjunto de datos, mostrando la relación entre los conjuntos de datos y los modelos que produjeron.

Respuesta:

{
    "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 Proyectos

Listar Proyectos

GET /api/projects

Obtener Proyecto

GET /api/projects/{projectId}

Crear proyecto

POST /api/projects

Cuerpo:

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

Eliminar proyecto

DELETE /api/projects/{projectId}

API de Modelos

Listar Modelos

GET /api/models

Parámetros de consulta:

ParámetroTipoDescripción
projectIdstringFiltrar por proyecto
taskstringFiltrar por tipo de tarea

Obtener Modelo

GET /api/models/{modelId}

Cargar Modelo

POST /api/models

Formulario Multipart:

CampoTipoDescripción
filearchivoArchivo .pt del modelo
projectIdstringProyecto de destino
namestringNombre del modelo

Eliminar modelo

DELETE /api/models/{modelId}

Descargar Modelo

GET /api/models/{modelId}/files

Devuelve URLs de descarga firmadas para archivos de modelo.

Ejecutar Inferencia

POST /api/models/{modelId}/predict

Formulario Multipart:

CampoTipoDescripción
filearchivoArchivo de imagen
conffloatUmbral de confianza
ioufloatUmbral de IoU

Respuesta:

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

API de Entrenamiento

Comenzar el entrenamiento

POST /api/training/start

Cuerpo:

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

Obtener Estado de Entrenamiento

GET /api/models/{modelId}/training

Cancelar Entrenamiento

DELETE /api/models/{modelId}/training

API de Despliegues

Listar Despliegues

GET /api/deployments

Parámetros de consulta:

ParámetroTipoDescripción
modelIdstringFiltrar por modelo

Crear Despliegue

POST /api/deployments

Cuerpo:

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

Obtener Despliegue

GET /api/deployments/{deploymentId}

Iniciar Despliegue

POST /api/deployments/{deploymentId}/start

Detener Despliegue

POST /api/deployments/{deploymentId}/stop

Eliminar Despliegue

DELETE /api/deployments/{deploymentId}

Obtener Métricas

GET /api/deployments/{deploymentId}/metrics

Obtener Registros

GET /api/deployments/{deploymentId}/logs

Parámetros de consulta:

ParámetroTipoDescripción
severitystringINFO, WARNING, ERROR
limitintNúmero de entradas

API de Exportación

Listar Exportaciones

GET /api/exports

Crear Exportación

POST /api/exports

Cuerpo:

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

Formatos admitidos:

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

Obtener Estado de Exportación

GET /api/exports/{exportId}

API de Actividad

track y gestione los eventos de actividad de su cuenta.

Listar Actividad

GET /api/activity

Parámetros de consulta:

ParámetroTipoDescripción
startDatestringFiltrar desde fecha (ISO)
endDatestringFiltrar hasta fecha (ISO)
searchstringBuscar en mensajes de eventos

Marcar Eventos Vistos

POST /api/activity/mark-seen

Archivar Eventos

POST /api/activity/archive

API de Papelera

Gestionar recursos eliminados de forma lógica (retención de 30 días).

Listar Papelera

GET /api/trash

Restaurar Elemento

POST /api/trash

Cuerpo:

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

Vaciar Papelera

POST /api/trash/empty

Elimina permanentemente todos los elementos de la papelera.

API de Facturación

Gestionar créditos y suscripciones.

Obtener Saldo

GET /api/billing/balance

Respuesta:

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

Micro-USD

Todos los importes están en micro-USD (1.000.000 = $1.00) para una contabilidad precisa.

Obtener Resumen de Uso

GET /api/billing/usage-summary

Devuelve los detalles del plan, los límites y las métricas de uso.

Crear Sesión de Pago

POST /api/billing/checkout-session

Cuerpo:

{
    "amount": 25
}

Crea una sesión de pago de Stripe para la compra de créditos ($5-$1000).

Crear Pago de Suscripción

POST /api/billing/subscription-checkout

Crea una sesión de pago de Stripe para la suscripción Pro.

Crear Sesión del Portal

POST /api/billing/portal-session

Devuelve la URL al portal de facturación de Stripe para la gestión de suscripciones.

Obtener Historial de Pagos

GET /api/billing/payments

Devuelve la lista de transacciones de pago de Stripe.

API de Almacenamiento

Obtener Información de Almacenamiento

GET /api/storage

Respuesta:

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

API de GDPR

Puntos de conexión de cumplimiento del RGPD para la exportación y eliminación de datos.

Exportar/Eliminar Datos de la Cuenta

POST /api/gdpr

Cuerpo:

{
    "action": "export"
}
AcciónDescripción
exportDescargar todos los datos de la cuenta
deleteEliminar cuenta y todos los datos

Acción irreversible

La eliminación de la cuenta es permanente y no se puede deshacer. Todos los datos, modelos y despliegues serán eliminados.

API de claves API

Listar Claves de API

GET /api/api-keys

Crear Clave de API

POST /api/api-keys

Cuerpo:

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

Eliminar clave API

DELETE /api/api-keys/{keyId}

Códigos de error

CódigoDescripción
UNAUTHORIZEDClave API inválida o faltante
FORBIDDENPermisos insuficientes
NOT_FOUNDRecurso no encontrado
VALIDATION_ERRORDatos de solicitud inválidos
RATE_LIMITEDDemasiadas solicitudes
INTERNAL_ERRORError del servidor

Python

Para una integración más sencilla, utilice el paquete python de Ultralytics.

Instalación y configuración

pip install ultralytics

Verificar la instalación:

yolo check

Requisito de Versión del Paquete

La integración con la Plataforma requiere ultralytics>=8.4.0. Las versiones anteriores NO funcionarán con la Plataforma.

Autenticación

Método 1: CLI (recomendado)

yolo settings api_key=YOUR_API_KEY

Método 2: Variable de entorno

export ULTRALYTICS_API_KEY=YOUR_API_KEY

Método 3: En código

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Uso de Conjuntos de Datos de la Plataforma

Conjuntos de datos de referencia con ul:// URI:

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

Enviar a la plataforma

Enviar resultados a un proyecto de la 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",
)

Qué se sincroniza:

  • Métricas de entrenamiento (en tiempo real)
  • Ponderación final de los modelos
  • Gráficos de validación
  • Salida de la consola
  • Métricas del sistema

Ejemplos de API

Cargar un modelo desde Platform:

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

Ejecutar inferencia:

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 exportación:

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

Validación:

metrics = model.val(data="ul://username/my-dataset")

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

Webhooks

Los webhooks notifican a su servidor sobre los eventos de la Plataforma:

EventoDescripción
training.startedTrabajo de entrenamiento iniciado
training.epochÉpoca completada
training.completedEntrenamiento finalizado
training.failedEntrenamiento fallido
export.completedExportación lista

La configuración de webhooks está disponible en los planes Enterprise.

Preguntas frecuentes

¿Cómo pagino resultados extensos?

Utilice page y limit parámetros:

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

¿Puedo usar la API sin un SDK?

Sí, toda la funcionalidad está disponible a través de REST. El SDK es un envoltorio de conveniencia.

¿Existen bibliotecas cliente de la API?

Actualmente, utilice el paquete Python de Ultralytics o realice solicitudes HTTP directas. Se planean bibliotecas cliente oficiales para otros lenguajes.

¿Cómo gestiono los límites de tasa?

Implementar retroceso 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")


📅 Creado hace 20 días ✏️ Actualizado hace 14 días
glenn-jocherLaughing-q

Comentarios