Referencia de la REST API#

Ultralytics Platform ofrece una API REST completa para acceder de forma programática a conjuntos de datos, modelos, entrenamientos y despliegues.

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

Visió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

Autenticació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.

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 peticiones:

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:

https://platform.ultralytics.com/api

Límites de tasa#

La API aplica límites basados en ventana deslizante respaldada por Upstash Redis por clave de API. Cada ruta utiliza la categoría correspondiente a continuación.

Cuando se limita la tasa de peticiones, la API devuelve 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 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.

Endpoints dedicados (ilimitados)#

Dedicated endpoints no están sujetos a los límites de velocidad de las claves de API de la plataforma cuando llamas directamente a la URL del endpoint (por ejemplo, https://predict-abc123.run.app/predict). El rendimiento depende entonces de la configuración del servicio desplegado.

Formato de respuesta#

Respuestas de éxito#

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 conjuntos de datos 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 dataset#

GET /api/datasets/{datasetId}

Devuelve los detalles del conjunto de datos, incluidos los nombres de las clases, los recuentos de particiones y otras propiedades gestionadas por Platform. Los metadatos personalizados se cargan por separado desde el endpoint de metadatos a continuación.

Pasa username cuando {datasetId} sea un identificador (slug) de un dataset en lugar de un ID.

Crear dataset#

POST /api/datasets

Cuerpo:

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

Respuesta:

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

Actualizar dataset#

PATCH /api/datasets/{datasetId}

Cuerpo (actualización parcial):

{
    "name": "Updated Name",
    "description": "New description",
    "metadata": { "location": "factory-2", "reviewed": true },
    "visibility": "public"
}

Envía un objeto metadata vacío ({}) para borrar los metadatos personalizados. El objeto de metadatos serializado está limitado a 500.000 caracteres y cada clave de nivel superior está limitada a 128 caracteres.

Obtener los metadatos del conjunto de datos#

GET /api/datasets/{datasetId}/metadata

Devuelve el objeto de metadatos personalizados y un conjunto seleccionado de pares de clave/valor gestionados por Ultralytics y de solo lectura. Los metadatos personalizados se omiten intencionadamente de las cargas útiles normales de los conjuntos de datos. Se requiere autenticación y acceso al espacio de trabajo del conjunto de datos.

Icono 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.

Eliminar dataset#

DELETE /api/datasets/{datasetId}

Realiza un borrado lógico del dataset (se mueve a la papelera y se puede recuperar durante 30 días).

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

Exportar 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
}

Crear versión de dataset#

POST /api/datasets/{datasetId}/export

Crea una nueva instantánea de versión numerada del conjunto de datos. Esto requiere acceso de Editor o superior. La versión captura el recuento actual de imágenes, clases, anotaciones y 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. Esto requiere acceso de Editor o superior.

Cuerpo de la solicitud:

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

Respuesta:

{
    "ok": true
}

Restaurar 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
}

Obtener 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
}

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

Redistribuir 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
}

Incrustaciones 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.

Agrupació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).

Obtener 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
}

Auto-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:

Ingesta de dataset#

POST /api/datasets/ingest

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

El cuerpo de la petición requiere datasetId más exactamente uno de sessionId (una sesión de subida de un archivo comprimido) o sourceUrl (una URL remota ZIP, TAR, TAR.GZ, TGZ o NDJSON). Añade el parámetro opcional targetSplit (train, val o test) para anular la estructura de divisiones (splits) del archivo. Para adjuntar metadatos personalizados, utiliza imageMetadata, indexado por la ruta exacta relativa al archivo de cada imagen o por el valor NDJSON de file.

Para los archivos comprimidos subidos, la sesión de subida ya está vinculada al dataset mediante el parámetro assetId pasado a POST /api/upload/signed-url; la ingesta valida que assetId coincida con el cuerpo datasetId. 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 de sourceUrl, crea primero el dataset y, a continuación, pasa su datasetId a la ingesta.

Cuerpo (archivo subido):

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

Cuerpo (una o varias imágenes con metadatos):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

Las imágenes locales utilizan el flujo de subida de archivos comprimidos existente, tanto si el archivo contiene una imagen como si contiene muchas. La clave debe coincidir con la ruta normalizada dentro del archivo, incluidas las carpetas. Para las importaciones NDJSON, cada registro de imagen puede contener en su lugar su propio objeto metadata. El valor local del registro metadata tiene prioridad sobre una entrada coincidente en imageMetadata.

Los metadatos están en formato JSON y admiten valores anidados. Las rutas de los archivos están limitadas a 1024 caracteres, las claves de metadatos de nivel superior a 128 caracteres y cada objeto de metadatos a 500.000 caracteres serializados. El mapa completo de imageMetadata, o los metadatos efectivos combinados en una importación NDJSON, también están limitados a 500.000 caracteres serializados. Estas restricciones se incluyen en el esquema interactivo de OpenAPI.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

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

Imágenes del dataset#

Listar imágenes#

GET /api/datasets/{datasetId}/images

Parámetros de consulta:

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

Obtener 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).

Eliminar imagen#

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

Obtener etiquetas de imagen#

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

Devuelve las anotaciones y nombres de clase 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 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

API de proyectos#

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

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",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Actualizar proyecto#

PATCH /api/projects/{projectId}

Cuerpo (actualización parcial):

{
    "metadata": { "department": "research", "program": "inspection" }
}

Envía un objeto metadata vacío ({}) para borrarlo. Los metadatos del proyecto utilizan los mismos límites de clave de nivel superior de 128 caracteres y de objeto serializado de 500.000 caracteres que los metadatos del conjunto de datos.

Obtener los metadatos del proyecto#

GET /api/projects/{projectId}/metadata

Devuelve el objeto de metadatos personalizados y los pares de clave/valor gestionados por Ultralytics de solo lectura. Se requiere autenticación y acceso al espacio de trabajo del proyecto.

Eliminar proyecto#

DELETE /api/projects/{projectId}

Realiza un borrado lógico del proyecto (se mueve a la papelera).

Clonar 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 name, slug, description, visibility, license y anulaciones de destino en owner.

Icono 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.

API de modelos#

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

Listar modelos#

GET /api/models

Parámetros de consulta:

Listar modelos completados#

GET /api/models/completed

Devuelve hasta 1000 modelos con pesos utilizables en todos los proyectos para entrenamiento y despliegue. Pasa owner para un espacio de trabajo.

Obtener modelo#

GET /api/models/{modelId}

Crear modelo#

POST /api/models

Cuerpo JSON:

Actualizar modelo#

PATCH /api/models/{modelId}

Cuerpo (actualización parcial):

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

Envía un objeto metadata vacío ({}) para borrarlo. Los metadatos personalizados del modelo son independientes de la información del modelo gestionada por el entrenamiento, los detalles del entorno y los argumentos de entrenamiento, y utilizan los mismos límites de objeto serializado y de clave de nivel superior que los metadatos del conjunto de datos.

Obtener los metadatos del modelo#

GET /api/models/{modelId}/metadata

Devuelve el objeto de metadatos personalizados y los pares de clave/valor gestionados por Ultralytics de solo lectura. Se requiere autenticación y acceso al espacio de trabajo del modelo.

Eliminar modelo#

DELETE /api/models/{modelId}

Descargar archivos de modelo#

GET /api/models/{modelId}/files

Devuelve URLs de descarga firmadas para archivos de modelo.

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

Seguimiento de descarga#

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

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

Ejecuta 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 por imagen shape, speed, results y datos opcionales de mapas de píxeles densos (un mapa de clases semánticas, o un mapa de profundidad donde depth = pixel × max / divisor es el divisor 255 para el mapa predeterminado de 8 bits, o 65535 con bits=12|16), además de metadata con el recuento de imágenes, los tiempos de ejecución de las funciones, la tarea y las versiones del servicio. Las rutas internas de los modelos 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
    }
}

API de entrenamiento#

Inicia el entrenamiento de YOLO en GPUs en la nube (26 tipos de GPU desde la RTX 2000 Ada hasta la 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

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 disponibilidad de GPU#

GET /api/training/gpu-availability

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

Obtener 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.

Cancelar entrenamiento#

DELETE /api/models/{modelId}/training

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

API de despliegues#

Despliega modelos en endpoints de inferencia dedicados con comprobaciones de estado y monitorización. Los nuevos despliegues utilizan el escalado a cero (scale-to-zero) por defecto, y la API acepta un objeto opcional resources. Consulta la documentación de Endpoints.

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

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 punto final de inferencia dedicado en la región especificada. El punto final es accesible globalmente mediante 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

Deja de atender solicitudes estableciendo las instancias mínimas y máximas del servicio en cero.

Comprobación de estado#

GET /api/deployments/{deploymentId}/health

Devuelve el estado de salud del punto final de despliegue.

Ejecutar 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 del modelo y nunca devuelve la ruta interna del modelo.

Obtener 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:

Obtener registros#

GET /api/deployments/{deploymentId}/logs

Parámetros de consulta:

API de exportación#

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

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:

Utiliza el argumento format de la tabla de exportación compartida a continuación. PyTorch es el formato de origen y no es un destino de exportación de la API.

Obtener estado de exportación#

GET /api/exports/{exportId}

Cancelar exportación#

DELETE /api/exports/{exportId}

Rastrear descarga de exportación#

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

API de actividad#

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

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

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

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
}

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

API de papelera#

Visualiza y restaura los elementos eliminados. Los elementos se eliminan permanentemente después de 30 días. Consulta la documentación de Trash.

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#

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

Los endpoints de saldo y transacciones aceptan un parámetro de consulta opcional owner con el nombre de usuario del propietario del espacio de trabajo.

Obtener saldo#

GET /api/billing/balance

Respuesta:

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

Obtener resumen de uso#

GET /api/billing/usage-summary

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

Obtener 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.

API de almacenamiento#

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

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

Integraciones 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 parámetro obligatorio target más los parámetros de consulta opcionales prefix y el proveedor cursor. Los cuerpos de las peticiones de conexión y descubrimiento utilizan los esquemas de credenciales de proveedor en la referencia interactiva de OpenAPI; las credenciales nunca se devuelven.

API de carga#

Sube archivos directamente al almacenamiento en la nube utilizando URLs firmadas para transferencias rápidas y fiables. Al completar la subida de un modelo se adjuntan sus pesos. Al completar la subida de un archivo comprimido de un dataset se registra la sesión; pasa ese sessionId a POST /api/datasets/ingest para iniciar el procesamiento. Consulta la documentación de Data.

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

Completar carga#

POST /api/upload/complete

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

Cuerpo:

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

API de integraciones#

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

Vista 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.

Importar 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.

API de claves de API#

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

Listar claves de API#

GET /api/api-keys

Los clientes autenticados con clave de API reciben metadatos de la clave, pero nunca los valores de claves existentes descifrados. Una clave recién creada es devuelta una sola vez por POST /api/api-keys.

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

Crear clave de API#

POST /api/api-keys

Cuerpo:

{
    "name": "training-server"
}

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

API 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 Teams.

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

API de exploración#

Busca y explora conjuntos de datos públicos y proyectos compartidos por la comunidad. Consulta la documentación de Explore.

Buscar contenido público#

GET /api/explore/search

Parámetros de consulta:

Datos de la barra lateral#

GET /api/explore/sidebar

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

APIs de usuario y ajustes#

Gestiona tu perfil, tus claves de API, el uso de almacenamiento y los espacios de trabajo de equipo. Consulta la documentación de Settings.

Resumen 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.

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 del espacio de trabajo#

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

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

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

Instalación y configuración#

pip install "ultralytics>=8.4.104"

Verifica la instalación:

yolo check

Autenticación#

yolo login YOUR_API_KEY

Uso de datasets de la plataforma#

Haz referencia a datasets con URIs de 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 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

Ejemplos 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)  # use imgsz=224 for classification

Validación:

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

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

FAQ#

¿Cómo pagino resultados extensos?#

La mayoría de los endpoints utilizan un parámetro limit para controlar cuántos resultados se devuelven por petición:

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

Los endpoints Activity y Trash 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 Explore Search 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?#

Las operaciones REST públicas documentadas anteriormente están disponibles sin el Python SDK. El SDK es un envoltorio de conveniencia que añade características 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 para sesiones de navegador permanecen en la interfaz de usuario de Platform.

¿Existen librerías cliente para la API?#

Utiliza el paquete de Python de Ultralytics o realiza solicitudes HTTP directas desde cualquier lenguaje.

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

Utiliza la cabecera Retry-After de la respuesta 429 para esperar el tiempo adecuado:

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 RuntimeError("Rate limit exceeded")

¿Cómo encuentro el ID de mi modelo o dataset?#

Los identificadores de recursos son devueltos por las respuestas de la API de creación, lista y obtención. Las URLs de las páginas de Platform usan slugs legibles por humanos, no identificadores de bases de datos:

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

Utiliza los endpoints de listado para encontrar el _id correspondiente para un modelo, conjunto de datos, proyecto, despliegue u otro recurso.