For the complete documentation index, see llms.txt. This page is also available as Markdown.

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-ai

Requisitos: 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_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: Pasar directamente en el código

⚠️ 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


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]

Campo
Tipo
Descripción

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:

Parámetro
Tipo
Predeterminado
Descripción

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:

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 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:

Campo
Tipo
Descripción

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]

Propiedad
Tipo
Descripción

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:

Parámetro
Tipo
Descripción

server_name

str

Nombre del servidor

Devuelve: ServerConfig

Propiedad
Tipo
Descripción

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:

Parámetro
Tipo
Predeterminado
Descripción

include_completed

bool

False

Incluir pedidos completados/expirados

Devuelve: List[Order]

Campo
Tipo
Descripción

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:

Parámetro
Tipo
Descripción

server_id

int

ID del servidor a comprobar

Devuelve: SpotMarket

Campo
Tipo
Descripción

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:

Parámetro
Tipo
Requerido
Descripción

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_order todavía parámetros para rental_hours, auto_renew o auto_renew_max_price, ni métodos para set_order_auto_renew o order_renewals. Hasta que los tenga, llama directamente a esos endpoints REST: create_order, set_order_auto_renew y order_renewals. Order los objetos conservan los campos que añade la API (extra="allow"), así que order.auto_renew, order.rental_end y order.term_end son legibles en los pedidos que los incluyen; use getattr(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_order tiene 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:

Parámetro
Tipo
Requerido
Descripción

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:

Parámetro
Tipo
Requerido
Descripción

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:

Parámetro
Tipo
Descripción

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: 6 con 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:

Método
Descripción

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

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

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érico

  • e.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:

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

  1. Antes de cada solicitud, el limitador de velocidad espera hasta que transcurra el intervalo mínimo.

  2. create_order las llamadas imponen una pausa adicional de 5 segundos.

  3. Ante errores de límite de velocidad, el SDK realiza un retroceso exponencial: 1 s → 2 s → 4 s → ...

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

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:

  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

Última actualización

¿Te fue útil?