Link to this sectionReferencia de la REST API#

Ultralytics Platform ofrece una REST API completa para acceder mediante programación a datasets, modelos, entrenamiento y despliegues.

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

Link to this sectionVisión general de la API#

La API está organizada en torno a los recursos principales de la plataforma:

graph LR
    A[API Key]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    A --> D[Models]:::proc
    A --> E[Deployments]:::proc
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]:::proc
    B -->|auto-annotate| B

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

Link to this sectionAutenticación#

Las API de recursos utilizan autenticación mediante clave API, lo que incluye la gestión de clases y divisiones de conjuntos de datos, clonación, entrenamiento, exportaciones, implementaciones y lecturas de cuentas admitidas. Los endpoints públicos admiten el acceso anónimo donde se indique. Las rutas de aplicación exclusivas del navegador están excluidas.

Link to this sectionObtener 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.

Link to this sectionCabecera de autorización#

Incluye tu API-key en todas las peticiones:

Authorization: Bearer YOUR_API_KEY

Link to this sectionEjemplo#

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

Link to this sectionURL base#

Todos los endpoints de la API utilizan:

https://platform.ultralytics.com/api

Link to this sectionLímites de tasa#

La API aplica límites de tasa por API-key (ventana deslizante, respaldada por Upstash Redis) para proteger contra abusos mientras mantiene 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 aplica limitación, la API devuelve 429 con metadatos de reintento:

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

Link to this sectionLímites por API-key#

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

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

Link to this sectionEndpoints dedicados (ilimitados)#

Los endpoints dedicados no están sujetos a límites de tasa de la API-key. Cuando despliegas un modelo en un endpoint dedicado, las peticiones 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, por lo que obtienes un rendimiento basado en la configuración de tu servicio dedicado en lugar de en los límites compartidos de la API.

Link to this sectionFormato de respuesta#

Link to this sectionRespuestas de éxito#

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

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

Link to this sectionRespuestas de error#

{
    "error": "Dataset not found"
}

Link to this sectionAPI de datasets#

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

Link to this sectionListar 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"
}

Link to this sectionObtener dataset#

GET /api/datasets/{datasetId}

Devuelve los detalles completos del dataset, incluidos metadatos, nombres de clases y conteos de divisiones.

Pasa username cuando {datasetId} sea un slug de conjunto de datos en lugar de un ID.

Link to this sectionCrear dataset#

POST /api/datasets

Cuerpo:

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

Respuesta:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

Link to this sectionActualizar dataset#

PATCH /api/datasets/{datasetId}

Cuerpo (actualización parcial):

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

Link to this sectionIcono del conjunto de datos#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

Sube un icono WebP de hasta 5 MB como campo de formulario multipart image, o elimina el icono actual.

Link to this sectionEliminar dataset#

DELETE /api/datasets/{datasetId}

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

Link to this sectionClonar dataset#

POST /api/datasets/{datasetId}/clone

Crea una copia de un conjunto de datos público, propio o editable de un espacio de trabajo con todas sus imágenes y etiquetas.

Cuerpo opcional (todos los campos son opcionales):

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

Link to this sectionExportar dataset#

GET /api/datasets/{datasetId}/export

Devuelve una respuesta JSON con una URL de descarga firmada para la exportación más reciente del dataset.

Parámetros de consulta:

Respuesta:

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

Link to this sectionCrear versión de dataset#

POST /api/datasets/{datasetId}/export

Crea una nueva instantánea numerada de la versión del dataset. Solo para el propietario. La versión captura el conteo actual de imágenes, clases, anotaciones y distribución de divisiones, 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=..."
}

Link to this sectionActualizar 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
}

Link to this sectionRestaurar versión del conjunto de datos#

POST /api/datasets/{datasetId}/restore

Reconstruye las imágenes, anotaciones y clases del conjunto de datos a partir de una versión guardada sin copiar los bytes de las imágenes.

{
    "version": 2
}

Link to this sectionObtener estadísticas de clases#

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

Devuelve la distribución de clases, mapa de calor de ubicación y estadísticas de dimensiones. Los resultados se guardan en caché durante un máximo de 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
}

Link to this sectionGestionar clases#

Fusionar clases (reasigna anotaciones de clases de origen a una de destino, luego elimina las de origen):

POST /api/datasets/{datasetId}/classes/merge

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

Los ID de clase son posicionales, por lo que la combinación no es idempotente. Vuelve a obtener el conjunto de datos antes de reintentarlo.

Eliminar clases:

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

Link to this sectionRedistribuir divisiones#

POST /api/datasets/{datasetId}/splits/redistribute

Reasigna aleatoriamente las imágenes entre las divisiones de entrenamiento, validación y prueba. Los porcentajes deben sumar 100.

{
    "train": 80,
    "val": 20,
    "test": 0
}

Link to this sectionIncrustaciones del conjunto de datos#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET devuelve el resumen actual del análisis UMAP y el estado del trabajo activo; POST pone en cola un trabajo de análisis de incrustaciones; DELETE cancela el trabajo activo.

Link to this sectionAgrupación de imágenes#

GET /api/datasets/{datasetId}/images/clustering

Devuelve el diseño 2D de UMAP y los metadatos por imagen para la vista de dispersión de agrupamiento (paginado y con límite de tasa).

Link to this sectionObtener modelos entrenados en el dataset#

GET /api/datasets/{datasetId}/models

Devuelve los modelos que se entrenaron usando este dataset.

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
}

Link to this sectionAuto-anotar dataset#

POST /api/datasets/{datasetId}/predict

Ejecuta la inferencia de YOLO en las imágenes del dataset para auto-generar anotaciones. Utiliza un modelo seleccionado para predecir etiquetas en imágenes no anotadas.

Cuerpo:

Link to this sectionIngesta de dataset#

POST /api/datasets/ingest

Crea una tarea de ingesta de conjunto de datos para un conjunto de datos existente. El conjunto de datos de destino siempre se pasa como datasetId en el cuerpo JSON, no en la ruta de la URL.

El cuerpo de la solicitud requiere datasetId más exactamente uno de sessionId (una sesión de carga de un archivo subido) o sourceUrl (una URL remota de ZIP, TAR, TAR.GZ, TGZ o NDJSON). Añade targetSplit opcional (train, val o test) para anular la estructura de partición del archivo.

Para los archivos subidos, la sesión de subida ya está vinculada al conjunto de datos mediante el assetId pasado a POST /api/upload/signed-url; la ingesta valida que el assetId coincida con el datasetId del cuerpo. Las entradas opcionales de classMapping asignan cada nombre de clase entrante a un índice de clase existente basado en cero, a un nombre de clase para reutilizar o crear, o a null para omitir la clase. Para las importaciones remotas mediante sourceUrl, crea primero el conjunto de datos y luego pasa su datasetId a la ingesta.

Cuerpo (archivo subido):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

Cuerpo (archivo remoto o NDJSON):

{
    "datasetId": "dataset_abc123",
    "sourceUrl": "https://example.com/my-dataset.zip"
}

Cuerpo (ingesta posterior, importación de etiquetas):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

Respuesta:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Link to this sectionImágenes del dataset#

Link to this sectionListar imágenes#

GET /api/datasets/{datasetId}/images

Parámetros de consulta:

Link to this sectionObtener imágenes seleccionadas#

POST /api/datasets/{datasetId}/images

Devuelve la misma forma de imagen para hasta 1000 ID de imagen suministrados. Acepta los mismos controles de consulta de URL y etiqueta que la operación de lista.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Link to this sectionObtener URLs de imágenes firmadas#

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

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

Link to this sectionEliminar imagen#

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

Link to this sectionObtener etiquetas de imagen#

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

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

Link to this sectionActualizar 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] }
    ]
}

Link to this sectionOperaciones masivas de imágenes#

Mover imágenes entre divisiones (train/val/test) dentro de un dataset:

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

Eliminar imágenes masivamente:

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

Link to this sectionAPI de proyectos#

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

Link to this sectionListar proyectos#

GET /api/projects

Parámetros de consulta:

Link to this sectionObtener proyecto#

GET /api/projects/{projectId}

Link to this sectionCrear 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

Link to this sectionActualizar proyecto#

PATCH /api/projects/{projectId}

Link to this sectionEliminar proyecto#

DELETE /api/projects/{projectId}

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

Link to this sectionClonar proyecto#

POST /api/projects/{projectId}/clone

Clona un proyecto de espacio de trabajo público, propio o editable y sus modelos en tu cuenta o espacio de trabajo. Un cuerpo JSON opcional acepta sobrescrituras de name, slug, description, visibility, license y el owner de destino.

Link to this sectionIcono de proyecto#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

Sube un icono WebP de hasta 5 MB como campo de formulario multipart image, o elimina el icono actual.

Link to this sectionAPI de modelos#

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

Link to this sectionListar modelos#

GET /api/models

Parámetros de consulta:

Link to this sectionListar modelos completados#

GET /api/models/completed

Devuelve hasta 1000 modelos con pesos utilizables en todos los proyectos para entrenamiento e implementación. Pasa owner para un espacio de trabajo.

Link to this sectionObtener modelo#

GET /api/models/{modelId}

Link to this sectionCrear modelo#

POST /api/models

Cuerpo JSON:

Link to this sectionActualizar modelo#

PATCH /api/models/{modelId}

Link to this sectionEliminar modelo#

DELETE /api/models/{modelId}

Link to this sectionDescargar archivos de modelo#

GET /api/models/{modelId}/files

Devuelve URLs de descarga firmadas para archivos de modelo.

Link to this sectionClonar modelo#

POST /api/models/{modelId}/clone

Clona un modelo de espacio de trabajo público, propio o editable a uno de tus proyectos.

Cuerpo:

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

Link to this sectionSeguimiento de descarga#

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

Realiza el seguimiento de las analíticas de descarga del modelo.

Link to this sectionEjecuta la inferencia#

POST /api/models/{modelId}/predict

Los modelos públicos pueden predecirse sin autenticación. Los modelos privados y compartidos requieren una clave API con acceso al proyecto principal.

Formulario multiparte:

Proporciona file o source. El tamaño máximo de subida es de 100 MB.

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:

Las respuestas contienen shape, speed, results y datos de máscara semántica opcionales por imagen, además de metadata con el recuento de imágenes, tiempos de función, tarea y versiones de servicio. Las rutas internas del modelo nunca se devuelven.

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

Link to this sectionAPI de entrenamiento#

Lanza el entrenamiento de YOLO en GPUs en la nube (26 tipos de GPU desde RTX 2000 Ada hasta B300) y supervisa el progreso en tiempo real. Consulta la documentación de Cloud Training.

graph LR
    A[POST /training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET /models/id/training]:::proc
    C -->|cancel| E[DELETE /models/id/training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

Link to this sectionIniciar 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

Link to this sectionObtener disponibilidad de GPU#

GET /api/training/gpu-availability

Devuelve el estado actual de las existencias de GPU (High, Medium, Low o null) clasificado por ID de tipo de GPU. Público, no requiere autenticación; se almacena en caché durante 5 minutos.

Link to this sectionObtener estado del entrenamiento#

GET /api/models/{modelId}/training

Devuelve el estado, las métricas, el progreso, el tiempo, los detalles de la GPU y los errores del trabajo de entrenamiento en curso. Los proyectos públicos son accesibles sin autenticación; los proyectos privados y compartidos requieren una clave API con acceso.

Link to this sectionCancelar entrenamiento#

DELETE /api/models/{modelId}/training

Termina la instancia de computación en ejecución y marca el trabajo como cancelado.

Link to this sectionAPI de despliegues#

Despliega modelos en puntos finales de inferencia dedicados con comprobaciones de estado y monitorización. Los nuevos despliegues utilizan escalado a cero de forma predeterminada, y la API acepta un objeto resources opcional. Consulta la documentación de puntos finales.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|stop| D[Stopped]:::extern
    D -->|start| C
    C -->|delete| E[Deleted]:::error
    D -->|delete| E
    C -->|predict| F[Inference Results]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

Link to this sectionListar despliegues#

GET /api/deployments

Parámetros de consulta:

Link to this sectionCrear 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 punto final de inferencia dedicado en la región especificada. El punto final es accesible globalmente mediante una URL única.

Link to this sectionObtener despliegue#

GET /api/deployments/{deploymentId}

Link to this sectionEliminar despliegue#

DELETE /api/deployments/{deploymentId}

Link to this sectionIniciar despliegue#

POST /api/deployments/{deploymentId}/start

Reanuda un despliegue detenido.

Link to this sectionDetener despliegue#

POST /api/deployments/{deploymentId}/stop

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

Link to this sectionComprobación de estado#

GET /api/deployments/{deploymentId}/health

Devuelve el estado de salud del punto final de despliegue.

Link to this sectionEjecutar inferencia en el despliegue#

POST /api/deployments/{deploymentId}/predict

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

Formulario multiparte:

Proporciona file o source. La respuesta utiliza el mismo contrato de imagen y metadatos que la predicción de modelos y nunca devuelve la ruta interna del modelo.

Link to this sectionObtener métricas#

GET /api/deployments/{deploymentId}/metrics

Devuelve métricas de conteo de solicitudes, latencia y tasa de errores con datos de sparkline.

Parámetros de consulta:

Link to this sectionObtener registros#

GET /api/deployments/{deploymentId}/logs

Parámetros de consulta:

Link to this sectionAPI de exportación#

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

Link to this sectionListar exportaciones#

GET /api/exports

Parámetros de consulta:

Link to this sectionCrear 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:

Link to this sectionObtener estado de exportación#

GET /api/exports/{exportId}

Link to this sectionCancelar exportación#

DELETE /api/exports/{exportId}

Link to this sectionRastrear descarga de exportación#

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

Link to this sectionAPI de actividad#

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

Link to this sectionListar actividad#

GET /api/activity

Parámetros de consulta:

Link to this sectionMarcar eventos como vistos#

POST /api/activity/mark-seen

Cuerpo:

{
    "all": true
}

O pasa IDs específicos:

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

Pasa el parámetro de consulta opcional owner para marcar eventos en un espacio de trabajo.

Link to this sectionArchivar eventos#

POST /api/activity/archive

Cuerpo:

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

O pasa IDs específicos:

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

Pasa el parámetro de consulta opcional owner para archivar o restaurar eventos del espacio de trabajo.

Link to this sectionAPI de papelera#

Visualiza y restaura elementos eliminados. Los elementos se eliminan de forma permanente después de 30 días. Consulta la documentación de la papelera.

Link to this sectionListar papelera#

GET /api/trash

Parámetros de consulta:

Link to this sectionRestaurar elemento#

POST /api/trash

Cuerpo:

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

Link to this sectionEliminar elemento permanentemente#

DELETE /api/trash

Cuerpo:

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

Link to this sectionVaciar papelera#

DELETE /api/trash/empty

Elimina permanentemente todos los elementos de la papelera.

Link to this sectionAPI de facturación#

Comprueba tu saldo de crédito, el uso del plan y el historial de transacciones. Consulta la documentación de facturación.

Link to this sectionObtener saldo#

GET /api/billing/balance

Parámetros de consulta:

Respuesta:

{
    "creditsCents": 2500,
    "plan": "free"
}

Link to this sectionObtener resumen de uso#

GET /api/billing/usage-summary

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

Link to this sectionObtener transacciones#

GET /api/billing/transactions

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

Las transacciones incluyen campos de libro mayor orientados al cliente, como el importe, el saldo resultante, la fecha, el contexto opcional del modelo y la URL del recibo. No se devuelven notas internas, ID de pago/reembolso de Stripe ni claves de idempotencia.

Parámetros de consulta:

Link to this sectionAPI de almacenamiento#

Comprueba el desglose de tu uso de almacenamiento por categoría (datasets, modelos, exportaciones) y mira tus elementos más grandes.

Link to this sectionObtener información de almacenamiento#

GET /api/storage

Parámetros de consulta:

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

Link to this sectionIntegraciones de almacenamiento en la nube#

Conecta y explora integraciones de almacenamiento GCS, S3 o Azure Blob de solo lectura:

GET /api/integrations/buckets
POST /api/integrations/buckets
POST /api/integrations/buckets/discover
GET /api/integrations/buckets/{id}/objects

Las cuatro operaciones aceptan el parámetro de consulta opcional owner para un espacio de trabajo. La exploración de objetos también acepta el target obligatorio, además de los parámetros de consulta opcionales prefix y cursor del proveedor. Los cuerpos de solicitud de conexión y descubrimiento utilizan los esquemas de credenciales del proveedor en la referencia interactiva de OpenAPI; las credenciales nunca se devuelven.

Link to this sectionAPI de carga#

Sube archivos directamente al almacenamiento en la nube utilizando URL firmadas para transferencias rápidas y fiables. Completar una subida de modelo adjunta sus pesos. Completar una subida de archivo de conjunto de datos registra la sesión; pasa ese sessionId a POST /api/datasets/ingest para comenzar el procesamiento. Consulta la documentación de datos.

Link to this sectionObtener URL de carga 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 de la API para transferencias de archivos grandes.

Cuerpo:

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Respuesta:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Link to this sectionCompletar carga#

POST /api/upload/complete

Notifica a la plataforma que la subida de un archivo se ha completado. Para los modelos, esto adjunta los pesos subidos. Para los archivos de conjuntos de datos, esto verifica y registra la sesión de subida; llama a POST /api/datasets/ingest después para iniciar el procesamiento del conjunto de datos.

Cuerpo:

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

Link to this sectionAPI de integraciones#

Importa conjuntos de datos desde servicios de terceros. Consulta la documentación de integraciones.

Link to this sectionVista previa de importación de Roboflow#

POST /api/integrations/roboflow/preview

Resuelve una API key de Roboflow en un plan de importación masiva: información del espacio de trabajo, qué proyectos se importarían de nuevo, recuento de versiones ya importadas (omitidas) y tipos de proyecto no compatibles. La API key de Roboflow se pasa en el cuerpo y no se almacena.

Link to this sectionImportar desde Roboflow#

POST /api/integrations/roboflow/import

Pone en cola trabajos de ingesta de conjuntos de datos para importar los proyectos de Roboflow seleccionados a tu espacio de trabajo. Requiere espacio de almacenamiento disponible, y cada conjunto de datos debe ajustarse al límite de tamaño por importación de tu plan.

Link to this sectionAPI de claves de API#

Gestiona tus claves de API para el acceso programático. Consulta la documentación de claves de API.

Link to this sectionListar claves de API#

GET /api/api-keys

Los clientes autenticados con clave API reciben metadatos de clave, nunca valores de clave existentes descifrados. Una clave recién creada se devuelve una vez mediante POST /api/api-keys.

Pasa el parámetro de consulta opcional owner para gestionar claves para un espacio de trabajo donde tengas acceso de editor.

Link to this sectionCrear clave de API#

POST /api/api-keys

Cuerpo:

{
    "name": "training-server"
}

Link to this sectionEliminar clave de 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"

Link to this sectionAPI de equipos y miembros#

Crea espacios de trabajo de equipo, invita a miembros y gestiona roles para la colaboración. Consulta la documentación de equipos.

Link to this sectionListar equipos#

GET /api/teams

Link to this sectionCrear equipo#

POST /api/teams/create

Cuerpo:

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

Link to this sectionListar miembros#

GET /api/members

Devuelve los miembros del espacio de trabajo actual.

Link to this sectionInvitar miembro#

POST /api/members

Cuerpo:

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

Link to this sectionActualizar rol de miembro#

PATCH /api/members/{userId}

Link to this sectionEliminar miembro#

DELETE /api/members/{userId}

Link to this sectionTransferir propiedad#

POST /api/members/transfer-ownership

Link to this sectionAPI de exploración#

Busca y explora datasets y proyectos públicos compartidos por la comunidad. Consulta la documentación de exploración.

Link to this sectionBuscar contenido público#

GET /api/explore/search

Parámetros de consulta:

Link to this sectionDatos de la barra lateral#

GET /api/explore/sidebar

Devuelve contenido seleccionado para la barra lateral de exploración.

Link to this sectionAPIs de usuario y ajustes#

Gestiona tu perfil, claves API, uso de almacenamiento y espacios de trabajo de equipo. Consulta la documentación de configuración.

Link to this sectionResumen de la cuenta#

GET /api/account/summary

Devuelve el plan de la cuenta autenticada, el saldo de crédito, los recuentos de recursos y los espacios de trabajo del equipo.

Link to this sectionObtener usuario por nombre de usuario#

GET /api/users

Parámetros de consulta:

Link to this sectionSeguir o dejar de seguir a un usuario#

PATCH /api/users

Cuerpo:

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

Link to this sectionComprobar disponibilidad de nombre de usuario#

GET /api/username/check

Parámetros de consulta:

Link to this sectionAjustes#

GET /api/settings
POST /api/settings

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

Link to this sectionIcono del espacio de trabajo#

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

Sube un icono de perfil/espacio de trabajo WebP de hasta 5 MB como campo de formulario multipart image, o elimínalo. Pasa owner opcional para un espacio de trabajo de equipo.

Link to this sectionCódigos de error#

Link to this sectionIntegració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 la transmisión de métricas en tiempo real.

Link to this sectionInstalación y configuración#

pip install ultralytics

Verifica la instalación:

yolo check

Link to this sectionAutenticación#

yolo settings api_key=YOUR_API_KEY

Link to this sectionUso de datasets de la plataforma#

Haz referencia a los datasets 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:

Link to this sectionEnvío a la plataforma#

Envía los 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 (en tiempo real)
• Pesos finales del modelo
• Gráficos de validación
• Salida de consola
• Métricas del sistema

Link to this sectionEjemplos de API#

Cargar un modelo desde la plataforma:

# 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

Exportar modelo:

# Export to ONNX
model.export(format="onnx", imgsz=640, quantize=16)

# Export to TensorRT
model.export(format="engine", imgsz=640, quantize=16)

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

Link to this sectionFAQ#

Link to this section¿Cómo pagino resultados extensos?#

La mayoría de los endpoints 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 endpoints 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 endpoint 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"

Link to this section¿Puedo utilizar la API sin un SDK?#

Las operaciones REST públicas documentadas anteriormente están disponibles sin el SDK de Python. El SDK es un envoltorio de conveniencia que añade funciones como la transmisión de métricas en tiempo real y subidas automáticas de modelos. Puedes explorar el contrato legible por máquina de forma interactiva en platform.ultralytics.com/api/docs; los flujos de cuenta exclusivos de la sesión del navegador permanecen en la interfaz de usuario de la plataforma.

Link to this section¿Existen librerías cliente para la API?#

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

Link to this section¿Cómo gestiono los límites de tasa?#

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

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

Link to this section¿Cómo encuentro el ID de mi modelo o dataset?#

Los IDs de los 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 endpoints de lista para buscar por nombre o filtrar por proyecto.