Referencia de la REST API

Plataforma Ultralytics proporciona una REST API completa para el acceso programático a conjuntos de datos, modelos, entrenamiento y despliegues.

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

Visión general de la API

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

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

Autenticación

La mayoría de las solicitudes de API requieren autenticación mediante clave de API. Los puntos finales públicos (que listan conjuntos de datos, proyectos y modelos públicos) admiten acceso de lectura anónimo sin una clave.

Obtener clave de API

1. Ir a Settings > Profile (sección Claves API)
2. Haz clic Create Key
3. Copia la clave generada

Consulta Claves API para obtener instrucciones detalladas.

Encabezado de autorización

Incluye tu clave API en todas las solicitudes:

Authorization: Bearer ul_your_api_key_here

Ejemplo

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

URL base

Todos los puntos finales de la API utilizan:

https://platform.ultralytics.com/api

Límites de Tasa

La API utiliza un sistema de limitación de velocidad de dos capas para proteger contra el abuso, manteniendo al mismo tiempo el uso legítimo sin restricciones:

• Por clave API — Límites aplicados por clave API en solicitudes autenticadas
• Por IP — 100 solicitudes/min por dirección IP en todas /api/* rutas (aplica tanto a solicitudes autenticadas como no autenticadas)

Cuando se limita, la API devuelve 429 con metadatos de reintento:

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

Límites por clave de API

Los límites de tasa se aplican automáticamente en función del endpoint que se está llamando. Las operaciones costosas tienen límites más estrictos para prevenir el abuso, mientras que las operaciones CRUD estándar comparten un valor predeterminado generoso:

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

Puntos finales dedicados (ilimitados)

Puntos finales dedicados son no sujeto a límites de tasa de clave API. Cuando despliega un modelo en un endpoint dedicado, las solicitudes a esa URL de endpoint (por ejemplo, https://predict-abc123.run.app/predict) van directamente a su servicio dedicado sin limitación de velocidad por parte de la Plataforma. Usted está pagando por la capacidad de cómputo, por lo que obtiene un rendimiento ilimitado hasta la configuración de escalado de su endpoint.

Formato de Respuesta

Respuestas de Éxito

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

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

Respuestas de Error

{
    "error": "Invalid dataset ID"
}

API de Conjuntos de Datos

Gestione colecciones de imágenes etiquetadas para entrenar modelos YOLO.

Listar conjuntos de datos

GET /api/datasets

Parámetros de consulta:

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

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

Respuesta:

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Obtener Conjunto de Datos

GET /api/datasets/{datasetId}

Devuelve los detalles completos del conjunto de datos, incluyendo metadatos, nombres de clases y recuentos de divisiones.

Crear Conjunto de Datos

POST /api/datasets

Cuerpo:

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

Actualizar Conjunto de Datos

PATCH /api/datasets/{datasetId}

Cuerpo (actualización parcial):

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

Eliminar conjunto de datos

DELETE /api/datasets/{datasetId}

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

Clonar Conjunto de Datos

POST /api/datasets/{datasetId}/clone

Crea una copia del conjunto de datos con todas las imágenes y etiquetas. Solo los conjuntos de datos públicos pueden ser clonados.

Cuerpo (todos los campos opcionales):

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

Exportar Conjunto de Datos

GET /api/datasets/{datasetId}/export

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

Parámetros de consulta:

Respuesta:

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

Crear Versión del Conjunto de Datos

POST /api/datasets/{datasetId}/export

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

Cuerpo de la Solicitud:

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

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

Respuesta:

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

Actualizar descripción de la versión

PATCH /api/datasets/{datasetId}/export

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

Cuerpo de la Solicitud:

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

Respuesta:

{
    "ok": true
}

Obtener estadísticas de clase

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

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

Respuesta:

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

Obtener modelos entrenados en el conjunto de datos

GET /api/datasets/{datasetId}/models

Devuelve los modelos que fueron entrenados utilizando este conjunto de datos.

Respuesta:

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

Autoanotar conjunto de datos

POST /api/datasets/{datasetId}/predict

Ejecutar inferencia de YOLO en imágenes del conjunto de datos para auto-generar anotaciones. Utiliza un modelo seleccionado para predecir etiquetas para imágenes sin anotar.

Cuerpo:

Ingesta de Conjunto de Datos

POST /api/datasets/ingest

Crear un trabajo de ingesta de conjunto de datos para procesar archivos ZIP cargados que contienen imágenes y etiquetas.

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

Imágenes del Conjunto de Datos

Listar imágenes

GET /api/datasets/{datasetId}/images

Parámetros de consulta:

Obtener URLs de imagen firmadas

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

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

Eliminar imagen

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

Obtener etiquetas de imagen

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

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

Actualizar Etiquetas de Imagen

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

Cuerpo:

{
    "labels": [{ "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] }]
}

Operaciones Masivas de Imágenes

Mover imágenes entre divisiones (entrenamiento/validación/prueba) dentro de un conjunto de datos:

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

Eliminar imágenes masivamente:

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

API de Proyectos

Gestionar los espacios de trabajo de entrenamiento que agrupan modelos.

Listar Proyectos

GET /api/projects

Parámetros de consulta:

Obtener Proyecto

GET /api/projects/{projectId}

Crear proyecto

POST /api/projects

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

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

Actualizar Proyecto

PATCH /api/projects/{projectId}

Eliminar proyecto

DELETE /api/projects/{projectId}

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

Clonar Proyecto

POST /api/projects/{projectId}/clone

Icono del proyecto

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

POST /api/projects/{projectId}/icon

Eliminar el icono del proyecto:

DELETE /api/projects/{projectId}/icon

API de Modelos

Gestionar los puntos de control de modelos entrenados dentro de los proyectos.

Listar Modelos

GET /api/models

Parámetros de consulta:

Listar modelos completados

GET /api/models/completed

Devuelve los modelos que han finalizado el entrenamiento (para su uso en selectores de modelos y despliegue).

Obtener Modelo

GET /api/models/{modelId}

Crear Modelo

POST /api/models

Cuerpo JSON:

Actualizar Modelo

PATCH /api/models/{modelId}

Eliminar modelo

DELETE /api/models/{modelId}

Descargar archivos del modelo

GET /api/models/{modelId}/files

Devuelve URLs de descarga firmadas para archivos de modelo.

Clonar Modelo

POST /api/models/{modelId}/clone

Clonar un modelo público a uno de sus proyectos.

Cuerpo:

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

Track Descarga

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

Track analíticas de descarga de modelos.

Ejecutar Inferencia

POST /api/models/{modelId}/predict

Formulario Multipart:

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

Respuesta:

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

Obtener token de predicción

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

Obtener un token de corta duración para solicitudes de predicción directas. El token omite el proxy de la API para una inferencia de menor latencia desde aplicaciones del lado del cliente.

Modelo de calentamiento

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

Precargue un modelo para una primera inferencia más rápida. Llame a esto antes de ejecutar predicciones para evitar retrasos en la solicitud inicial.

API de Entrenamiento

Iniciar, supervisar y cancelar trabajos de entrenamiento en la nube.

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

Comenzar el entrenamiento

POST /api/training/start

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

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

Obtener Estado de Entrenamiento

GET /api/models/{modelId}/training

Devuelve el estado actual del trabajo de entrenamiento, las métricas y el progreso de un modelo.

Cancelar Entrenamiento

DELETE /api/models/{modelId}/training

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

API de Despliegues

Cree y gestione endpoints de inferencia dedicados.

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

Listar Despliegues

GET /api/deployments

Parámetros de consulta:

Crear Despliegue

POST /api/deployments

Cuerpo:

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

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

Obtener Despliegue

GET /api/deployments/{deploymentId}

Eliminar Despliegue

DELETE /api/deployments/{deploymentId}

Iniciar Despliegue

POST /api/deployments/{deploymentId}/start

Reanudar una implementación detenida.

Detener Despliegue

POST /api/deployments/{deploymentId}/stop

Pausar una implementación en ejecución (detiene la facturación).

Comprobación del estado

GET /api/deployments/{deploymentId}/health

Devuelve el estado de salud del punto final de despliegue.

Ejecutar inferencia en despliegue

POST /api/deployments/{deploymentId}/predict

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

Formulario Multipart:

Obtener Métricas

GET /api/deployments/{deploymentId}/metrics

Devuelve las métricas de recuentos de solicitudes, latencia y tasa de error con datos de sparkline.

Parámetros de consulta:

Obtener Registros

GET /api/deployments/{deploymentId}/logs

Parámetros de consulta:

API de Monitorización

Métricas Agregadas

GET /api/monitoring

Devuelve métricas agregadas de todas las implementaciones de usuario: solicitudes totales, implementaciones activas, tasa de error y latencia promedio.

API de Exportación

Convertir modelos a formatos optimizados para despliegue en el edge.

Listar Exportaciones

GET /api/exports

Parámetros de consulta:

Crear Exportación

POST /api/exports

Cuerpo:

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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

Formatos admitidos:

Obtener Estado de Exportación

GET /api/exports/{exportId}

Cancelar exportación

DELETE /api/exports/{exportId}

Track Descarga de Exportación

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

API de Actividad

track y gestione los eventos de actividad de su cuenta.

Listar Actividad

GET /api/activity

Parámetros de consulta:

Marcar Eventos Vistos

POST /api/activity/mark-seen

Cuerpo:

{
    "all": true
}

O pasar IDs específicos:

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

Archivar Eventos

POST /api/activity/archive

Cuerpo:

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

O pasar IDs específicos:

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

API de Papelera

Gestionar recursos eliminados de forma lógica (retención de 30 días).

Listar Papelera

GET /api/trash

Parámetros de consulta:

Restaurar Elemento

POST /api/trash

Cuerpo:

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

Eliminar elemento permanentemente

DELETE /api/trash

Cuerpo:

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

Vaciar Papelera

DELETE /api/trash/empty

Elimina permanentemente todos los elementos de la papelera.

API de Facturación

Gestione créditos, suscripciones y métodos de pago.

Obtener Saldo

GET /api/billing/balance

Parámetros de consulta:

Respuesta:

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

Obtener Resumen de Uso

GET /api/billing/usage-summary

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

Obtener transacciones

GET /api/billing/transactions

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

Parámetros de consulta:

Crear Sesión de Pago

POST /api/billing/checkout-session

Cuerpo:

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

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

Crear Pago de Suscripción

POST /api/billing/subscription-checkout

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

Cuerpo:

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

Crear Sesión del Portal

POST /api/billing/portal-session

Devuelve la URL al portal de facturación para la gestión de suscripciones.

Recarga automática

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

Obtener configuración de recarga automática

GET /api/billing/auto-topup

Parámetros de consulta:

Actualizar Configuración de Recarga Automática

PATCH /api/billing/auto-topup

Cuerpo:

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

Métodos de Pago

Listar métodos de pago

GET /api/billing/payment-methods

Crear Intención de Configuración

POST /api/billing/payment-methods/setup

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

Establecer Método de Pago Predeterminado

POST /api/billing/payment-methods/default

Cuerpo:

{
    "paymentMethodId": "pm_123"
}

Actualizar Información de Facturación

PATCH /api/billing/payment-methods

Cuerpo:

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

Eliminar método de pago

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

API de Almacenamiento

Obtener Información de Almacenamiento

GET /api/storage

Respuesta:

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

Recalcular Almacenamiento

POST /api/storage

Activa un recálculo del uso de almacenamiento.

API de carga

Las cargas directas de archivos utilizan un flujo de URL firmada de dos pasos.

Obtener URL de carga firmada

POST /api/upload/signed-url

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

Cuerpo:

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

Respuesta:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Carga completada

POST /api/upload/complete

Notificar a la plataforma que una carga de archivo está completa para que pueda comenzar el procesamiento.

Cuerpo:

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

API de claves API

Listar Claves de API

GET /api/api-keys

Crear Clave de API

POST /api/api-keys

Cuerpo:

{
    "name": "training-server"
}

Eliminar clave API

DELETE /api/api-keys

Parámetros de consulta:

Ejemplo:

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

API de Equipos y Miembros

Gestionar la colaboración en el espacio de trabajo con equipos, miembros e invitaciones.

Listar equipos

GET /api/teams

Crear equipo

POST /api/teams/create

Cuerpo:

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

Listar miembros

GET /api/members

Devuelve los miembros del espacio de trabajo actual.

Invitar a un miembro

POST /api/members

Cuerpo:

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

Actualizar Rol de Miembro

PATCH /api/members/{userId}

Eliminar miembro

DELETE /api/members/{userId}

Transferir propiedad

POST /api/members/transfer-ownership

Invitaciones

Aceptar Invitación

POST /api/invites/accept

Obtener información de invitación

GET /api/invites/info

Parámetros de consulta:

Revocar invitación

DELETE /api/invites/{inviteId}

Reenviar invitación

POST /api/invites/{inviteId}/resend

Explore la API

Buscar contenido público

GET /api/explore/search

Parámetros de consulta:

Datos de la barra lateral

GET /api/explore/sidebar

Devuelve contenido seleccionado para la barra lateral de Explorar.

APIs de Usuario y Configuración

Obtener usuario por nombre de usuario

GET /api/users

Parámetros de consulta:

Seguir o Dejar de Seguir Usuario

PATCH /api/users

Cuerpo:

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

Verificar disponibilidad de nombre de usuario

GET /api/username/check

Parámetros de consulta:

Configuración

GET /api/settings
POST /api/settings

Obtener o actualizar la configuración del perfil de usuario (nombre de visualización, biografía, enlaces sociales, etc.).

Icono de perfil

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

Subir o eliminar avatar de perfil.

Incorporación

POST /api/onboarding

Completar el flujo de incorporación (establecer región de datos, nombre de usuario).

API de GDPR

Puntos de conexión de cumplimiento del RGPD para la exportación y eliminación de datos.

Obtener estado del trabajo GDPR

GET /api/gdpr

Parámetros de consulta:

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

Iniciar flujo de exportación o eliminación

POST /api/gdpr

Cuerpo:

{
    "action": "export"
}

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

Opcional para espacios de trabajo en equipo:

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

Códigos de error

Integración con Python

Para una integración más sencilla, utilice el paquete Python de Ultralytics que maneja la autenticación, las cargas y la transmisión de métricas en tiempo real automáticamente.

Instalación y configuración

pip install ultralytics

Verificar instalación:

yolo check

Autenticación

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Uso de Conjuntos de Datos de la Plataforma

Referenciar conjuntos de datos con ul:// URIs:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

Formato URI:

Envío a la Plataforma

Enviar resultados a un proyecto de la Plataforma:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="ul://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

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, half=True)

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

# Export to CoreML
model.export(format="coreml", imgsz=640)

Validación:

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

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

Webhooks

Los webhooks notifican a su servidor sobre eventos de la Plataforma mediante callbacks HTTP POST:

Preguntas frecuentes

¿Cómo pagino resultados extensos?

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

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

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

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

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

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

¿Puedo usar la API sin un SDK?

Sí, toda la funcionalidad está disponible a través de REST. El SDK de Python es un envoltorio de conveniencia que añade características como la transmisión de métricas en tiempo real y la carga automática de modelos.

¿Existen bibliotecas cliente de la API?

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

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

Utilice el Retry-After encabezado de la respuesta 429 para esperar el tiempo adecuado:

import time

import requests


def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded")

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

Los ID de recursos se devuelven al crear recursos a través de la API. También puede encontrarlos en la URL de la plataforma:

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

Utilice los endpoints de lista para buscar por nombre o filtrar por proyecto.

📅 Creado hace 2 meses ✏️ Actualizado hace 5 días

Comentarios