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. Escribe un nombre para la clave (por ejemplo, «Servidor de entrenamiento»)
4. Haz clic en Crear clave

Nombre de la clave#

Ponle un nombre descriptivo a la clave:

• training-server - Para máquinas de entrenamiento remoto
• ci-pipeline - Para la integración de CI/CD
• local-dev - Para 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 proveedores para agentes y anotación#

La misma pestaña Ajustes > Claves de API también almacena las claves de proveedores externos de modelos que usan los agentes y los modelos de pago de la anotación guiada por clases; la anotación utiliza la clave guardada en el espacio de trabajo del conjunto de datos. Solo el propietario del espacio de trabajo puede añadir, sustituir o eliminar estas claves; los miembros del equipo pueden ver qué proveedores están conectados. Pide al propietario que conecte cualquier proveedor que falte. Para conectar un proveedor como propietario:

1. Haz clic en Añadir clave.
2. Selecciona el proveedor que corresponda al modelo de lenguaje o de visión y lenguaje de tu flujo de trabajo, o al modelo de anotación que quieras ejecutar.
3. Pega la clave de API del proveedor en Clave de API y 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 sirve para autenticarte con proveedores externos de modelos. El uso de los proveedores se factura a través de la cuenta asociada a la clave guardada. Usa el control de edición de la fila de la clave para sustituir la clave de un proveedor.

Formato de la clave#

Las claves de API tienen 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 sin formato
• Los primeros 11 caracteres (ul_ más 8 caracteres hexadecimales) sirven como prefijo visible, lo que permite identificar una clave sin exponerla

Uso de claves de API#

Variable de entorno#

Define tu clave como variable de entorno:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

CLI de YOLO#

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

yolo login YOUR_API_KEY

Elimina la clave guardada con yolo logout.

Cabeceras HTTP#

Incluye la clave en las solicitudes de API:

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

También puedes pasarla al SDK de Python (pip install "ultralytics-platform>=0.1.45"), que lee ULTRALYTICS_API_KEY o la clave guardada por yolo login si 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 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 ver la guía completa de entrenamiento remoto.

Gestionar claves#

Ver claves#

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

Cada fila de clave muestra el nombre y el prefijo de la clave, la fecha de creación, un botón para copiar la clave completa y un botón para eliminarla (papelera).

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 para eliminarla (papelera)
3. Haz clic en Eliminar clave para confirmar

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 se limitan al espacio de trabajo activo en ese momento:

• Espacio de trabajo personal: las claves te autentican como titular de tu cuenta personal
• Espacio de trabajo de equipo: las claves autentican al propietario del espacio de trabajo del equipo y tienen todos los permisos 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 del espacio de trabajo tiene permisos de propietario, solo el propietario puede crearla, verla o revocarla. Consulta Equipos para obtener información sobre los roles.

Claves de workers locales#

Al conectar un host local, se genera una clave de worker independiente. Las claves de worker se gestionan desde la integración local, no desde 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 en cola y en ejecución de ese host.

Buenas prácticas de seguridad#

Recomendado#

• Guarda las claves en variables de entorno
• Usa claves distintas para cada entorno
• Revoca cuanto antes las claves que no uses
• Rota las claves periódicamente
• Usa nombres descriptivos para identificar la finalidad de cada clave

No lo hagas#

• No incluyas claves en el control de versiones
• No compartas claves entre aplicaciones
• No registres claves en la salida de la aplicación
• No incluyas claves en el código del lado del cliente

Rotación de claves#

Rota las claves periódicamente por seguridad:

1. Crea una clave nueva con el mismo nombre
2. Actualiza las aplicaciones para que usen la clave nueva
3. Comprueba 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. Comprueba que has copiado la clave correctamente (incluido el prefijo ul_)
2. Comprueba que no se haya revocado la clave
3. Confirma que la variable de entorno está definida
4. Asegúrate de que usas Python>=3.11 y ultralytics>=8.4.120

Permiso denegado#

Error: Permission denied for this operation

Soluciones:

1. Comprueba que eres el propietario del recurso o que tienes los permisos adecuados en el 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 reciben 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 ver los límites de cada categoría
2. Implementa una espera exponencial usando la cabecera Retry-After
3. Usa un endpoint dedicado cuando necesites capacidad de inferencia aislada

Preguntas frecuentes#