Referencia de la REST API#

Ultralytics Platform proporciona una REST API para acceder mediante programación a conjuntos de datos, imágenes, proyectos, modelos, entrenamientos, 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

Descripción general de la API#

La API se organiza en torno a los recursos principales de Platform:

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 de un conjunto de datos público, ejecutar inferencia en un modelo público o buscar en Explorar— 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 Claves de API para obtener instrucciones detalladas.

Cabecera de autorización#

Incluye tu clave de API como token bearer:

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 identifican mediante los mismos nombres legibles que aparecen en las URL de Platform, no mediante identificadores de base de datos:

• {owner} es un nombre de usuario personal o el identificador de un espacio 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 en minúsculas y separado por guiones, con un máximo de 128 caracteres.
• {imageId} y {exportId} son identificadores hexadecimales de 24 caracteres devueltos por la API.
• Cambiar el nombre de un recurso mediante PATCH modifica simultáneamente el name visible y el nombre de la URL, y la respuesta devuelve el nombre actual de la URL para que puedas seguir utilizándolo.

Límites de uso#

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 límite predeterminado.

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

Cuando se aplica una limitación, la API devuelve 429 junto 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 frecuencia de las claves de API de Platform cuando llamas directamente al serviceUrl propio del despliegue (por ejemplo, https://predict-abc123.run.app/predict). En ese caso, el rendimiento depende de la configuración del servicio desplegado.

Formato de respuesta#

Respuestas correctas#

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

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

Las respuestas que contienen datos también incluyen region (us, eu o ap), la región de almacenamiento de ese espacio 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 conjuntos de datos#

Crea, consulta y gestiona conjuntos de datos de imágenes etiquetadas para entrenar modelos YOLO. Consulta la documentación de conjuntos de datos.

Enumerar conjuntos de datos#

GET /api/datasets/{owner}

SDK de Python: 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 espacio 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 conjunto de datos#

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

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

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

Crear conjunto de datos#

POST /api/datasets

SDK de Python: 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"
}

La respuesta devuelve el slug de dataset que se creó realmente, así que léeselo antes de subirlo a menos que configures requireExactSlug.

Respuesta (201):

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

Actualizar conjunto de datos#

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

SDK de Python: 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"
}

Cambiar el nombre modifica el nombre de la URL, así que usa el valor dataset devuelto para las solicitudes posteriores.

Eliminar conjunto de datos#

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

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

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

Clonar conjunto de datos#

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

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

Copia un conjunto de datos accesible, con sus imágenes y etiquetas, en tu espacio de trabajo personal o en el de un 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 origen de almacenamiento conectado devuelven 409 porque sus archivos no se copian.

Descargar una exportación de conjunto de datos#

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

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

Devuelve una URL de descarga NDJSON firmada. Omite v para exportar el estado actual del conjunto de datos y reutilizar la exportación almacenada en caché cuando no haya cambiado nada 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 del conjunto de datos#

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

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

Crea una instantánea numerada e inmutable del conjunto de datos y almacena su exportación 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 devuelve esa instantánea en su lugar.

Actualizar la descripción de la versión#

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

SDK de Python: 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

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

Reconstruye las imágenes, las anotaciones y las clases a partir de una versión guardada sin copiar los datos binarios 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

SDK de Python: 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 ese caso, sampleSize indica cuántas imágenes han contribuido.

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#

Combinar clases (reasigna las anotaciones a una clase de destino y, después, elimina las clases de origen):

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

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

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

Eliminar clases (se eliminan sus anotaciones y los ID de las clases restantes disminuyen):

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

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

{
    "classIds": [2, 4]
}

Ambas operaciones devuelven success, los valores actualizados de classNames y classColors, y un resumen de los cambios realizados (mergedClassIds y targetClassId, o deletedClassIds y deletedAnnotations).

Redistribuir particiones#

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

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

Reasigna aleatoriamente las imágenes entre las particiones. 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).

Embeddings 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 embeddings y devuelve 202 con un 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

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

Devuelve la distribución 2D de UMAP de un análisis completado, paginada con offset y limit (predeterminado y máximo: 50.000). Cada entrada contiene id, umapX, umapY, split, classIds, width, height, bytes, labelCount y missing.

Enumerar modelos entrenados con un conjunto de datos#

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

SDK de Python: 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
}

Enumerar imágenes del conjunto de datos#

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

SDK de Python: 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

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

Devuelve la misma estructura de imagen para un máximo de 1.000 ID de imagen proporcionados y acepta los mismos parámetros de filtro y consulta de URL que la operación de listado.

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

Ingerir datos del conjunto de datos#

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

SDK de Python: 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 assetId pasado a POST /api/upload/signed-url, y la ingestión rechaza una sesión que pertenezca a un conjunto de datos diferente.

Cuerpo (archivo cargado):

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

Cuerpo (archivo remoto o NDJSON):

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

Cuerpo (importación de etiquetas en una ingestión 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. En las importaciones de NDJSON, cada registro puede incluir su propio objeto metadata, que tiene prioridad sobre una entrada coincidente de imageMetadata. Las rutas de archivo están limitadas a 1.024 caracteres, las claves de metadatos de nivel superior a 128 caracteres y cada objeto de metadatos —así como el mapa completo de 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 sobre anotaciones.

Obtener imagen#

GET /api/images/{imageId}

SDK de Python: client.images.retrieve(image_id)

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

Actualizar imagen#

PATCH /api/images/{imageId}

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

Sustituye o 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}

SDK de Python: client.images.delete(image_id)

Elimina permanentemente una imagen y sus anotaciones.

Anotar imagen automáticamente#

POST /api/images/{imageId}/predict

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

Ejecuta inferencia de YOLO en la imagen y devuelve las anotaciones predichas. No las guarda; escribe los resultados de nuevo 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 las del conjunto de datos devuelve 422.

Anota automáticamente un conjunto de datos#

POST /api/datasets/{owner}/{dataset}/predict/batch

SDK de Python: client.datasets.create_batch(owner, dataset, model_id=...)

Guarda una versión de un conjunto de datos, luego pone en cola una ejecución que etiqueta las imágenes sin etiquetar del conjunto de datos con el modelo y devuelve 202. El cuerpo acepta los mismos campos modelId, confidence y iou que el endpoint de imagen única, además de includeAnnotated (por defecto, false) para anotar también las imágenes que ya tienen etiquetas y una matriz opcional classMapping que proporciona el índice de clase del conjunto de datos para cada clase de modelo, o null para omitirlo. Las etiquetas existentes nunca se modifican y la ejecución se factura por las imágenes que procesa realmente. 402 significa que el saldo no cubre la estimación, 409 que el conjunto de datos no está listo, no le quedan imágenes por anotar o ya tiene una ejecución en curso, y 422 que el conjunto de datos no tiene clases: créalas con el classes endpoint antes de llamar a este endpoint, que es lo que hace el paso de asignación de clases de la aplicación antes de iniciar una ejecución.

GET en la misma ruta (client.datasets.batch(owner, dataset)) devuelve la ejecución en curso y su progreso, o la última ejecución terminada hasta que se descarte; DELETE (client.datasets.delete_batch(owner, dataset)) cancela una ejecución en curso o liquida la facturación y descarta el resumen finalizado.

Mover imágenes en bloque#

PATCH /api/images/bulk

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

Mueve hasta 1.000 imágenes de un conjunto de datos a una partición diferente.

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

Los conflictos de nombre de archivo o contenido devuelven 409 hasta que elijas una conflictPolicy para todo el lote de skip, keep_both o replace. La respuesta informa de modifiedCount, skippedCount y targetSplit.

Eliminar imágenes en bloque#

DELETE /api/images/bulk

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

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

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

Obtener URL firmadas de imágenes#

POST /api/images/urls

SDK de Python: 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, ambas identificadas por el ID de imagen.

API de proyectos#

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

Enumerar proyectos#

GET /api/projects/{owner}

SDK de Python: client.projects.list(owner)

Parámetros de consulta:

Obtener proyecto#

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

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

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

Crear proyecto#

POST /api/projects

SDK de Python: 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}

SDK de Python: 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 128 caracteres por clave y de 500.000 caracteres por objeto serializado que los metadatos del conjunto de datos.

Eliminar proyecto#

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

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

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

Clonar un proyecto#

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

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

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

API de modelos#

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

Enumerar modelos de un proyecto#

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

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

Parámetros de consulta:

Obtener modelo#

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

SDK de Python: 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, entre otros—, además de isOwner.

Crear modelo#

POST /api/models

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

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

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

Actualizar modelo#

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

SDK de Python: 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. Pasar projectId por sí solo mueve el modelo a otro proyecto del mismo propietario; la respuesta devuelve el slug del modelo en el destino, renamed: true cuando ese slug ya estaba ocupado allí y 409 mientras el modelo sigue entrenando.

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

El metadata personalizado 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}

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

Mueve el modelo a la papelera durante 30 días.

Descargar archivos del modelo#

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

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

Devuelve URL 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

SDK de Python: 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

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

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

Formulario multipart:

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 de images contiene shape, speed, results y, para tareas de predicción densa, un payload PNG semantic_mask o depth (los valores de profundidad son pixel × max / divisor, con divisor 255 para el mapa de 8 bits predeterminado y 65535 cuando bits es 12 o 16). El objeto metadata informa del número 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],
            "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

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

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

Cancela el entrenamiento#

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

SDK de Python: 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 GPU en la nube y supervisa el progreso en tiempo real. Consulta la documentación sobre entrenamiento en la nube.

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

Consultar la disponibilidad de GPU#

GET /api/training/gpu-availability

SDK de Python: client.training.gpu_availability()

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

Iniciar entrenamiento#

POST /api/training/start

SDK de Python: 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 implementación en el edge. Consulta la documentación sobre implementación.

Enumerar exportaciones#

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

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

Parámetros de consulta:

Crear exportación#

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

SDK de Python: 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 compatibles:

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

nms=None se establece por defecto en salidas sin procesar para la NMS externa. Configura nms=False para seleccionar una cabeza libre de NMS disponible; los formatos no compatibles recurren a su ruta de salida nativa. Las entradas nms anteriores identifican los formatos que pueden incrustar la NMS con nms=True.

Consultar el estado de la exportación#

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

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

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

Cancelar o eliminar una exportación#

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

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

Cancela una exportación activa o elimina una finalizada y su archivo. La respuesta indica cuál de las dos acciones se ha realizado:

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

API de implementaciones#

Implementa modelos en endpoints de inferencia dedicados con comprobaciones de estado y supervisión. Consulta la documentación sobre 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

Enumerar implementaciones#

GET /api/deployments/{owner}

SDK de Python: client.deployments.list(owner)

Parámetros de consulta:

Los usuarios anónimos deben filtrar por un modelo público; para enumerar todo un espacio de trabajo se requiere autenticación.

Crear implementación#

POST /api/deployments/{owner}

SDK de Python: 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.

Consultar implementación#

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

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

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

Iniciar, detener o sustituir una implementación#

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

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

Un único campo action selecciona la operación:

{ "action": "start" }

La sustitución implementa una nueva revisión mientras conserva el ID de la implementación, la región y la URL del endpoint; la revisión existente sigue activa si falla la implementación. El modelo de sustitución debe ser un modelo completado con pesos a los que tu clave tenga acceso. Las operaciones completadas devuelven 200 con status, ready o stopped; las operaciones que todavía se están implementando devuelven 202 con deploying o stopping.

Eliminar implementación#

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

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

Elimina permanentemente el endpoint de inferencia.

Comprobación del estado#

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

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

Hace ping al endpoint y lo prepara, y devuelve healthy, latencyMs y el código ascendente status.

Ejecutar inferencia en una implementación#

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

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

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

Formulario multipart:

Consultar métricas#

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

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

Parámetros de consulta:

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

Consultar registros#

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

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

Parámetros de consulta:

API de papelera#

Consulta, restaura y elimina permanentemente proyectos, datasets y modelos eliminados de forma temporal. Los elementos se purgan automáticamente después de 30 días. Consulta la documentación de la papelera.

Enumerar la Papelera#

GET /api/trash

SDK de Python: client.lifecycle.trash()

Parámetros de consulta:

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

Restaurar elemento#

POST /api/trash

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

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

Al restaurar un proyecto también se restauran los modelos que se enviaron a la papelera con él, indicados como restoredModels.

Eliminar permanentemente#

DELETE /api/trash

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

Elimina un elemento:

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

O vacía toda la papelera:

{
    "all": true
}

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

API de cargas#

Carga archivos directamente en el almacenamiento en la nube mediante URL firmadas. Al completar la carga de un modelo se asocian sus pesos; al completar la carga de un archivo de dataset se registra la sesión, que después pasas a la ingesta del dataset. Consulta la documentación sobre datos.

Obtener URL de carga firmada#

POST /api/upload/signed-url

SDK de Python: 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",
    "headers": { "x-goog-if-generation-match": "0" }
}

Sube el archivo con una petición de PUT a uploadUrl, utilizando el mismo Content-Type que declaraste y cada cabecera devuelta en headers. Las URL de subida de conjuntos de datos son válidas durante 12 horas y son de solo creación: una segunda PUT a la misma URL devuelve 412, y una PUT sin las cabeceras devueltas devuelve 400.

Completar carga#

POST /api/upload/complete

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

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

Respuesta: success y un objeto file con size y contentType. En el caso de los modelos, esto asocia los pesos; para los archivos de dataset, llama después a ingest para iniciar el procesamiento.

Cuando se proporciona md5, se comprueba con el objeto almacenado. Una discrepancia devuelve 400; en una sesión que aún no está completa, también borra el archivo subido y deja la sesión incompleta, así que solicita una nueva URL firmada y vuelve a subirlo . Una sesión de conjunto de datos completada se puede volver a completar mientras exista su archivo, pero las finalizaciones concurrentes con diferentes resúmenes devuelven 409; las sesiones de modelos se eliminan al completarse. checksum se almacena como metadatos del archivo del modelo y no se verifica.

API de integraciones de almacenamiento#

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

Enumerar integraciones#

GET /api/integrations/buckets

SDK de Python: 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

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

Enumera los buckets o contenedores legibles con las credenciales proporcionadas, sin guardarlos.

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

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

Las mismas estructuras de credenciales que en el descubrimiento, además de una matriz targets obligatoria con entre 1 y 50 nombres de buckets o contenedores. Devuelve 201 con la integración almacenada. Las credenciales temporales de S3 (claves de acceso ASIA) se rechazan.

Examinar objetos#

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

SDK de Python: 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}

SDK de Python: client.storage_integrations.delete(id)

Elimina las credenciales guardadas sin borrar los datos del proveedor. Los conjuntos de datos conectados siguen 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 de Roboflow.

Previsualizar una importación de Roboflow#

POST /api/integrations/roboflow/preview

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

Resuelve una clave de API de Roboflow en un plan de importación: detalles del espacio de trabajo, newDatasets que se importarían, recuentos de proyectos omitidos, no compatibles y no resueltos, bytesTotal y el margen disponible de storage. La clave de API de Roboflow se lee del cuerpo y no se guarda.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importar desde Roboflow#

POST /api/integrations/roboflow/import

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

Pone en cola trabajos de ingesta para un máximo de 500 versiones de proyectos de Roboflow seleccionadas, usando los elementos devueltos por la previsualización.

{
    "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 la cuenta#

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

Resumen de la cuenta#

GET /api/account/summary

SDK de Python: client.account.summary()

Devuelve el plan, el saldo de créditos y los recuentos de recursos del espacio 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": []
}

Enumerar claves de API#

GET /api/api-keys

SDK de Python: client.account.api_keys()

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

Comprobar el uso del almacenamiento#

GET /api/storage

SDK de Python: 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

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

Parámetros de consulta:

Devuelve el perfil público user con followerCount y, para los solicitantes autenticados, isFollowed.

Seguir o dejar de seguir a un usuario#

PATCH /api/users

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

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

Respuesta: followed y followerCount actualizado.

API de facturación#

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

Ver el plan y el uso#

GET /api/billing/usage-summary

SDK de Python: client.billing.usage_summary()

Devuelve plan (ID, estado, ciclo de facturación, final del periodo), metrics (límite y uso del almacenamiento), trainingCredit, features, creditsCents y el número de puestos.

Ver transacciones#

GET /api/billing/transactions

SDK de Python: 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. Los detalles internos de facturación nunca se devuelven.

Explorar API#

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

Buscar contenido público#

GET /api/explore/search

SDK de Python: 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 Python con tipos generado a partir del contrato OpenAPI, con un método por endpoint (client.datasets.list, client.models.predict, client.exports.create, ...). Cada método acepta los parámetros de ruta posicionalmente, el resto de entradas como argumentos con nombre y timeout y extra_headers opcionales por solicitud.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY or the key saved by yolo login
    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 no satisfactorias generan APIError con status_code, body y json analizado, y los fallos de conexión generan APIConnectionError. Consulta el repositorio del SDK para ver el README completo.

Integración con Python#

Para flujos de trabajo de entrenamiento e inferencia, usa el paquete de Python de Ultralytics, que gestiona la autenticación, las subidas y la transmisión de métricas en tiempo real de forma automática. En Python 3.11+, pip install ultralytics también instala el SDK ultralytics-platform. Cuando model.train(project=...) apunta a Platform, las devoluciones de llamada de entrenamiento transmiten eventos a través de client.training.metrics() del SDK y solicitan URLs de subida de puntos de control a través de client.models.upload_checkpoint(), las operaciones POST /api/webhooks/training/metrics y POST /api/webhooks/models/upload en el documento OpenAPI, por lo que no hay nada que tengas que llamar por tu cuenta.

Instalación y configuración#

La integración en la plataforma requiere Python>=3.11 y ultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

Verifica la instalación:

yolo check

Autenticación#

yolo login YOUR_API_KEY

Usar conjuntos de datos de Platform#

Haz referencia a conjuntos de datos con URI 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 Platform#

Envía los resultados a un proyecto de Platform:

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 la consola
• Métricas del sistema
• Argumentos de entrenamiento y entorno del host (nombre de host, SO, Python, hardware, confirmación de git, línea de comandos)

Ejemplos de API#

Cargar un modelo desde Platform:

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

Preguntas frecuentes#