SDK de Python (clore-ai)
El clore-ai paquete es el SDK oficial de Python para el Clore.ai mercado de GPUs. Envuelve toda la API REST en una interfaz limpia y segura en cuanto a tipos, con limitación de velocidad integrada, reintentos automáticos y manejo estructurado de errores, para que puedas centrarte en alquilar GPUs, no en la gestión de HTTP.
Instalación
pip install clore-aiRequisitos: Python 3.9+
El paquete instala tanto el SDK de Python como el clore CLI.
Autenticación
Obtén tu clave API desde el panel de Clore.ai → API sección.
Opción 1: Variable de entorno (recomendada)
export CLORE_API_KEY=your_api_key_hereEl SDK lee CLORE_API_KEY automáticamente — no se necesitan cambios en el código.
Opción 2: Archivo de configuración de la CLI
clore config set api_key YOUR_API_KEYEsto almacena la clave en ~/.clore/config.json.
Opción 3: Pasar directamente en el código
⚠️ Importante: La API de Clore.ai usa el
authencabezado para la autenticación, noAuthorization: Bearer. El SDK lo maneja automáticamente.
Inicio rápido
Cliente síncrono (CloreAI)
Constructor
El cliente admite administradores de contexto para limpieza automática:
wallets()
Obtén los saldos de tus carteras y las direcciones de depósito.
Devuelve: List[Wallet]
name
str
Nombre de la moneda (p. ej. "bitcoin", "CLORE-Blockchain", "USD-Blockchain")
balance
float | None
Saldo actual
deposit
str | None
Dirección de depósito
withdrawal_fee
float | None
Comisión de retiro
marketplace()
Busca en el mercado de GPUs con filtros opcionales en el lado del cliente.
Parámetros:
gpu
str | None
None
Filtrar por modelo de GPU (coincidencia de subcadena sin distinción entre mayúsculas y minúsculas)
min_gpu_count
int | None
None
Número mínimo de GPUs
min_ram_gb
float | None
None
RAM mínima en GB
max_price_usd
float | None
None
Precio máximo por hora en USD
available_only
bool
True
Devuelve solo servidores que estén disponibles para alquilar
Devuelve: List[MarketplaceServer]
Cada MarketplaceServer ofrece propiedades convenientes para los campos más comunes, además de acceso a todos los datos anidados:
id
int
ID único del servidor
gpu_model
str | None
Descripción principal de la GPU (p. ej. "1x NVIDIA GeForce RTX 4090")
gpu_count
int
Número de GPUs (de gpu_array)
ram_gb
float | None
RAM en GB
price_usd
float | None
Precio bajo demanda en USD
spot_price_usd
float | None
Precio spot en USD
available
bool
Si el servidor está disponible (no alquilado)
location
str | None
Código de país de las especificaciones de red
Para casos de uso avanzados, puedes acceder a la estructura anidada completa:
specs
ServerSpecs | None
Especificaciones completas de hardware (specs.gpu, specs.ram, specs.cpu, specs.disk, specs.net, etc.)
precio
ServerPrice | None
Objeto completo de precio (price.usd.on_demand_usd, price.usd.spot, price.on_demand, etc.)
rented
bool | None
Si el servidor está alquilado actualmente
reliability
float | None
Puntuación de fiabilidad del servidor
rating
ServerRating | None
Valoración del servidor (rating.avg, rating.cnt)
Nota: El
marketplace()el endpoint es público — funciona sin clave API.
my_servers()
Enumera los servidores que estás proporcionando al mercado de Clore.ai.
Devuelve: List[MyServer]
id
int
ID del servidor
name
str | None
Nombre del servidor
gpu_model
str | None
Descripción principal de la GPU
ram_gb
float | None
RAM en GB
estado
str
Estado legible: "En línea", "Fuera de línea", "Desconectado", o "No funciona"
conectado
bool | None
Si el servidor está conectado
en línea
bool | None
Si el servidor está en línea
visibilidad
str | None
"público" o "privado"
server_config(server_name)
Obtén la configuración de un servidor específico que hospedas.
Parámetros:
server_name
str
Nombre del servidor
Devuelve: ServerConfig
name
str | None
Nombre del servidor
gpu_model
str | None
Descripción principal de la GPU
mrl
int | None
Duración máxima de alquiler en horas
on_demand_price
float | None
Primer precio disponible en USD bajo demanda
spot_price
float | None
Primer precio spot disponible en USD
specs
ServerSpecs | None
Especificaciones completas de hardware
conectado
bool | None
Si el servidor está conectado
visibilidad
str | None
"público" o "privado"
my_orders(include_completed)
Obtén tus pedidos actuales, incluyendo opcionalmente los completados o expirados.
Parámetros:
include_completed
bool
False
Incluir pedidos completados/expirados
Devuelve: List[Order]
id
int
ID único del pedido
server_id
int | None
ID del servidor
type
str
"on-demand" o "spot"
estado
str | None
Estado del pedido
imagen
str | None
Imagen de Docker
currency
str | None
Moneda de pago
precio
float | None
Precio del pedido por día
pub_cluster
str | None
Nombre de host/IP pública para acceso
tcp_ports
dict | None
Mapeos de puertos TCP
spot_marketplace(server_id)
Ver ofertas del mercado spot para un servidor específico.
Parámetros:
server_id
int
ID del servidor a comprobar
Devuelve: SpotMarket
ofertas
List[SpotOffer] | None
Lista de ofertas spot (order_id, precio, server_id)
server
SpotServerInfo | None
Información del servidor (precio mínimo, visibilidad, estado en línea)
currency_rates_in_usd
Dict[str, float] | None
Tipos de cambio de moneda en USD
create_order(...)
Crea un nuevo pedido bajo demanda o spot. Así es como alquilas una GPU.
Pedido bajo demanda
Pedido spot
Parámetros:
server_id
int
Sí
ID del servidor a alquilar
imagen
str
Sí
Imagen de Docker (p. ej. "cloreai/ubuntu22.04-cuda12")
type
str
Sí
"on-demand" o "spot"
currency
str
Sí
Moneda de pago (p. ej. "bitcoin")
ssh_password
str
No
Contraseña SSH (alfanumérica, máx. 32 caracteres)
ssh_key
str
No
Clave pública SSH (máx. 3072 caracteres)
ports
dict
No
Mapeos de puertos, p. ej. {"22": "tcp", "8888": "http"}
env
dict
No
Variables de entorno
jupyter_token
str
No
Token de Jupyter Notebook (máx. 32 caracteres)
command
str
No
Comando de shell para ejecutar después de iniciar el contenedor
spot_price
float
Solo spot
Precio por día para pedidos spot
required_price
float
No
Bloquea un precio específico (solo bajo demanda)
autossh_entrypoint
str
No
Usa el punto de entrada SSH de Clore.ai
gpu_count
int
No
Alquila solo N GPUs en servidores con alquiler parcial (solo bajo demanda); omite esto para alquilar todo el equipo
gpu_indices
list[int]
No
Ranuras exactas de GPU de partial_gpu_rental.free_indices; la longitud debe ser igual a gpu_count; omite para selección automática
Renovación automática: el SDK (0.1.2 y anteriores) no tiene
create_ordertodavía parámetros pararental_hours,auto_renewoauto_renew_max_price, ni métodos paraset_order_auto_renewoorder_renewals. Hasta que los tenga, llama directamente a esos endpoints REST:create_order,set_order_auto_renewyorder_renewals.Orderlos objetos conservan los campos que añade la API (extra="allow"), así queorder.auto_renew,order.rental_endyorder.term_endson legibles en los pedidos que los incluyen; usegetattr(order, "auto_renew", None)para un campo que un pedido puede no tener.
Devuelve: respuesta bruta de la API ({"code": 0} en caso de éxito); obtén el pedido creado mediante my_orders()
Límite de velocidad:
create_ordertiene una pausa especial de 5 segundos entre llamadas. El SDK la aplica automáticamente.
cancel_order(order_id, issue)
Cancela un pedido activo o una oferta spot. Opcionalmente, informa un problema con el servidor.
Parámetros:
order_id
int
Sí
ID del pedido a cancelar
problema
str
No
Motivo de cancelación / informe de problema (máx. 2048 caracteres)
Devuelve: Dict[str, Any]
set_server_settings(...)
Actualiza la configuración de un servidor que alojas en el mercado.
Parámetros:
name
str
Sí
Nombre del servidor
disponibilidad
bool
No
Si el servidor puede alquilarse
mrl
int
No
Duración máxima de alquiler en horas
bajo demanda
float
No
Precio bajo demanda por día
spot
float
No
Precio mínimo spot por día
Devuelve: Dict[str, Any]
set_spot_price(order_id, price)
Actualiza el precio de tu oferta en el mercado spot.
Parámetros:
order_id
int
ID del pedido/oferta spot
precio
float
Nuevo precio por día
Devuelve: Dict[str, Any]
Nota: Solo puedes bajar los precios spot una vez cada 600 segundos, y con un tamaño de paso limitado. La API devuelve
código: 6con detalles si excedes estos límites.
Cliente asíncrono (AsyncCloreAI)
El AsyncCloreAI el cliente proporciona los mismos métodos que CloreAI, pero todos devuelven corutinas. Úsalo cuando necesites llamadas concurrentes a la API o estés trabajando dentro de una aplicación asíncrona.
Uso básico
Operaciones concurrentes
Ejecuta múltiples llamadas a la API en paralelo con asyncio.gather:
Métodos disponibles
AsyncCloreAI admite todos los mismos métodos que CloreAI:
await wallets()
Obtener saldos de la cartera
await marketplace(...)
Buscar en el mercado
await my_servers()
Lista tus servidores alojados
await server_config(name)
Obtener la configuración del servidor
await my_orders(...)
Lista tus pedidos
await spot_marketplace(server_id)
Obtener ofertas del mercado spot
await create_order(...)
Crear un pedido nuevo
await cancel_order(...)
Cancelar un pedido
await set_server_settings(...)
Actualizar la configuración del servidor
await set_spot_price(...)
Actualizar el precio spot
Manejo de errores
El SDK proporciona clases de excepción estructuradas para cada código de error de la API.
Códigos de error
0
—
Éxito
1
DBError
Error de base de datos
2
InvalidInputError
Datos de entrada no válidos
3
AuthError
Token de API no válido
4
InvalidEndpointError
Endpoint no válido
5
RateLimitError
Límite de velocidad excedido
6
FieldError
Error en un campo específico (ver error campo en la respuesta)
Todas las clases de excepción heredan de CloreAPIError e incluyen:
e.code— código de error numéricoe.response— diccionario completo de respuesta de la API (cuando esté disponible)
Limitación de velocidad
El SDK incluye un limitador de velocidad integrado que aplica automáticamente los límites de Clore.ai:
La mayoría de los endpoints
1 solicitud/segundo
create_order
1 solicitud/5 segundos
Cuando la API devuelve un error de límite de velocidad (código 5), el SDK aplica retroceso exponencial y reintenta hasta max_retries veces (predeterminado: 3). No necesitas añadir time.sleep() entre llamadas.
Cómo funciona
Antes de cada solicitud, el limitador de velocidad espera hasta que transcurra el intervalo mínimo.
create_orderlas llamadas imponen una pausa adicional de 5 segundos.Ante errores de límite de velocidad, el SDK realiza un retroceso exponencial: 1 s → 2 s → 4 s → ...
Después de
max_retriesintentos fallidos, seRateLimitErrorlanza.
Personaliza el comportamiento de reintento
Configuración
Archivo de configuración
La CLI almacena la configuración en ~/.clore/config.json:
Orden de resolución
El SDK resuelve la clave de API en este orden:
api_keyargumento pasado al constructorCLORE_API_KEYvariable de entornoapi_keycampo en~/.clore/config.json
Variables de entorno
CLORE_API_KEY
Clave de API para autenticación
Siguientes pasos
Referencia de la CLI — Usa Clore.ai desde tu terminal
API REST — Documentación bruta de la API para integraciones personalizadas
Bajo demanda vs. spot — Comprende los modelos de precios
Imágenes Docker disponibles — Imágenes precompiladas para cargas de trabajo de GPU
Última actualización
¿Te fue útil?