Referencia de la REST API#

Ultralytics Platform proporciona una REST API para el acceso programático a conjuntos de datos, imágenes, proyectos, modelos, entrenamiento, exportaciones y despliegues.

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

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
    B -->|images| G[Images]:::proc
    C -->|contains| D[Models]:::proc
    B -->|train on| D
    D -->|deploy| E[Deployments]:::proc
    D -->|export| F[Exports]:::proc

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

Autenticación#

La mayoría de los endpoints requieren una clave de API. Los endpoints que exponen contenido público —leer un conjunto de datos, proyecto o modelo público, listar imágenes públicas de conjuntos de datos, ejecutar inferencia en un modelo público o buscar en Explore— también aceptan solicitudes anónimas y simplemente devuelven más resultados cuando se proporciona una clave.

Obtener una clave de API#

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 clave de API como un token de portador (bearer token):

Authorization: Bearer YOUR_API_KEY

Ejemplo#

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

URL base#

Todos los endpoints de la API utilizan:

https://platform.ultralytics.com/api

Rutas de recursos#

Los recursos se dirigen mediante los mismos nombres legibles por humanos que aparecen en las URLs de la plataforma, no mediante IDs de bases de datos:

• {owner} es un nombre de usuario personal o el identificador de un área de trabajo de equipo: de 4 a 32 caracteres, alfanuméricos en minúsculas con guiones simples entre segmentos.
• {dataset}, {project}, {model} y {deployment} siguen el mismo patrón de minúsculas con guiones, hasta 128 caracteres.
• {imageId} y {exportId} son IDs hexadecimales de 24 caracteres devueltos por la API.
• Renombrar un recurso a través de PATCH cambia el elemento visual name y el nombre de la URL juntos, y la respuesta devuelve el nombre actual de la URL para que puedas seguir utilizándolo.

Límites de tasa#

La API aplica límites de ventana deslizante por clave de API. Cada ruta pertenece a una categoría, y cada categoría tiene un contador independiente, por lo que 20 solicitudes de predicción no consumen tu asignación predeterminada.

Las rutas de la plataforma exclusivas del navegador, como el pago de facturación y la gestión de equipos, tienen sus propios límites que no se aplican al tráfico de claves de API.

Cuando se limita la tasa, la API devuelve 429 con cabeceras y un cuerpo JSON:

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

{
    "error": "Rate limit exceeded",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

Endpoints dedicados (ilimitados)#

Los endpoints dedicados no están sujetos a los límites de velocidad de la clave de API de la plataforma cuando llamas directamente al propio serviceUrl del despliegue (por ejemplo, https://predict-abc123.run.app/predict). El rendimiento depende entonces la configuración del servicio desplegado.

Formato de respuesta#

Respuestas de éxito#

Las respuestas son objetos JSON con campos específicos de cada recurso. No existe un contenedor genérico: los endpoints de lista devuelven una colección nombrada junto con recuentos, y las mutaciones devuelven los identificadores modificados.

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

Las respuestas con datos también incluyen region (us, eu o ap), la región de almacenamiento para esa área de trabajo.

Respuestas de error#

Cada respuesta de error es un objeto JSON con un mensaje error:

{
    "error": "Dataset not found"
}

Paginación#

El estilo de paginación depende de la colección:

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/{owner}

Python SDK: client.datasets.list(owner)

Devuelve los conjuntos de datos públicos del propietario, además de los conjuntos de datos privados cuando tu clave puede ver ese área de trabajo.

Parámetros de consulta:

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

Respuesta:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Obtener dataset#

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

Devuelve el objeto de conjunto de datos completo bajo una clave dataset, incluyendo classNames, splits, versions, source y el objeto metadata definido por el usuario.

Crear dataset#

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

Cuerpo:

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

Respuesta (201):

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

Actualizar dataset#

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

Cuerpo (actualización parcial):

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

Campos aceptados: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter y starred. Envía un objeto metadata vacío ({}) para borrar los metadatos personalizados. Las claves de metadatos están limitadas a 128 caracteres y el objeto serializado a 500 000 caracteres.

Respuesta:

{
    "success": true,
    "dataset": "warehouse-safety"
}

Renombrar cambia el nombre de la URL, así que utiliza el valor devuelto dataset para las solicitudes posteriores.

Eliminar dataset#

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

Mueve el conjunto de datos a la papelera, donde se puede recuperar durante 30 días.

Clonar dataset#

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

Copia un conjunto de datos accesible, junto con sus imágenes y etiquetas, en tu área de trabajo personal o en un área de trabajo de equipo.

Cuerpo opcional (todos los campos son opcionales):

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

Respuesta (201): id, owner, dataset, name, imageCount, classCount y region. Los conjuntos de datos respaldados por un recurso de almacenamiento conectado devuelven 409 porque sus archivos no se copian.

Descargar una exportación de un conjunto de datos#

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

Devuelve una URL de descarga NDJSON firmada. Omite v para exportar el estado actual del conjunto de datos, reutilizando la exportación en caché cuando nada haya cambiado desde que se generó.

Parámetros de consulta:

Respuesta:

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

Solicitar una versión específica devuelve downloadUrl y version en lugar de cached.

Crear versión de dataset#

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

Crea una instantánea numerada inmutable del conjunto de datos y almacena su exportación en NDJSON. Requiere acceso de editor.

Cuerpo (opcional):

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

Respuesta:

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

reused es true cuando el conjunto de datos no ha cambiado desde la versión anterior y se devolvió esa instantánea en su lugar.

Actualizar descripción de la versión#

PATCH /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

Cuerpo:

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

Respuesta: {"ok": true}

Restaurar versión del conjunto de datos#

POST /api/datasets/{owner}/{dataset}/restore

Python SDK: client.datasets.restore(owner, dataset, version=...)

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

Cuerpo:

{
    "version": 2
}

Respuesta: {"version": 2, "imageCount": 1000}

Obtener estadísticas del conjunto de datos#

GET /api/datasets/{owner}/{dataset}/class-stats

Python SDK: client.datasets.class_stats(owner, dataset)

Devuelve recuentos de anotaciones por clase, histogramas de imágenes y anotaciones, y mapas de calor. Los conjuntos de datos grandes se muestrean, en cuyo caso sampleSize informa cuántas imágenes contribuyeron.

Respuesta (abreviada):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "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", "forklift"],
    "cached": true,
    "sampleSize": null
}

Gestionar clases#

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

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

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

Eliminar clases (sus anotaciones se eliminan y los ID de las clases restantes se desplazan hacia abajo):

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

Ambas operaciones devuelven success, los elementos actualizados classNames y classColors, y un resumen de lo que cambió (mergedClassIds y targetClassId, o deletedClassIds y deletedAnnotations).

Redistribuir divisiones#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

Reasigna aleatoriamente las imágenes entre divisiones. Los tres porcentajes deben sumar 100.

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

Respuesta: success, los recuentos resultantes de splits y modified (número de imágenes movidas).

Incrustaciones del conjunto de datos#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

SDK de Python: client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)

GET devuelve el resumen del análisis (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST pone en cola un análisis de incrustaciones y devuelve 202 con un identificador jobId. DELETE cancela el trabajo activo y devuelve el ID del trabajo cancelado o null.

Agrupación de imágenes#

GET /api/datasets/{owner}/{dataset}/images/clustering

Python SDK: client.datasets.clustering(owner, dataset)

Devuelve la disposición 2D de UMAP a partir de un análisis completado, paginada con offset y limit (predeterminado y máx. 50 000). Cada entrada tiene id, umapX, umapY, split, classIds, width, height, bytes, labelCount y missing.

Listar modelos entrenados en un conjunto de datos#

GET /api/datasets/{owner}/{dataset}/models

Python SDK: client.datasets.models(owner, dataset)

Respuesta:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

Listar imágenes del conjunto de datos#

GET /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.images(owner, dataset)

Parámetros de consulta:

Respuesta:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04.jpg",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

Obtener imágenes seleccionadas#

POST /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

Devuelve la misma forma de imagen para un máximo de 1000 ID de imagen proporcionados, y acepta los mismos parámetros de filtro y consulta de URL que la operación de lista.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Ingestar datos en el conjunto de datos#

POST /api/datasets/{owner}/{dataset}/ingest

Python SDK: client.datasets.ingest(owner, dataset, body=...)

Procesa una carga completada, un archivo remoto o una fuente de almacenamiento conectada en un conjunto de datos existente. Proporciona exactamente una fuente:

Las sesiones de carga están vinculadas a un conjunto de datos mediante el parámetro assetId pasado a POST /api/upload/signed-url, y la ingesta rechaza una sesión que pertenezca a un conjunto de datos diferente.

Cuerpo (archivo subido):

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

Cuerpo (archivo remoto o NDJSON):

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

Cuerpo (importación de etiquetas en una ingesta posterior):

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

Cuerpo (adjuntar metadatos por imagen):

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

Las claves de metadatos deben coincidir con la ruta normalizada dentro del archivo, incluidas las carpetas. Para las importaciones en NDJSON, cada registro puede llevar su propio objeto metadata, el cual tiene preferencia sobre una entrada coincidente en imageMetadata. 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 (así como todo el mapa imageMetadata) a 500 000 caracteres serializados.

Respuesta (201):

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/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

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
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/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

API de imágenes#

Inspecciona, anota, mueve y elimina imágenes del conjunto de datos mediante su ID de imagen de 24 caracteres. Consulta la documentación de anotaciones.

Obtener imagen#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Devuelve metadata (personalizado, definido por el usuario), properties (nombre de archivo, hash, dimensiones, división, recuentos, marcas de tiempo), labels y el elemento classNames del conjunto de datos.

Actualizar imagen#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

Reemplaza bien las anotaciones o bien los metadatos personalizados; envía una de las dos estructuras, no ambas.

Cuerpo (anotaciones):

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

Cuerpo (metadatos):

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

Eliminar imagen#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

Elimina permanentemente una imagen y sus anotaciones.

Autoanotar imagen#

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

Ejecuta la inferencia de YOLO en la imagen y devuelve las anotaciones predichas. No las guarda; vuelve a escribir los resultados con PATCH /api/images/{imageId} cuando estés satisfecho con ellos.

Respuesta: success, predictions (objetos de anotación), modelUsed y inferenceTime. Un modelo cuyas clases no coincidan con el conjunto de datos devuelve 422.

Mover imágenes en lote#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

Mueve hasta 1000 imágenes de un conjunto de datos a una división diferente.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

Los conflictos de nombres de archivo o contenido devuelven 409 hasta que elijas una opción general para el conjunto (conflictPolicy) entre skip, keep_both o replace. La respuesta informa sobre modifiedCount, skippedCount y targetSplit.

Eliminar imágenes en lote#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Elimina hasta 1000 imágenes de un único conjunto de datos y devuelve deletedCount y deletedImageIds.

Obtener URLs de imágenes firmadas#

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

Devuelve URL firmadas temporales para un máximo de 100 ID de imagen de un conjunto de datos.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

Respuesta: urls y thumbnails, ambos indexados por ID de imagen.

API de proyectos#

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

Listar proyectos#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

Parámetros de consulta:

Obtener proyecto#

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

Devuelve el objeto project, una matriz models de resúmenes por modelo (estado, métricas, épocas, pesos, argumentos de entrenamiento) y isOwner.

Crear proyecto#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Respuesta (201): id, owner, project, region.

Actualizar proyecto#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

Campos aceptados: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences y starred.

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

Envía un objeto metadata vacío ({}) para borrarlo. Los metadatos del proyecto utilizan los mismos límites de claves de 128 caracteres y de objetos serializados de 500 000 caracteres que los metadatos del conjunto de datos.

Eliminar proyecto#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

Mueve el proyecto y sus modelos a la papelera y devuelve cascadedModels.

Clonar proyecto#

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

Clona un proyecto accesible y sus modelos completados. El cuerpo opcional acepta project, name, description, visibility, license y un destino owner.

API de modelos#

Gestiona modelos YOLO entrenados: visualiza métricas, descarga pesos, ejecuta inferencias y supervisa el entrenamiento. Consulta la documentación de modelos.

Listar modelos en un proyecto#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

Parámetros de consulta:

Obtener modelo#

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

Parámetros de consulta:

La respuesta predeterminada contiene el objeto model (estado, tarea, métricas, trainArgs, trainResults, classNames, computeCost, metadata y más), además de isOwner.

Crear modelo#

POST /api/models

Python SDK: client.models.create(body=...)

Crea un registro de modelo no entrenado al que puedes adjuntar pesos o entrenar.

Respuesta (201): id, owner, project, model, region.

Actualizar modelo#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

Los campos aceptados incluyen name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError y starred.

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

El parámetro personalizado metadata es independiente de los campos propios del entrenamiento, como trainArgs, environment y trainResults, y utiliza los mismos límites de tamaño que los metadatos del conjunto de datos.

Eliminar modelo#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

Mueve el modelo a trash durante 30 días.

Descargar archivos de modelo#

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

Devuelve URLs firmadas de corta duración para los pesos del modelo.

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

Clonar modelo#

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

Copia un modelo accesible en un proyecto existente.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

Ejecuta la inferencia#

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

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

Formulario multiparte:

Proporciona file o source. Los modelos de profundidad también aceptan bits (8, 12 o 16) para seleccionar la cuantización PNG del mapa de profundidad. Las solicitudes que superen los límites de entrada del servicio devuelven 413.

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

Respuesta:

Cada entrada en images incluye shape, speed, results y, para tareas de predicción densa, una carga útil PNG de semantic_mask o depth (los valores de profundidad son pixel × max / divisor, con un divisor de 255 para el mapa predeterminado de 8 bits y de 65535 cuando bits es 12 o 16). El objeto metadata informa sobre el recuento de imágenes, los tiempos de las funciones, la tarea y las versiones del servicio. Las rutas internas de los modelos nunca se devuelven.

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Comprobar el progreso del entrenamiento#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

Devuelve job, que contiene el estado, el progreso de las épocas, el tiempo, los detalles de cómputo, los argumentos de entrenamiento, las métricas de las épocas y los detalles seguros de los errores, o null cuando el modelo nunca se ha entrenado. Los modelos en proyectos públicos se pueden leer sin autenticación.

Cancelar entrenamiento#

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

Termina la instancia de cómputo en ejecución y marca el trabajo como cancelado. Devuelve 409 cuando el entrenamiento ya no está activo.

API de entrenamiento#

Inicia el entrenamiento de YOLO en GPUs en la nube y supervisa el progreso en tiempo real. Consulta la documentación de Cloud Training.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../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

Obtener disponibilidad de GPU#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

Devuelve el estado actual del inventario codificado por ID de GPU. Es público y sin autenticación; pasa managed=true para incluir la capacidad de entrenamiento gestionado, que sí requiere una clave API.

Iniciar entrenamiento#

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

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

Respuesta:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

El entrenamiento devuelve 402 cuando tu saldo de créditos es demasiado bajo y 503 cuando no hay capacidad disponible para la GPU solicitada.

API de exportaciones#

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

Listar exportaciones#

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

Parámetros de consulta:

Crear exportación#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

Respuesta (201): id, format, status (queued o running), gpuType, region. Una exportación equivalente que ya esté en curso devuelve 409.

Formatos admitidos:

Usa 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/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

Devuelve el objeto export con status, format, args, gpuType, marcas de tiempo y, una vez completado, un objeto file que contiene size, downloadUrl y downloadFilename.

Cancelar o eliminar exportación#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

Cancela una exportación activa o elimina una finalizada junto con su archivo. La respuesta informa de lo que ocurrió:

{
    "success": true,
    "action": "cancelled"
}

API de despliegues#

Despliega modelos en endpoints de inferencia dedicados con comprobaciones de estado y supervisión. Consulta la documentación de endpoints.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action 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/{owner}

Python SDK: client.deployments.list(owner)

Parámetros de consulta:

Los llamantes anónimos deben filtrar por un único modelo público; listar un espacio de trabajo completo requiere autenticación.

Crear despliegue#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

Cuerpo:

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

Respuesta (201): id, deployment, status (creating), message y region.

Obtener despliegue#

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

Devuelve el objeto deployment con status, statusMessage, region, serviceUrl y resources.

Iniciar, detener o reemplazar un despliegue#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

Un único campo action selecciona la operación:

{ "action": "start" }

El reemplazo despliega una nueva revisión preservando el ID de despliegue, la región y la URL del endpoint; la revisión existente permanece activa si el despliegue falla. El modelo de reemplazo debe ser un modelo completado con pesos a los que tu clave pueda acceder. Las operaciones completadas devuelven 200 con status ready o stopped; las operaciones que aún se están desplegando devuelven 202 con deploying o stopping.

Eliminar despliegue#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

Elimina permanentemente el endpoint de inferencia.

Comprobación de estado#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

Realiza un ping y calienta el endpoint, devolviendo healthy, latencyMs y el código status del upstream.

Ejecutar inferencia en un despliegue#

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

Ruta una imagen o vídeo a través del endpoint dedicado. Los contratos de solicitud y respuesta coinciden con la inferencia de modelos.

Formulario multiparte:

Obtener métricas#

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

Parámetros de consulta:

La respuesta completa contiene summary (totales de solicitudes, tasa de errores, latencia media y p50/p95/p99) y timeSeries (solicitudes, errores, latencia, CPU, memoria, recuento de instancias). La respuesta de minigráficos (sparkline) devuelve requests24h, totalRequests, errorRate y avgLatencyMs.

Obtener registros#

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

Parámetros de consulta:

API de papelera#

Ver, restaurar y eliminar permanentemente proyectos, conjuntos de datos y modelos eliminados de forma lógica (soft-deleted). Los elementos se depuran automáticamente después de 30 días. Consulta la documentación de la papelera.

Listar papelera#

GET /api/trash

Python SDK: client.lifecycle.trash()

Parámetros de consulta:

La respuesta incluye items (cada uno con daysRemaining), total, page, limit, totalPages y un objeto summary con los totales por tipo.

Restaurar elemento#

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

Restaurar un proyecto también restaura los modelos que fueron enviados a la papelera con él, informados como restoredModels.

Eliminar permanentemente#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

Eliminar un elemento:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

O vaciar toda la papelera:

{
    "all": true
}

La respuesta informa de deletedCount, además de cascadedModels y survivingDeployments cuando corresponda.

API de carga#

Sube archivos directamente al almacenamiento en la nube utilizando URLs firmadas. Completar la subida de un modelo adjunta sus pesos; completar la subida de un archivo comprimido de un conjunto de datos registra la sesión, que luego pasas a la ingesta de conjuntos de datos. Consulta la documentación de datos.

Obtener URL de carga firmada#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

Cuerpo:

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Respuesta:

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

Sube el archivo con una solicitud PUT a uploadUrl, utilizando el mismo Content-Type que declaraste.

Completar carga#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

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

Respuesta: success y un objeto file con size y contentType. Para los modelos, esto adjunta los pesos; para los archivos comprimidos de conjuntos de datos, llama a ingest a continuación para iniciar el procesamiento.

API de integraciones de almacenamiento#

Conecta cuentas de Google Cloud Storage, Amazon S3 o Azure Blob Storage de solo lectura y explóralas como fuentes de conjuntos de datos. Consulta la documentación de integraciones.

Listar integraciones#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Devuelve integrations, cada uno con id, provider, credentialIdentity, targets y createdAt. Las credenciales nunca se devuelven.

Descubrir ubicaciones#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

Lista los buckets o contenedores legibles con las credenciales proporcionadas, sin guardarlas.

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

Respuesta: {"targets": ["my-bucket", "another-bucket"]}

Conectar almacenamiento#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

Las mismas estructuras de credenciales que para el descubrimiento, más un array obligatorio targets de 1 a 50 nombres de buckets o contenedores. Devuelve 201 con la integración almacenada. Las credenciales temporales de S3 (claves de acceso de ASIA) son rechazadas.

Explorar objetos#

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

Python SDK: client.storage_integrations.objects(id, target=...)

Parámetros de consulta:

Devuelve entries (cada kind es folder o file) y un cursor opcional para la página siguiente.

Desconectar almacenamiento#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Elimina las credenciales guardadas sin borrar los datos del proveedor. Los conjuntos de datos conectados siguen siendo visibles, pero sus archivos permanecen no disponibles hasta que se vuelva a conectar la misma cuenta de almacenamiento. Requiere acceso de administrador del espacio de trabajo.

API de importación de conjuntos de datos#

Importa conjuntos de datos desde servicios de terceros. Consulta la integración con Roboflow.

Vista previa de una importación de Roboflow#

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

Resuelve una clave API de Roboflow en un plan de importación: detalles del área de trabajo, newDatasets que se importaría, recuentos de proyectos omitidos, no compatibles y no resueltos, bytesTotal, y tu margen de storage. La clave API de Roboflow se lee del cuerpo y no se persiste.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importar desde Roboflow#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

Pone en cola trabajos de ingestión para un máximo de 500 versiones de proyectos de Roboflow seleccionadas, utilizando los elementos devueltos por la vista previa.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

Respuesta (201): matrices imported, failed y skipped. Las importaciones requieren margen de almacenamiento, y cada conjunto de datos debe ajustarse al límite de tamaño por importación de tu plan.

API de cuenta#

Inspecciona tu cuenta, claves, almacenamiento y perfiles públicos de Platform. Consulta la documentación de configuración.

Resumen de la cuenta#

GET /api/account/summary

Python SDK: client.account.summary()

Devuelve el plan, el saldo de créditos y los recuentos de recursos para el área de trabajo que emitió la clave.

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

Listar claves de API#

GET /api/api-keys

Python SDK: client.account.api_keys()

Devuelve keys con keyId, name, keyPrefix y createdAt para el área de trabajo de la clave. Las solicitudes autenticadas por clave API reciben únicamente metadatos; los valores completos de las claves se muestran al propietario del área de trabajo en Configuración > Claves API en la interfaz de usuario de Platform, que es también donde se crean y revocan las claves.

Comprobar el uso de almacenamiento#

GET /api/storage

Python SDK: client.account.storage()

Parámetros de consulta:

Respuesta:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

Obtener un perfil de usuario público#

GET /api/users

Python SDK: client.account.profile(username=...)

Parámetros de consulta:

Devuelve el perfil público user con followerCount y, para las personas llamadas autenticadas, isFollowed.

Seguir o dejar de seguir a un usuario#

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

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

Respuesta: followed y el followerCount actualizado.

API de facturación#

Comprueba el uso del plan y tu libro mayor de créditos. Consulta la documentación de facturación.

Ver plan y uso#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

Devuelve plan (ID, estado, ciclo de facturación, fin del período), metrics (límite de almacenamiento y uso), trainingCredit, features, creditsCents y recuentos de puestos.

Ver transacciones#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Parámetros de consulta:

Cada transacción incluye id, type (como purchase, training, monthly_grant o refund), amountCents, balanceAfter, createdAt, un receiptUrl opcional y el contexto del modelo para los cargos de entrenamiento. Nunca se devuelven detalles de facturación internos.

API de exploración#

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

Buscar contenido público#

GET /api/explore/search

Python SDK: client.explore.search()

Parámetros de consulta:

Respuesta: projects, datasets y hasMore.

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

SDK de Python#

ultralytics-platform es un cliente de Python con tipos generado a partir del contrato OpenAPI, con un método por punto de conexión (client.datasets.list, client.models.predict, client.exports.create, ...). Cada método acepta los parámetros de ruta de forma posicional, otras entradas como argumentos de palabras clave y timeout y extra_headers opcionales por solicitud.

pip install "ultralytics-platform>=0.1.5" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform expone el mismo árbol de recursos para el código de async/await, las respuestas fallidas generan APIError con status_code, body y json analizados, y los errores de conexión generan APIConnectionError. Consulta el repositorio del SDK para ver el README completo.

Integración con Python#

Para los flujos de trabajo de entrenamiento e inferencia, usa el paquete de Python de Ultralytics, que gestiona la autenticación, las cargas y la transmisión de métricas en tiempo real de forma automática.

Instalación y configuración#

pip install "ultralytics>=8.4.120"

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#