Ir al contenido

REST API

Ultralytics proporciona una REST API completa REST API el acceso programático a conjuntos de datos, modelos, formación e implementaciones.

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 API requieren autenticación mediante clave API.

Obtener clave API

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

Consulte 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 velocidad

PlanSolicitudes/MinutoSolicitudes/día
Gratis601,000
Pro30050,000
EmpresaPersonalizadoPersonalizado

Los encabezados de límite de velocidad 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 (por defecto: 1)
limitintElementos por página (por defecto: 20)
taskcadenaFiltrar 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.

API de proyectos

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

Modelo de lista

GET /api/models

Parámetros de consulta:

ParámetroTipoDescripción
projectIdcadenaFiltrar por proyecto
taskcadenaFiltrar por tipo de tarea

Obtener modelo

GET /api/models/{modelId}

Subir modelo

POST /api/models

Formulario multiparte:

CampoTipoDescripción
filearchivoModelo de archivo .pt
projectIdcadenaProyecto objetivo
namecadenaNombre del modelo

Eliminar modelo

DELETE /api/models/{modelId}

Descargar modelo

GET /api/models/{modelId}/files

Devuelve las URL de descarga firmadas para los archivos de modelo.

Ejecutar Inferencia

POST /api/models/{modelId}/predict

Formulario multiparte:

CampoTipoDescripción
filearchivoArchivo de imagen
confflotarUmbral de confianza
iouflotarIoU

Respuesta:

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

API de formación

Comenzar el entrenamiento

POST /api/training/start

Cuerpo:

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

Obtener el estado de la formación

GET /api/models/{modelId}/training

Cancelar formación

DELETE /api/models/{modelId}/training

API de implementaciones

Lista de implementaciones

GET /api/deployments

Parámetros de consulta:

ParámetroTipoDescripción
modelIdcadenaFiltrar por modelo

Crear implementación

POST /api/deployments

Cuerpo:

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

Obtener implementación

GET /api/deployments/{deploymentId}

Iniciar implementación

POST /api/deployments/{deploymentId}/start

Detener la implementación

POST /api/deployments/{deploymentId}/stop

Eliminar implementación

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
severitycadenaINFORMACIÓN, ADVERTENCIA, ERROR
limitintNúmero de entradas

API de exportación

Exportaciones de listas

GET /api/exports

Crear exportación

POST /api/exports

Cuerpo:

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

Formatos compatibles:

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

Realiza un seguimiento y gestiona los eventos de actividad de tu cuenta.

Actividad de la lista

GET /api/activity

Parámetros de consulta:

ParámetroTipoDescripción
startDatecadenaFiltrar por fecha (ISO)
endDatecadenaFiltrar hasta la fecha (ISO)
searchcadenaBuscar en los mensajes de eventos

Marcar eventos vistos

POST /api/activity/mark-seen

Archivo de eventos

POST /api/activity/archive

API de basura

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

Lista de basura

GET /api/trash

Restaurar elemento

POST /api/trash

Cuerpo:

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

Vaciar la papelera

POST /api/trash/empty

Elimina permanentemente todos los elementos de la papelera.

API de facturación

Gestiona créditos y suscripciones.

Consigue el equilibrio

GET /api/billing/balance

Respuesta:

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

Micro-USD

Todas las cantidades se expresan en microdólares estadounidenses (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 Stripe para compras con tarjeta de crédito (entre 5 y 1000 dólares).

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 una lista de transacciones de pago de Stripe.

API de almacenamiento

Obtener información sobre el almacenamiento

GET /api/storage

Respuesta:

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

API del RGPD

Puntos finales 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. Se eliminarán todos los datos, modelos e implementaciones.

Claves API API

Lista de claves API

GET /api/api-keys

Crear clave 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 no válida o faltante
FORBIDDENPermisos insuficientes
NOT_FOUNDRecurso no encontrado
VALIDATION_ERRORDatos de solicitud no válidos
RATE_LIMITEDDemasiadas solicitudes
INTERNAL_ERRORError del servidor

Soporte SDK

Para facilitar la integración, utilice elPython Ultralytics Python .

Requisitos de la versión del paquete

La integración con Platform requiere ultralytics>= 8.4.0. Las versiones inferiores NO funcionarán con Platform.

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

Los webhooks notifican a tu servidor los eventos de la plataforma:

EventoDescripción
training.startedSe ha iniciado el trabajo de formación.
training.epochÉpoca completada
training.completedEntrenamiento finalizado
training.failedLa formación ha fallado.
export.completedListo para exportar

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

Preguntas frecuentes

¿Cómo puedo paginar resultados extensos?

Utilice page y limit parámetros:

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

¿Puedo utilizar la API sin un SDK?

Sí, todas las funciones están disponibles a través de REST. El SDK es una envoltura de conveniencia.

¿Existen bibliotecas de clientes API?

Actualmente, utilice elPython Ultralytics Python o realice solicitudes HTTP directas. Se prevé la creación de bibliotecas de clientes oficiales para otros lenguajes.

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

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 0 días ✏️ Actualizado hace 0 días
glenn-jocher

Comentarios