Referencia de la REST API

La Ultralytics Platform proporciona una completa REST API para el acceso programático a datasets, modelos, entrenamiento y despliegues.

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

Descripción general de la API

La API está organizada en torno a los recursos principales de la 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

Autenticación

Las API de recursos, como datasets, proyectos, modelos, entrenamiento, exportaciones y predicciones, utilizan autenticación mediante API key. Los endpoints públicos (listado de datasets, proyectos y modelos públicos) admiten acceso de lectura anónimo sin necesidad de una clave. Las rutas orientadas a la cuenta —incluyendo actividad, configuración, equipos, facturación y flujos de GDPR— requieren actualmente una sesión de navegador autenticada y no están disponibles mediante API key.

Obtener API Key

1. Ve a Settings > API Keys
2. Haz clic en Create Key
3. Copia la clave generada

Consulta API Keys para obtener instrucciones detalladas.

Cabecera de autorización

Incluye tu API key en todas las solicitudes:

Authorization: Bearer YOUR_API_KEY

Ejemplo

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

URL base

Todos los endpoints de la API utilizan:

Límites de tasa

La API impone límites de tasa por API key (ventana deslizante, respaldada por Upstash Redis) para proteger contra abusos manteniendo el uso legítimo sin restricciones. El tráfico anónimo está protegido adicionalmente por los controles de abuso a nivel de plataforma de Vercel.

Cuando se alcanza el límite, la API devuelve un código 429 con metadatos de reintento:

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

Límites por API Key

Los límites de tasa se aplican automáticamente según el endpoint que se esté llamando. Las operaciones costosas tienen límites más estrictos para evitar abusos, mientras que las operaciones CRUD estándar comparten un generoso límite predeterminado:

Cada categoría tiene un contador independiente por API key. Por ejemplo, realizar 20 solicitudes de predicción no afecta a tu asignación predeterminada de 100 solicitudes/min.

Endpoints dedicados (Ilimitado)

Los endpoints dedicados no están sujetos a límites de tasa por API key. Cuando despliegas un modelo en un endpoint dedicado, las solicitudes a esa URL de endpoint (p. ej., https://predict-abc123.run.app/predict) van directamente a tu servicio dedicado sin limitación de tasa por parte de la plataforma. Pagas por la computación, así que obtienes el rendimiento de la configuración de tu servicio dedicado en lugar de los límites de la API compartida.

Formato de respuesta

Respuestas exitosas

Las respuestas devuelven JSON con campos específicos del recurso:

{
    "datasets": [...],
    "total": 100
}

Respuestas de error

{
    "error": "Dataset not found"
}

API de Datasets

Crea, explora y gestiona datasets de imágenes etiquetadas para entrenar modelos YOLO. Consulta la documentación de Datasets.

Listar datasets

GET /api/datasets

Parámetros de consulta:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"

Respuesta:

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

Obtener conjunto de datos

GET /api/datasets/{datasetId}

Devuelve los detalles completos del conjunto de datos, incluidos los metadatos, los nombres de las clases y los recuentos de particiones.

Crear conjunto de datos

POST /api/datasets

Cuerpo:

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "visibility": "private",
    "classNames": ["person", "car"]
}

Actualizar conjunto de datos

PATCH /api/datasets/{datasetId}

Cuerpo (actualización parcial):

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

Eliminar conjunto de datos

DELETE /api/datasets/{datasetId}

Elimina el conjunto de datos de forma lógica (movido a la papelera, recuperable durante 30 días).

Clonar conjunto de datos

POST /api/datasets/{datasetId}/clone

Crea una copia del conjunto de datos con todas las imágenes y etiquetas. Solo se pueden clonar conjuntos de datos públicos. Requiere una sesión activa en el navegador de la plataforma; no disponible a través de una clave API.

Cuerpo (todos los campos son opcionales):

{
    "name": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "owner": "team-username"
}

Exportar conjunto de datos

GET /api/datasets/{datasetId}/export

Devuelve una respuesta JSON con una URL de descarga firmada para la última exportación del conjunto de datos.

Parámetros de consulta:

Respuesta:

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

Crear versión del conjunto de datos

POST /api/datasets/{datasetId}/export

Crea una nueva instantánea de versión numerada del conjunto de datos. Solo para el propietario. La versión captura el recuento actual de imágenes, el recuento de clases, el recuento de anotaciones y la distribución de particiones, y luego genera y almacena una exportación NDJSON inmutable.

Cuerpo de la solicitud:

{
    "description": "Added 500 training images"
}

Todos los campos son opcionales. El campo description es una etiqueta proporcionada por el usuario para la versión.

Respuesta:

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

Actualizar descripción de la versión

PATCH /api/datasets/{datasetId}/export

Actualiza la descripción de una versión existente. Solo para el propietario.

Cuerpo de la solicitud:

{
    "version": 2,
    "description": "Fixed mislabeled classes"
}

Respuesta:

{
    "ok": true
}

Obtener estadísticas de clase

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

Devuelve la distribución de clases, el mapa de calor de ubicación y las estadísticas de dimensiones. Los resultados se almacenan en caché hasta por 5 minutos.

Respuesta:

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

Obtener modelos entrenados con el conjunto de datos

GET /api/datasets/{datasetId}/models

Devuelve los modelos que se entrenaron utilizando este conjunto de datos.

Respuesta:

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

Autoanotar conjunto de datos

POST /api/datasets/{datasetId}/predict

Ejecuta la inferencia de YOLO en las imágenes del conjunto de datos para generar anotaciones automáticamente. Utiliza un modelo seleccionado para predecir etiquetas para imágenes sin anotar.

Cuerpo:

Ingesta de conjunto de datos

POST /api/datasets/ingest

Crea un trabajo de ingesta de conjuntos de datos para procesar archivos ZIP o TAR cargados, incluidos .tar.gz y .tgz, que contengan imágenes y etiquetas.

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

Imágenes del conjunto de datos

Listar imágenes

GET /api/datasets/{datasetId}/images

Parámetros de consulta:

Obtener URL de imágenes firmadas

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

Obtener URL firmadas para un lote de hashes de imagen (para su visualización en el navegador).

Eliminar imagen

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

Obtener etiquetas de imagen

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

Devuelve las anotaciones y los nombres de las clases para una imagen específica.

Actualizar etiquetas de imagen

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

Cuerpo:

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Operaciones masivas con imágenes

Mover imágenes entre particiones (train/val/test) dentro de un conjunto de datos:

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

Eliminar imágenes de forma masiva:

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

API de proyectos

Organiza tus modelos en proyectos. Cada modelo pertenece a un proyecto. Consulta la documentación de Proyectos.

Listar proyectos

GET /api/projects

Parámetros de consulta:

Obtener proyecto

GET /api/projects/{projectId}

Crear proyecto

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

Actualizar proyecto

PATCH /api/projects/{projectId}

Eliminar proyecto

DELETE /api/projects/{projectId}

Elimina el proyecto de forma lógica (movido a la papelera).

Clonar proyecto

POST /api/projects/{projectId}/clone

Clona un proyecto público (con todos sus modelos) en tu área de trabajo. Requiere una sesión activa en el navegador de la plataforma; no disponible a través de una clave API.

Icono del proyecto

Cargar un icono de proyecto (formulario multipart con archivo de imagen):

POST /api/projects/{projectId}/icon

Eliminar el icono del proyecto:

DELETE /api/projects/{projectId}/icon

Ambos requieren una sesión activa en el navegador de la plataforma; no disponibles a través de una clave API.

API de modelos

Gestiona modelos YOLO entrenados: consulta métricas, descarga pesos, ejecuta inferencia y exporta a otros formatos. Consulta la documentación de Modelos.

Listar modelos

GET /api/models

Parámetros de consulta:

Listar modelos completados

GET /api/models/completed

Devuelve los modelos que han terminado de entrenarse (para su uso en selectores de modelos y despliegue).

Obtener modelo

GET /api/models/{modelId}

Crear modelo

POST /api/models

Cuerpo JSON:

Actualizar modelo

PATCH /api/models/{modelId}

Eliminar modelo

DELETE /api/models/{modelId}

Descargar archivos de modelo

GET /api/models/{modelId}/files

Devuelve URLs de descarga firmadas para los archivos del modelo.

Clonar modelo

POST /api/models/{modelId}/clone

Clona un modelo público a uno de tus proyectos. Requiere una sesión activa en el navegador de la plataforma; no está disponible mediante clave API.

Cuerpo:

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

Rastrear descarga

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

Rastrea las analíticas de descarga del modelo.

Ejecutar inferencia

POST /api/models/{modelId}/predict

Formulario multiparte:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

Respuesta:

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

Obtener token de predicción

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

Calentar modelo

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

API de entrenamiento

Inicia el entrenamiento de YOLO en GPUs en la nube (24 tipos de GPU desde RTX 2000 Ada hasta B300) y supervisa el progreso en tiempo real. Consulta la documentación de Entrenamiento en la Nube.

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]

Iniciar entrenamiento

POST /api/training/start

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

Obtener estado del entrenamiento

GET /api/models/{modelId}/training

Devuelve el estado, las métricas y el progreso actuales del trabajo de entrenamiento de un modelo. Los proyectos públicos son accesibles de forma anónima; los proyectos privados requieren una sesión activa en el navegador de la plataforma (esta ruta no acepta autenticación mediante clave API).

Cancelar entrenamiento

DELETE /api/models/{modelId}/training

Finaliza la instancia de computación en ejecución y marca el trabajo como cancelado. Requiere una sesión activa en el navegador de la plataforma; no está disponible mediante clave API.

API de despliegues

Despliega modelos en endpoints de inferencia dedicados con comprobaciones de estado y supervisión. Los nuevos despliegues utilizan escala a cero por defecto, y la API acepta un objeto resources opcional. Consulta la documentación de Endpoints.

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 despliegues

GET /api/deployments

Parámetros de consulta:

Crear despliegue

POST /api/deployments

Cuerpo:

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

Crea un endpoint de inferencia dedicado en la región especificada. El endpoint es accesible globalmente a través de una URL única.

Obtener despliegue

GET /api/deployments/{deploymentId}

Eliminar despliegue

DELETE /api/deployments/{deploymentId}

Iniciar despliegue

POST /api/deployments/{deploymentId}/start

Reanuda un despliegue detenido.

Detener despliegue

POST /api/deployments/{deploymentId}/stop

Pausa un despliegue en ejecución (detiene la facturación).

Comprobación de estado

GET /api/deployments/{deploymentId}/health

Devuelve el estado de salud del endpoint de despliegue.

Ejecutar inferencia en despliegue

POST /api/deployments/{deploymentId}/predict

Envía una imagen directamente a un endpoint de despliegue para la inferencia. Funcionalmente equivalente a la predicción de modelo, pero enrutado a través del endpoint dedicado para una menor latencia.

Formulario multiparte:

Obtener métricas

GET /api/deployments/{deploymentId}/metrics

Devuelve métricas de recuento de solicitudes, latencia y tasa de error con datos de minigráficos.

Parámetros de consulta:

Obtener registros

GET /api/deployments/{deploymentId}/logs

Parámetros de consulta:

API de monitorización

Métricas agregadas

GET /api/monitoring

Devuelve métricas agregadas de todos los despliegues del usuario: total de solicitudes, despliegues activos, tasa de errores y latencia media.

API de exportación

Convierte modelos a formatos optimizados como ONNX, TensorRT, CoreML y TFLite para el despliegue en el borde (edge). Consulta la documentación de despliegue.

Listar exportaciones

GET /api/exports

Parámetros de consulta:

Crear exportación

POST /api/exports

Cuerpo:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

Formatos admitidos:

Obtener estado de exportación

GET /api/exports/{exportId}

Cancelar exportación

DELETE /api/exports/{exportId}

Seguimiento de descarga de exportación

POST /api/exports/{exportId}/track-download

API de actividad

Consulta un feed de acciones recientes en tu cuenta: ejecuciones de entrenamiento, subidas y más. Consulta la documentación de actividad.

Listar actividad

GET /api/activity

Parámetros de consulta:

Marcar eventos como vistos

POST /api/activity/mark-seen

Cuerpo:

{
    "all": true
}

O pasa IDs específicos:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

Archivar eventos

POST /api/activity/archive

Cuerpo:

{
    "all": true,
    "archive": true
}

O pasa IDs específicos:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

API de papelera

Ver y restaurar elementos eliminados. Los elementos se eliminan permanentemente después de 30 días. Consulta la documentación de la papelera.

Listar papelera

GET /api/trash

Parámetros de consulta:

Restaurar elemento

POST /api/trash

Cuerpo:

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

Eliminar elemento permanentemente

DELETE /api/trash

Cuerpo:

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

Vaciar papelera

DELETE /api/trash/empty

Elimina permanentemente todos los elementos de la papelera.

API de facturación

Consulta tu saldo de créditos, compra créditos, ve el historial de transacciones y configura la recarga automática. Consulta la documentación de facturación.

Obtener saldo

GET /api/billing/balance

Parámetros de consulta:

Respuesta:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

Obtener resumen de uso

GET /api/billing/usage-summary

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

Obtener transacciones

GET /api/billing/transactions

Devuelve el historial de transacciones (las más recientes primero).

Parámetros de consulta:

Crear sesión de pago

POST /api/billing/checkout-session

Cuerpo:

{
    "amount": 25,
    "owner": "team-username"
}

Crea una sesión de pago para la compra de créditos.

Crear pago de suscripción

POST /api/billing/subscription-checkout

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

Cuerpo:

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Cancela o reanuda la suscripción

DELETE /api/billing/subscription-checkout

Cancela una suscripción Pro al final del periodo por defecto. Envía {"resume": true} para reanudar una cancelación ya programada antes de que finalice el periodo de facturación.

Cuerpo:

{
    "resume": true
}

Recarga automática

Añade créditos automáticamente cuando el saldo cae por debajo de un umbral.

Obtener configuración de recarga automática

GET /api/billing/auto-topup

Parámetros de consulta:

Actualizar configuración de recarga automática

PATCH /api/billing/auto-topup

Cuerpo:

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Métodos de pago

Listar métodos de pago

GET /api/billing/payment-methods

Crear intento de configuración

POST /api/billing/payment-methods/setup

Devuelve un secreto de cliente para añadir un nuevo método de pago.

Establecer método de pago predeterminado

POST /api/billing/payment-methods/default

Cuerpo:

{
    "paymentMethodId": "pm_123"
}

Actualizar información de facturación

PATCH /api/billing/payment-methods

Cuerpo:

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Eliminar método de pago

DELETE /api/billing/payment-methods/{id}

API de almacenamiento

Consulta el desglose del uso de tu almacenamiento por categoría (datasets, modelos, exportaciones) y observa tus elementos de mayor tamaño.

Obtener información de almacenamiento

GET /api/storage

Respuesta:

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

API de subida

Sube archivos directamente al almacenamiento en la nube mediante URLs firmadas para transferencias rápidas y fiables. Utiliza un flujo de dos pasos: obtén una URL firmada y luego sube el archivo. Consulta la Data documentation.

Obtener URL de subida firmada

POST /api/upload/signed-url

Solicita una URL firmada para subir un archivo directamente al almacenamiento en la nube. La URL firmada evita el servidor API para transferencias de archivos grandes.

Cuerpo:

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Respuesta:

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

Completar subida

POST /api/upload/complete

Notifica a la plataforma que la subida de un archivo se ha completado para que pueda comenzar a procesarlo.

Cuerpo:

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API de claves API

Gestiona tus claves API para acceso programático. Consulta la API Keys documentation.

Listar claves API

GET /api/api-keys

Crear clave API

POST /api/api-keys

Cuerpo:

{
    "name": "training-server"
}

Eliminar clave API

DELETE /api/api-keys

Parámetros de consulta:

Ejemplo:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

API de equipos y miembros

Crea espacios de trabajo de equipo, invita a miembros y gestiona roles para colaborar. Consulta la Teams documentation.

Listar equipos

GET /api/teams

Crear equipo

POST /api/teams/create

Cuerpo:

{
    "username": "my-team",
    "fullName": "My Team"
}

Listar miembros

GET /api/members

Devuelve los miembros del espacio de trabajo actual.

Invitar miembro

POST /api/members

Cuerpo:

{
    "email": "user@example.com",
    "role": "editor"
}

Actualizar rol de miembro

PATCH /api/members/{userId}

Eliminar miembro

DELETE /api/members/{userId}

Transferir propiedad

POST /api/members/transfer-ownership

Invitaciones

Aceptar invitación

POST /api/invites/accept

Obtener información de invitación

GET /api/invites/info

Parámetros de consulta:

Revocar invitación

DELETE /api/invites/{inviteId}

Reenviar invitación

POST /api/invites/{inviteId}/resend

API de Explore

Busca y explora datasets públicos y proyectos compartidos por la comunidad. Consulta la Explore documentation.

Buscar contenido público

GET /api/explore/search

Parámetros de consulta:

Datos de la barra lateral

GET /api/explore/sidebar

Devuelve contenido curado para la barra lateral de Explore.

APIs de usuario y ajustes

Gestiona tu perfil, claves API, uso de almacenamiento y ajustes de privacidad de datos. Consulta la Settings documentation.

Obtener usuario por nombre de usuario

GET /api/users

Parámetros de consulta:

Seguir o dejar de seguir a un usuario

PATCH /api/users

Cuerpo:

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

Comprobar disponibilidad de nombre de usuario

GET /api/username/check

Parámetros de consulta:

Ajustes

GET /api/settings
POST /api/settings

Obtener o actualizar los ajustes del perfil de usuario (nombre visible, biografía, enlaces sociales, etc.).

Icono de perfil

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

Sube o elimina el avatar del perfil.

Onboarding

POST /api/onboarding

Completa el flujo de onboarding (configurar región de datos, nombre de usuario).

API de GDPR

Solicita una exportación de todos tus datos o elimina permanentemente tu cuenta. Consulta la Settings documentation.

Obtener estado del trabajo de GDPR

GET /api/gdpr

Parámetros de consulta:

Devuelve el estado del trabajo. Para trabajos de exportación completados, la respuesta incluye una downloadUrl.

Iniciar flujo de exportación o eliminación

POST /api/gdpr

Cuerpo:

{
    "action": "export"
}

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

Opcional para espacios de trabajo de equipo:

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

Códigos de error

Integración con Python

Para una integración más sencilla, utiliza el paquete Python de Ultralytics, que gestiona automáticamente la autenticación, las subidas y el streaming de métricas en tiempo real.

Instalación y configuración

pip install ultralytics

Verifica la instalación:

yolo check

Autenticación

yolo settings api_key=YOUR_API_KEY

Uso de Datasets de la plataforma

Referencia conjuntos de datos con URIs ul://:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

Formato de URI:

Envío a la plataforma

Envía resultados a un proyecto de la plataforma:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

Qué se sincroniza:

• Métricas de entrenamiento (tiempo real)
• Pesos finales del modelo
• Gráficos de validación
• Salida de la consola
• Métricas del sistema

Ejemplos de API

Carga un modelo desde la plataforma:

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

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

Ejecuta 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

Exporta modelo:

# 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/datasets/my-dataset")

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

Webhooks

La plataforma utiliza webhooks internos para transmitir métricas de entrenamiento en tiempo real desde el SDK de Python de ultralytics (ejecutándose en GPUs en la nube o en máquinas remotas/locales) de vuelta a la plataforma: pérdida por época, mAP, estadísticas del sistema y estado de finalización. Estos webhooks están autenticados mediante el webhookSecret HMAC proporcionado por trabajo de entrenamiento y no están destinados a ser consumidos por aplicaciones de usuario.

Preguntas frecuentes

¿Cómo pagino grandes resultados?

La mayoría de los puntos finales utilizan un parámetro limit para controlar cuántos resultados se devuelven por solicitud:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=50"

Los puntos finales de Actividad y Papelera también admiten un parámetro page para la paginación basada en páginas:

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

El punto final de búsqueda Explore utiliza offset en lugar de page, con un tamaño de página fijo de 20:

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&sort=stars"

¿Puedo utilizar la API sin un SDK?

Sí, toda la funcionalidad está disponible a través de REST. El SDK de Python es una envoltura de conveniencia que añade características como el streaming de métricas en tiempo real y las subidas automáticas de modelos. También puedes explorar todos los puntos finales de forma interactiva en platform.ultralytics.com/api/docs.

¿Existen bibliotecas de cliente para la API?

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

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

Utiliza la cabecera Retry-After de la respuesta 429 para esperar la cantidad de tiempo adecuada:

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

¿Cómo encuentro mi ID de modelo o conjunto de datos?

Los IDs de recursos se devuelven cuando creas recursos a través de la API. También puedes encontrarlos en la URL de la plataforma:

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

Utiliza los puntos finales de lista para buscar por nombre o filtrar por proyecto.