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

Descripción general de la API

La API está organizada 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 una clave de API. Los puntos finales públicos (que enumeran conjuntos de datos, proyectos y modelos públicos) admiten el acceso de lectura anónimo sin necesidad de clave.

Obtener clave de API

1. Ir a Settings > Profile (Sección Claves API)
2. Haga 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, al tiempo que mantiene sin restricciones el uso legítimo:

• Por clave API: límites aplicados por clave API en solicitudes autenticadas.
• Por IP — 100 solicitudes/min por dirección IP en todos los casos. /api/* rutas (se 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

Por límites de clave API

Los límites de velocidad se aplican automáticamente en función del punto final al que se llama. Las operaciones costosas tienen límites más estrictos para evitar abusos, 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 a su asignación predeterminada de 100 solicitudes/min.

Terminales dedicados (ilimitado)

Terminales dedicados son No sujeto a límites de frecuencia de claves API.. Cuando implementas un modelo en un punto final dedicado, las solicitudes a la URL de ese punto final (por ejemplo, https://predict-abc123.run.app/predict) accede directamente a tu servicio dedicado sin limitaciones de velocidad por parte de la plataforma. Pagas por la capacidad de cálculo, por lo que obtienes un rendimiento ilimitado hasta la configuración de escalado de tu punto final.

Formato de Respuesta

Respuestas exitosas

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

Gestiona colecciones de imágenes etiquetadas para entrenar 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 todos los detalles del conjunto de datos, incluidos los metadatos, los nombres de clase y los recuentos de división.

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 temporalmente el conjunto de datos (lo mueve a la papelera, donde se puede recuperar 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 se pueden clonar los conjuntos de datos públicos.

Cuerpo (todos los campos son 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 el archivo de exportación del conjunto de datos.

Respuesta:

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": 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é durante un máximo de 5 minutos.

Respuesta:

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

Obtener modelos entrenados en el conjunto de datos

GET /api/datasets/{datasetId}/models

Devuelve los modelos que se entrenaron 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
}

Anotar automáticamente el conjunto de datos

POST /api/datasets/{datasetId}/predict

Ejecuta YOLO en las imágenes del conjunto de datos para generar automáticamente anotaciones. Utiliza un modelo seleccionado para predecir etiquetas para imágenes sin anotar.

Cuerpo:

Ingesta de conjuntos de datos

POST /api/datasets/ingest

Cree una tarea de ingesta de conjuntos de datos para procesar los 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]

Conjunto de datos Imágenes

Lista de imágenes

GET /api/datasets/{datasetId}/images

Parámetros de consulta:

Obtener URL de imágenes firmadas

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

Obtenga URL firmadas para un lote de hash de imágenes (para mostrar 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 clases para una imagen específica.

Actualizar etiquetas de imágenes

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

Cuerpo:

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

Operaciones masivas con 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 de forma masiva:

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

API de Proyectos

Gestiona espacios de trabajo de formación 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 temporalmente el proyecto (lo mueve a la papelera).

Proyecto Clone

POST /api/projects/{projectId}/clone

Icono del proyecto

Subir un icono del proyecto (formulario multiparte 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 los modelos entrenados dentro de los proyectos.

Listar Modelos

GET /api/models

Parámetros de consulta:

Lista de 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 de modelos

GET /api/models/{modelId}/files

Devuelve URLs de descarga firmadas para archivos de modelo.

Modelo clonado

POST /api/models/{modelId}/clone

Clona un modelo público en uno de tus proyectos.

Cuerpo:

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

Descargar pista

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

Seguimiento de las estadísticas 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 Predict

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

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

Modelo de calentamiento

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

Precargue un modelo para acelerar la primera inferencia. Llame a esto antes de ejecutar predicciones para evitar retrasos en la solicitud inicial.

API de Entrenamiento

Iniciar, supervisar y cancelar trabajos de formación 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 informática en ejecución y marca el trabajo como cancelado.

API de Despliegues

Cree y gestione puntos finales 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. Se puede acceder al punto final de forma global 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 curso (detiene la facturación).

Comprobación del estado

GET /api/deployments/{deploymentId}/health

Devuelve el estado de salud del punto final de implementación.

Ejecutar inferencia en la implementación

POST /api/deployments/{deploymentId}/predict

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

Formulario Multipart:

Obtener Métricas

GET /api/deployments/{deploymentId}/metrics

Devuelve métricas de recuento de solicitudes, latencia y tasa de error con datos de minigráficos.

Parámetros de consulta:

Obtener Registros

GET /api/deployments/{deploymentId}/logs

Parámetros de consulta:

API de supervisión

Métricas agregadas

GET /api/monitoring

Devuelve métricas agregadas de todas las implementaciones de los usuarios: total de solicitudes, implementaciones activas, tasa de error y latencia media.

API de Exportación

Convierta los modelos a formatos optimizados para su implementación en el borde.

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}

Descargar exportación de pista

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 identificadores específicos:

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

Archivar Eventos

POST /api/activity/archive

Cuerpo:

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

O pasar identificadores 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 de forma permanente

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

Gestiona 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 (la más reciente 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 a crédito.

Crear Pago de Suscripción

POST /api/billing/subscription-checkout

Crea una sesión de pago para la actualización 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 sea inferior a un umbral determinado.

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

Lista de 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 nuevo cálculo del uso del almacenamiento.

API de carga

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

Obtener URL de carga firmada

POST /api/upload/signed-url

Solicite una URL firmada para cargar un archivo directamente en el almacenamiento en la nube. La URL firmada omite 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 completa

POST /api/upload/complete

Notifica a la plataforma que se ha completado la carga de un archivo para que pueda comenzar a procesarlo.

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

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

Lista de equipos

GET /api/teams

Crear equipo

POST /api/teams/create

Cuerpo:

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

Miembros de la lista

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 función de miembro

PATCH /api/members/{userId}

Eliminar miembro

DELETE /api/members/{userId}

Transferir la propiedad

POST /api/members/transfer-ownership

Invitaciones

Aceptar invitación

POST /api/invites/accept

Obtener información sobre la 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

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

API de usuario y configuración

Obtener usuario por nombre de usuario

GET /api/users

Parámetros de consulta:

Seguir o dejar de seguir a un usuario

PATCH /api/users

Cuerpo:

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

Comprobar disponibilidad de nombre de usuario

GET /api/username/check

Parámetros de consulta:

Configuración

GET /api/settings
POST /api/settings

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

Icono de perfil

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

Subir o eliminar el avatar del perfil.

Incorporación

POST /api/onboarding

Completa el proceso de incorporación (configura la región de datos y el nombre de usuario).

API de GDPR

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

Obtener el estado del trabajo del RGPD

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 exportación o eliminar flujo

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

Python

Para facilitar la integración, utilice elPython Ultralytics Python , que gestiona automáticamente la autenticación, las cargas y la transmisión de métricas en tiempo real.

Instalación y configuración

pip install ultralytics

Verificar la 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

Conjuntos de datos de referencia con ul:// URI:

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:

Enviar 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)
• Ponderación final de los modelos
• Gráficos de validación
• Salida de la consola
• Métricas del sistema

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

Modelo de exportación:

# 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 tu servidor los eventos de la plataforma mediante devoluciones de llamada 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 Activity y Trash 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 punto final de búsqueda Explore utiliza offset en lugar de page, con un tamaño de página fijo de 20:

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

¿Puedo usar la API sin un SDK?

Sí, todas las funciones están disponibles a través de REST. El Python es un envoltorio práctico 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 puedo encontrar mi ID de modelo o conjunto de datos?

Los ID de recursos se devuelven cuando se crean recursos a través de la API. También se pueden encontrar en la URL de la plataforma:

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

Utiliza los puntos finales de la lista para buscar por nombre o filtrar por proyecto.

📅 Creado hace 1 mes ✏️ Actualizado hace 5 días

Comentarios