SDK de Python (clore-ai)

El clore-ai paquete es el SDK oficial de Python para el Clore.ai mercado de GPU. 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 GPU, no en el cableado HTTP.

---

Instalación

pip install clore-ai

Requisitos: Python 3.9+

El paquete instala tanto el SDK de Python como el clore CLI.

---

Autenticación

Obtén tu clave de API desde el panel de control de Clore.ai → API sección.

Opción 1: variable de entorno (recomendado)

export CLORE_API_KEY=your_api_key_here

El 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_KEY

Esto almacena la clave en ~/.clore/config.json.

Opción 3: pásala directamente en el código

from clore_ai import CloreAI

client = CloreAI(api_key="your_api_key_here")

⚠️ Importante: La API de Clore.ai usa el auth encabezado para la autenticación, no Authorization: Bearer. El SDK lo maneja automáticamente.

---

Inicio rápido

from clore_ai import CloreAI

client = CloreAI()
servers = client.marketplace(gpu="RTX 4090", max_price_usd=5.0)
for s in servers:
    print(f"Servidor {s.id}: {s.gpu_model} — ${s.price_usd:.4f}/h")

---

Cliente síncrono (CloreAI)

Constructor

CloreAI(
    api_key: str | None = None,       # Recurre a CLORE_API_KEY de env / config
    base_url: str | None = None,       # Predeterminado: https://api.clore.ai/v1
    timeout: float = 30.0,             # Tiempo de espera de la solicitud en segundos
    max_retries: int = 3               # Intentos de reintento ante errores de límite de velocidad / red
)

El cliente admite gestores de contexto para la limpieza automática:

with CloreAI() as client:
    wallets = client.wallets()
    # client.close() se llama automáticamente

---

wallets()

Obtén los saldos de tus monederos y las direcciones de depósito.

wallets = client.wallets()

for wallet in wallets:
    print(f"{wallet.name}: {wallet.balance:.8f}")
    if wallet.deposit:
        print(f"  Depósito: {wallet.deposit}")

Devuelve: List[Wallet]

Campo	Tipo	Descripción
nombre	str	Nombre de la moneda (p. ej. "bitcoin", "CLORE-Blockchain", "USD-Blockchain")
balance	float | None	Saldo actual
depósito	str | None	Dirección de depósito
comisión de retirada	float | None	Comisión de retirada

---

marketplace()

Busca en el mercado de GPU con filtros opcionales del lado del cliente.

# Todos los servidores disponibles
servers = client.marketplace()

# Filtrar por modelo de GPU y precio máximo
servers = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=5.0
)

# Equipos multi-GPU con mucha RAM
servers = client.marketplace(
    min_gpu_count=4,
    min_ram_gb=128.0
)

Parámetros:

Parámetro	Tipo	Predeterminado	Descripción
gpu	str | None	None	Filtrar por modelo de GPU (coincidencia de subcadena sin distinguir mayúsculas/minúsculas)
min_gpu_count	int | None	None	Número mínimo de GPU
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 disponibles para alquilar

Devuelve: List[MarketplaceServer]

Cada MarketplaceServer proporciona propiedades convenientes para los campos más comunes, además de acceso a todos los datos anidados:

Propiedad	Tipo	Descripción
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 GPU (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:

Campo	Tipo	Descripción
specs	ServerSpecs | None	Especificaciones completas de hardware (specs.gpu, specs.ram, specs.cpu, specs.disk, specs.net, etc.)
price	ServerPrice | None	Objeto de precio completo (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 una clave de API.

---

my_servers()

Lista los servidores que estás proporcionando al mercado de Clore.ai.

my_servers = client.my_servers()

for server in my_servers:
    print(f"{server.name}: {server.gpu_model} [{server.status}]")

Devuelve: List[MyServer]

Propiedad	Tipo	Descripción
id	int	ID del servidor
nombre	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 por humanos: "En línea", "Sin conexión", "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 alojas.

config = client.server_config("MyGPU")

print(f"Servidor: {config.name}")
print(f"GPU: {config.gpu_model}")
print(f"Alquiler mínimo: {config.mrl}h")
print(f"Bajo demanda: ${config.on_demand_price}")
print(f"Spot: ${config.spot_price}")

Parámetros:

Parámetro	Tipo	Descripción
server_name	str	Nombre del servidor

Devuelve: ServerConfig

Propiedad	Tipo	Descripción
nombre	str | None	Nombre del servidor
gpu_model	str | None	Descripción principal de la GPU
mrl	int | None	Duración máxima del alquiler en horas
on_demand_price	float | None	Primer precio USD disponible bajo demanda
spot_price	float | None	Primer precio USD spot disponible
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, opcionalmente incluyendo los completados/vencidos.

# Solo pedidos activos
orders = client.my_orders()

# Incluir pedidos completados
all_orders = client.my_orders(include_completed=True)

for order in orders:
    print(f"Pedido {order.id}: {order.type} — {order.status}")
    if order.pub_cluster:
        print(f"  IP: {order.pub_cluster}")
    if order.tcp_ports:
        print(f"  Puertos: {order.tcp_ports}")

Parámetros:

Parámetro	Tipo	Predeterminado	Descripción
include_completed	bool	False	Incluir pedidos completados/vencidos

Devuelve: List[Order]

Campo	Tipo	Descripción
id	int	ID único del pedido
server_id	int | None	ID del servidor
tipo	str	"on-demand" o "spot"
estado	str | None	Estado del pedido
imagen	str | None	Imagen Docker
currency	str | None	Moneda de pago
price	float | None	Precio del pedido por día
pub_cluster	str | None	Hostname/IP público para acceso
tcp_ports	dict | None	Mapeos de puertos TCP

---

spot_marketplace(server_id)

Consulta las ofertas del mercado spot para un servidor específico.

spot = client.spot_marketplace(server_id=6)

if spot.offers:
    for offer in spot.offers:
        print(f"Pedido {offer.order_id}: ${offer.price}/día (servidor {offer.server_id})")

if spot.currency_rates_in_usd:
    for coin, rate in spot.currency_rates_in_usd.items():
        print(f"  {coin}: ${rate}")

Parámetros:

Parámetro	Tipo	Descripción
server_id	int	ID del servidor a verificar

Devuelve: SpotMarket

Campo	Tipo	Descripción
ofertas	List[SpotOffer] | None	Lista de ofertas spot (order_id, price, server_id)
servidor	SpotServerInfo | None	Información del servidor (precios mínimos, visibilidad, estado en línea)
currency_rates_in_usd	Dict[str, float] | None	Tipos de cambio de divisas en USD

---

create_order(...)

Crea un nuevo pedido bajo demanda o spot. Así es como alquilas una GPU.

Pedido bajo demanda

order = client.create_order(
    server_id=123,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",
    currency="bitcoin",
    ssh_password="MySecurePass123",
    ports={"22": "tcp", "8888": "http"}
)

print(f"Pedido creado: {order.id}")
print(f"Conectar: {order.pub_cluster}")

Pedido spot

order = client.create_order(
    server_id=123,
    image="cloreai/pytorch",
    type="spot",
    currency="bitcoin",
    spot_price=0.000005,
    ssh_password="MySecurePass123",
    ports={"22": "tcp"}
)

Parámetros:

Parámetro	Tipo	Requerido	Descripción
server_id	int	Sí	ID del servidor a alquilar
imagen	str	Sí	Imagen Docker (p. ej. "cloreai/ubuntu22.04-cuda12")
tipo	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 del notebook de Jupyter (máx. 32 caracteres)
command	str	No	Comando de shell a 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 entrypoint SSH de Clore.ai
gpu_count	int	No	Alquila solo N GPUs en servidores con alquiler parcial (solo bajo demanda); omite para alquilar el rig completo
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

Devuelve: respuesta sin procesar de la API ({"code": 0} al tener éxito); obtén la orden creada mediante my_orders()

Límite de tasa: create_order tiene un enfriamiento especial de 5 segundos entre llamadas. El SDK lo aplica automáticamente.

---

cancel_order(order_id, issue)

Cancela una orden activa o una oferta spot. Opcionalmente informa un problema con el servidor.

# Cancelación simple
client.cancel_order(order_id=38)

# Cancelar con reporte de problema
client.cancel_order(
    order_id=38,
    issue="La GPU #1 se estaba sobrecalentando y reduciendo su rendimiento"
)

Parámetros:

Parámetro	Tipo	Requerido	Descripción
order_id	int	Sí	ID de la orden a cancelar
issue	str	No	Motivo de cancelación / reporte de problema (máx. 2048 caracteres)

Devuelve: Dict[str, Any]

---

set_server_settings(...)

Actualiza la configuración de un servidor que alojas en el marketplace.

client.set_server_settings(
    name="MyGPU",
    availability=True,
    mrl=96,
    on_demand=0.0001,
    spot=0.00000113
)

Parámetros:

Parámetro	Tipo	Requerido	Descripción
nombre	str	Sí	Nombre del servidor
availability	bool	No	Si el servidor puede alquilarse
mrl	int	No	Duración máxima del alquiler en horas
on_demand	float	No	Precio por día bajo demanda
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.

client.set_spot_price(order_id=39, price=0.000003)

Parámetros:

Parámetro	Tipo	Descripción
order_id	int	ID de la orden/oferta spot
price	float	Nuevo precio por día

Devuelve: Dict[str, Any]

Nota: Solo puedes bajar los precios spot una vez cada 600 segundos, y en un tamaño de paso limitado. La API devuelve code: 6 con detalles si superas estos límites.

---

Cliente asíncrono (AsyncCloreAI)

El AsyncCloreAI client 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

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI(api_key="your_key") as client:
        wallets = await client.wallets()
        for w in wallets:
            print(f"{w.name}: {w.balance:.8f}")

asyncio.run(main())

Operaciones concurrentes

Ejecuta múltiples llamadas a la API en paralelo con asyncio.gather:

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # Buscar varios modelos de GPU concurrentemente
        rtx4090, rtx3090, a100 = await asyncio.gather(
            client.marketplace(gpu="RTX 4090"),
            client.marketplace(gpu="RTX 3090"),
            client.marketplace(gpu="A100"),
        )

        for name, servers in [("RTX 4090", rtx4090), ("RTX 3090", rtx3090), ("A100", a100)]:
            if servers:
                cheapest = min(s.price_usd or float('inf') for s in servers)
                print(f"{name}: {len(servers)} disponibles, el más barato ${cheapest:.4f}/h")
            else:
                print(f"{name}: no disponible")

asyncio.run(compare_gpus())

Métodos disponibles

AsyncCloreAI admite todos los mismos métodos que CloreAI:

Método	Descripción
await wallets()	Obtener saldos de la cartera
await marketplace(...)	Buscar en el marketplace
await my_servers()	Listar tus servidores alojados
await server_config(name)	Obtener la configuración del servidor
await my_orders(...)	Listar tus órdenes
await spot_marketplace(server_id)	Obtener ofertas del mercado spot
await create_order(...)	Crear una nueva orden
await cancel_order(...)	Cancelar una orden
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 excepciones estructuradas para cada código de error de la API.

from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,      # Clase base para todos los errores de la API
    AuthError,          # Código 3 — clave de API no válida
    RateLimitError,     # Código 5 — se superó el límite de tasa
    InvalidInputError,  # Código 2 — datos de solicitud incorrectos
    DBError,            # Código 1 — error de base de datos
    InvalidEndpointError,  # Código 4 — endpoint no válido
    FieldError,         # Código 6 — error específico de campo
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=123,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin",
    )
except AuthError:
    print("Clave de API no válida. Revisa tu CLORE_API_KEY.")
except RateLimitError:
    print("Límite de tasa alcanzado. El SDK reintenta automáticamente, pero has alcanzado el máximo de reintentos.")
except InvalidInputError as e:
    print(f"Solicitud incorrecta: {e}")
except FieldError as e:
    # Los errores de código 6 incluyen detalles en la respuesta
    print(f"Error de campo: {e} (detalles: {e.response})")
except CloreAPIError as e:
    print(f"Error de la API: {e} (código: {e.code})")

Códigos de error

Código	Excepción	Descripción
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	Se superó el límite de tasa
6	FieldError	Error en un campo específico (consulta error campo en la respuesta)

Todas las clases de excepción heredan de CloreAPIError e incluyen:

• e.code — código de error numérico

• e.response — dict completo de la respuesta de la API (cuando esté disponible)

---

Limitación de tasa

El SDK incluye un limitador de tasa integrado que aplica automáticamente los límites de Clore.ai:

Endpoint	Límite
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 tasa (código 5), el SDK aplica retroceso exponencial e intenta de nuevo hasta max_retries veces (valor predeterminado: 3). No necesitas agregar time.sleep() entre llamadas.

Cómo funciona

1. Antes de cada solicitud, el limitador de tasa espera hasta que haya transcurrido el intervalo mínimo.

2. create_order las llamadas aplican un enfriamiento adicional de 5 segundos.

3. En errores de límite de tasa, el SDK retrocede exponencialmente: 1s → 2s → 4s → ...

4. Después de max_retries intentos fallidos, se lanza RateLimitError un error.

Personalizar el comportamiento de reintento

client = CloreAI(
    max_retries=5,    # Más reintentos para scripts de larga duración
    timeout=60.0      # Tiempo de espera mayor para conexiones lentas
)

---

Configuración

Archivo de configuración

La CLI almacena la configuración en ~/.clore/config.json:

{
  "api_key": "your_api_key_here"
}

Orden de resolución

El SDK resuelve la clave de API en este orden:

1. api_key argumento pasado al constructor

2. CLORE_API_KEY variable de entorno

3. api_key campo en ~/.clore/config.json

Variables de entorno

Variable	Descripción
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 sin procesar de la API para integraciones personalizadas

• Bajo demanda vs spot — Comprende los modelos de precios

• Imágenes de Docker disponibles — Imágenes preconstruidas para cargas de trabajo de GPU