Claves de API#

Las claves de API de Ultralytics Platform permiten un acceso programático seguro para el entrenamiento remoto, la inferencia y la automatización. Crea claves con nombre y cifrado AES-256-GCM para distintos casos de uso.

Crear una clave de API#

Crea una clave de API nueva:

1. Ve a Ajustes > Claves de API
2. Haz clic en Añadir clave y selecciona Ultralytics como proveedor
3. Introduce un nombre para la clave (p. ej., "Servidor de entrenamiento")
4. Haz clic en Crear clave

Nombre de la clave#

Asigna un nombre descriptivo a tu clave:

• training-server - Para máquinas de entrenamiento remoto
• ci-pipeline - Para la integración de CI/CD
• local-dev - Para el desarrollo local

Visualización de la clave#

Después de crearla, la clave se muestra en un cuadro de diálogo de confirmación:

Claves de proveedor para agentes#

La misma pestaña Configuración > Claves de API también almacena las claves para proveedores de modelos externos utilizados por los Agentes. Solo el propietario del espacio de trabajo puede añadir, reemplazar o eliminar estas claves; los miembros del equipo pueden ver qué proveedores están conectados. Pídele al propietario que conecte un proveedor faltante. Para conectar un proveedor como propietario:

1. Haz clic en Añadir clave.
2. Selecciona el proveedor que coincida con el modelo de lenguaje o de visión y lenguaje de tu flujo de trabajo.
3. Pega la clave de API de ese proveedor en Clave de API y luego haz clic en Guardar clave. El enlace Obtener una clave de API del cuadro de diálogo abre la página de claves del proveedor.

Una clave de Ultralytics no autentica a los proveedores de modelos externos. El uso del proveedor se factura a través de la cuenta de proveedor asociada con la clave guardada. Utiliza el control de edición de la fila de la clave para reemplazar una clave de proveedor.

Formato de la clave#

Las claves de API siguen este formato:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Prefijo: ul_ identifica las claves de Ultralytics
• Cuerpo: 40 caracteres hexadecimales aleatorios
• Total: 43 caracteres

Seguridad de las claves#

• Las claves se almacenan con cifrado AES-256-GCM, nunca en texto plano
• Los primeros 11 caracteres (ul_ más 8 caracteres hexadecimales) actúan como prefijo visible, de modo que se puede identificar una clave sin exponerla

Uso de las claves de API#

Variable de entorno#

Establece tu clave como variable de entorno:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Valida y guarda la clave usando la YOLO CLI en Python>=3.11:

yolo login YOUR_API_KEY

Elimina la clave guardada con yolo logout.

Cabeceras HTTP#

Incluye la clave en las solicitudes a la API:

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

O pásalo al SDK de Python (pip install "ultralytics-platform>=0.1.45"), que lee ULTRALYTICS_API_KEY o la clave guardada por yolo login cuando se omite api_key:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Consulta la referencia de la REST API para ver todos los endpoints disponibles.

Entrenamiento remoto#

Activa la transmisión de métricas con tu clave.

Instala o actualiza el paquete de Ultralytics en Python>=3.11 antes de empezar:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

Consulta Entrenamiento en la nube para obtener la guía completa de entrenamiento remoto.

Gestionar claves#

Ver claves#

Todas las claves aparecen en la pestaña Settings > API Keys:

Cada tarjeta de clave muestra el nombre de la clave, el valor de la clave que se puede copiar, el tiempo relativo desde su creación y un botón para revocarla.

Revocar una clave#

Revoca una clave que se haya visto comprometida o que ya no necesites:

1. Busca la clave en la sección Claves de API
2. Haz clic en el botón Revocar (papelera)
3. Confirma la revocación

Regenerar una clave#

Si una clave se ha visto comprometida:

1. Crea una clave nueva con el mismo nombre
2. Actualiza tus aplicaciones
3. Revoca la clave antigua

Claves de API del espacio de trabajo#

Las claves de API están vinculadas al espacio de trabajo activo en ese momento:

• Espacio de trabajo personal: las claves autentican tu cuenta personal
• Espacio de trabajo de equipo: las claves autentican al propietario del espacio de trabajo del equipo, con permisos completos de propietario en ese espacio de trabajo

Al cambiar de espacio de trabajo en la barra lateral, la sección Claves de API muestra las claves de ese espacio de trabajo. Como una clave de espacio de trabajo tiene permisos de propietario, solo el propietario del espacio de trabajo puede crearla, verla o revocarla. Consulta Equipos para obtener información detallada sobre los roles.

Claves de worker de On Premise#

Al conectar un host de On Premise se genera una clave de worker independiente. Las claves de worker se gestionan desde la integración On Premise en lugar de esta pestaña, nunca aparecen junto a tus claves de API y se revocan al desconectar el host, lo que también cancela los trabajos de ese host que estén en cola o en ejecución.

Prácticas recomendadas de seguridad#

Sí#

• Almacena las claves en variables de entorno
• Usa claves independientes para distintos entornos
• Revoca rápidamente las claves que no utilices
• Rota las claves periódicamente
• Usa nombres descriptivos para identificar la finalidad de las claves

No#

• Incluyas claves en el control de versiones
• Compartas claves entre aplicaciones
• Registres claves en la salida de la aplicación
• Insertes claves en código del lado del cliente

Rotación de claves#

Rota las claves periódicamente por motivos de seguridad:

1. Crea una clave nueva con el mismo nombre
2. Actualiza las aplicaciones para que utilicen la clave nueva
3. Verifica que las aplicaciones funcionan correctamente
4. Revoca la clave antigua

Solución de problemas#

Error de clave no válida#

Error: Invalid API key

Soluciones:

1. Verifica que la clave se haya copiado correctamente (incluido el prefijo ul_)
2. Comprueba que la clave no se haya revocado
3. Confirma que la variable de entorno esté establecida
4. Asegúrate de usar Python>=3.11 y ultralytics>=8.4.120

Permiso denegado#

Error: Permission denied for this operation

Soluciones:

1. Verifica que eres el propietario del recurso o que tienes el acceso adecuado al espacio de trabajo
2. Comprueba que la clave pertenece al espacio de trabajo correcto
3. Si gestionas claves en un espacio de trabajo de equipo, confirma que eres el propietario del espacio de trabajo; los demás roles obtienen Workspace owner access required
4. Crea una clave nueva si es necesario

Límite de solicitudes alcanzado#

Error: Rate limit exceeded

Soluciones:

1. Reduce la frecuencia de las solicitudes; consulta la tabla de límites de solicitudes para conocer los límites por categoría
2. Implementa un retroceso exponencial mediante la cabecera Retry-After
3. Usa un endpoint dedicado cuando necesites capacidad de inferencia aislada

Preguntas frecuentes#