Python SDK (clore-ai)

Das clore-ai Paket ist das offizielle Python-SDK für das Clore.ai GPU-Marktplatz. Es kapselt die gesamte REST-API in einer sauberen, typsicheren Schnittstelle mit integrierter Ratenbegrenzung, automatischen Wiederholungen und strukturierter Fehlerbehandlung — damit Sie sich auf das Mieten von GPUs konzentrieren können und nicht auf HTTP-Details.

---

Installation

pip install clore-ai

Anforderungen: Python 3.9+

Das Paket installiert sowohl das Python-SDK als auch die clore CLI.

---

Authentifizierung

Holen Sie sich Ihren API-Schlüssel vom Clore.ai-Dashboard → API Abschnitt.

Option 1: Umgebungsvariable (empfohlen)

export CLORE_API_KEY=your_api_key_here

Das SDK liest CLORE_API_KEY automatisch — keine Codeänderungen erforderlich.

Option 2: CLI-Konfigurationsdatei

clore config set api_key YOUR_API_KEY

Dies speichert den Schlüssel in ~/.clore/config.json.

Option 3: Direkt im Code übergeben

from clore_ai import CloreAI

client = CloreAI(api_key="your_api_key_here")

⚠️ Wichtig: Die Clore.ai-API verwendet den auth Header für die Authentifizierung, nicht Authorization: Bearer. Das SDK kümmert sich automatisch darum.

---

Schnellstart

from clore_ai import CloreAI

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

---

Synchroner Client (CloreAI)

Konstruktor

CloreAI(
    api_key: str | None = None,       # Fällt auf CLORE_API_KEY env / config zurück
    base_url: str | None = None,       # Standard: https://api.clore.ai/v1
    timeout: float = 30.0,             # Anfrage-Timeout in Sekunden
    max_retries: int = 3               # Anzahl der Wiederholungsversuche bei Rate-Limit- / Netzwerkfehlern
)

Der Client unterstützt Kontextmanager für automatische Aufräumarbeiten:

with CloreAI() as client:
    wallets = client.wallets()
    # client.close() wird automatisch aufgerufen

---

wallets()

Holen Sie Ihre Wallet-Salden und Einzahlungsadressen.

wallets = client.wallets()

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

Gibt zurück: List[Wallet]

Feld	Typ	Beschreibung
name	str	Währungsname (z. B. "bitcoin", "CLORE-Blockchain", "USD-Blockchain")
balance	float | None	Aktueller Saldo
deposit	str | None	Einzahlungsadresse
withdrawal_fee	float | None	Auszahlungsgebühr

---

marketplace()

Durchsuchen Sie den GPU-Marktplatz mit optionalen clientseitigen Filtern.

# Alle verfügbaren Server
servers = client.marketplace()

# Nach GPU-Modell und Max-Preis filtern
servers = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=5.0
)

# Multi-GPU-Rigs mit viel RAM
servers = client.marketplace(
    min_gpu_count=4,
    min_ram_gb=128.0
)

Parameter:

Parameter	Typ	Standard	Beschreibung
gpu	str | None	None	Nach GPU-Modell filtern (case-insensitiver Teilstring-Vergleich)
min_gpu_count	int | None	None	Minimale Anzahl von GPUs
min_ram_gb	float | None	None	Minimale RAM-Größe in GB
max_price_usd	float | None	None	Maximaler Preis pro Stunde in USD
available_only	bool	True	Nur Server zurückgeben, die zur Miete verfügbar sind

Gibt zurück: List[MarketplaceServer]

Jeder MarketplaceServer bietet komfortable Eigenschaften für die gebräuchlichsten Felder sowie Zugriff auf die vollständigen verschachtelten Daten:

Eigenschaft	Typ	Beschreibung
id	int	Eindeutige Server-ID
gpu_model	str | None	Primäre GPU-Beschreibung (z. B. "1x NVIDIA GeForce RTX 4090")
gpu_count	int	Anzahl der GPUs (aus gpu_array)
ram_gb	float | None	RAM in GB
price_usd	float | None	On-Demand-Preis in USD
spot_price_usd	float | None	Spot-Preis in USD
available	bool	Ob der Server verfügbar ist (nicht vermietet)
location	str | None	Ländercode aus den Netzwerkspezifikationen

Für fortgeschrittene Anwendungsfälle können Sie auf die vollständige verschachtelte Struktur zugreifen:

Feld	Typ	Beschreibung
specs	ServerSpecs | None	Vollständige Hardware-Spezifikationen (specs.gpu, specs.ram, specs.cpu, specs.disk, specs.net, usw.)
price	ServerPrice | None	Vollständiges Preisobjekt (price.usd.on_demand_usd, price.usd.spot, price.on_demand, usw.)
rented	bool | None	Ob der Server derzeit vermietet ist
reliability	float | None	Server-Zuverlässigkeitswert
rating	ServerRating | None	Serverbewertung (rating.avg, rating.cnt)

Hinweis: Das marketplace() Der Endpunkt ist öffentlich — er funktioniert ohne API-Schlüssel.

---

my_servers()

Liste der Server, die Sie auf dem Clore.ai-Marktplatz bereitstellen.

my_servers = client.my_servers()

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

Gibt zurück: List[MyServer]

Eigenschaft	Typ	Beschreibung
id	int	Server-ID
name	str | None	Servername
gpu_model	str | None	Primäre GPU-Beschreibung
ram_gb	float | None	RAM in GB
status	str	Menschlich lesbarer Status: "Online", "Offline", "Getrennt", oder "Funktioniert nicht"
connected	bool | None	Ob der Server verbunden ist
online	bool | None	Ob der Server online ist
visibility	str | None	"public" oder "private"

---

server_config(server_name)

Holen Sie die Konfiguration eines bestimmten Servers, den Sie hosten.

config = client.server_config("MyGPU")

print(f"Server: {config.name}")
print(f"GPU: {config.gpu_model}")
print(f"Minimale Mietdauer: {config.mrl}h")
print(f"On-Demand: ${config.on_demand_price}")
print(f"Spot: ${config.spot_price}")

Parameter:

Parameter	Typ	Beschreibung
server_name	str	Name des Servers

Gibt zurück: ServerConfig

Eigenschaft	Typ	Beschreibung
name	str | None	Servername
gpu_model	str | None	Primäre GPU-Beschreibung
mrl	int | None	Minimale Mietdauer in Stunden
on_demand_price	float | None	Erster verfügbarer On-Demand-Preis in USD
spot_price	float | None	Erster verfügbarer Spot-Preis in USD
specs	ServerSpecs | None	Vollständige Hardware-Spezifikationen
connected	bool | None	Ob der Server verbunden ist
visibility	str | None	"public" oder "private"

---

my_orders(include_completed)

Holen Sie Ihre aktuellen Bestellungen, optional einschließlich abgeschlossener/abgelaufener.

# Nur aktive Bestellungen
orders = client.my_orders()

# Abgeschlossene Bestellungen einbeziehen
all_orders = client.my_orders(include_completed=True)

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

Parameter:

Parameter	Typ	Standard	Beschreibung
include_completed	bool	False	Abgeschlossene/abgelaufene Bestellungen einbeziehen

Gibt zurück: List[Order]

Feld	Typ	Beschreibung
id	int	Eindeutige Bestell-ID
server_id	int | None	Server-ID
type	str	"on-demand" oder "spot"
status	str | None	Bestellstatus
image	str | None	Docker-Image
currency	str | None	Zahlungswährung
price	float | None	Bestellpreis pro Tag
pub_cluster	str | None	Öffentlicher Hostname/IP für den Zugriff
tcp_ports	dict | None	TCP-Portzuordnungen

---

spot_marketplace(server_id)

Spotmarktangebote für einen bestimmten Server anzeigen.

spot = client.spot_marketplace(server_id=6)

if spot.offers:
    for offer in spot.offers:
        print(f"Order {offer.order_id}: ${offer.price}/day (server {offer.server_id})")

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

Parameter:

Parameter	Typ	Beschreibung
server_id	int	Zu prüfende Server-ID

Gibt zurück: SpotMarket

Feld	Typ	Beschreibung
offers	List[SpotOffer] | None	Liste der Spot-Angebote (order_id, price, server_id)
server	SpotServerInfo | None	Serverinformationen (Mindestpreise, Sichtbarkeit, Online-Status)
currency_rates_in_usd	Dict[str, float] | None	Währungswechselkurse in USD

---

create_order(...)

Erstellen Sie eine neue On-Demand- oder Spot-Bestellung. So mieten Sie eine GPU.

On-Demand-Bestellung

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"Order erstellt: {order.id}")
print(f"Verbinden: {order.pub_cluster}")

Spot-Bestellung

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

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
server_id	int	Ja	Zu mietende Server-ID
image	str	Ja	Docker-Image (z. B. "cloreai/ubuntu22.04-cuda12")
type	str	Ja	"on-demand" oder "spot"
currency	str	Ja	Zahlungswährung (z. B. "bitcoin")
ssh_password	str	Nein	SSH-Passwort (alphanumerisch, max. 32 Zeichen)
ssh_key	str	Nein	SSH Public Key (max. 3072 Zeichen)
ports	dict	Nein	Portzuordnungen, z. B. {"22": "tcp", "8888": "http"}
env	dict	Nein	Umgebungsvariablen
jupyter_token	str	Nein	Jupyter-Notebook-Token (max. 32 Zeichen)
command	str	Nein	Shell-Befehl, der nach dem Start des Containers ausgeführt wird
spot_price	float	Nur Spot	Preis pro Tag für Spot-Bestellungen
required_price	float	Nein	Sperren Sie einen bestimmten Preis (nur On-Demand)
autossh_entrypoint	str	Nein	Clore.ai SSH-Entrypoint verwenden

Gibt zurück: Bestellung

Ratenlimit: create_order hat eine spezielle 5-Sekunden-Abkühlzeit zwischen Aufrufen. Das SDK erzwingt dies automatisch.

---

cancel_order(order_id, issue)

Stornieren Sie eine aktive Bestellung oder ein Spot-Angebot. Optional können Sie ein Problem mit dem Server melden.

# Einfache Stornierung
client.cancel_order(order_id=38)

# Stornierung mit Problemmeldung
client.cancel_order(
    order_id=38,
    issue="GPU #1 überhitzte und drosselte"
)

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
order_id	int	Ja	Zu stornierende Bestell-ID
issue	str	Nein	Stornierungsgrund / Problemmeldung (max. 2048 Zeichen)

Gibt zurück: Dict[str, Any]

---

set_server_settings(...)

Aktualisieren Sie die Einstellungen für einen Server, den Sie auf dem Marktplatz hosten.

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

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
name	str	Ja	Servername
availability	bool	Nein	Ob der Server gemietet werden kann
mrl	int	Nein	Minimale Mietdauer in Stunden
on_demand	float	Nein	On-Demand-Preis pro Tag
spot	float	Nein	Minimaler Spot-Preis pro Tag

Gibt zurück: Dict[str, Any]

---

set_spot_price(order_id, price)

Aktualisieren Sie den Preis für Ihr Spot-Angebot.

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

Parameter:

Parameter	Typ	Beschreibung
order_id	int	Spot-Bestell-/Angebots-ID
price	float	Neuer Preis pro Tag

Gibt zurück: Dict[str, Any]

Hinweis: Sie können Spot-Preise nur alle 600 Sekunden und nur in begrenzten Schritten senken. Die API gibt code: 6 mit Details zurück, wenn Sie diese Grenzen überschreiten.

---

Asynchroner Client (AsyncCloreAI)

Das AsyncCloreAI client stellt dieselben Methoden wie CloreAI, aber alle geben Koroutinen zurück. Verwenden Sie ihn, wenn Sie gleichzeitige API-Aufrufe benötigen oder in einer asynchronen Anwendung arbeiten.

Grundlegende Verwendung

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

Gleichzeitige Operationen

Führen Sie mehrere API-Aufrufe parallel mit asyncio.gather:

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # Mehrere GPU-Modelle gleichzeitig suchen
        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)} verfügbar, günstigster ${cheapest:.4f}/h")
            else:
                print(f"{name}: keine verfügbar")

asyncio.run(compare_gpus())

Verfügbare Methoden

AsyncCloreAI unterstützt alle dieselben Methoden wie CloreAI:

Methode	Beschreibung
await wallets()	Wallet-Salden abrufen
await marketplace(...)	Marktplatz durchsuchen
await my_servers()	Ihre gehosteten Server auflisten
await server_config(name)	Serverkonfiguration abrufen
await my_orders(...)	Ihre Bestellungen auflisten
await spot_marketplace(server_id)	Spotmarkt-Angebote abrufen
await create_order(...)	Neue Bestellung erstellen
await cancel_order(...)	Bestellung stornieren
await set_server_settings(...)	Servereinstellungen aktualisieren
await set_spot_price(...)	Spot-Preis aktualisieren

---

Fehlerbehandlung

Das SDK stellt strukturierte Ausnahmeklassen für jeden API-Fehlercode bereit.

from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,      # Basisklasse für alle API-Fehler
    AuthError,          # Code 3 — ungültiger API-Schlüssel
    RateLimitError,     # Code 5 — Ratenlimit überschritten
    InvalidInputError,  # Code 2 — fehlerhafte Anfrage-Daten
    DBError,            # Code 1 — Datenbankfehler
    InvalidEndpointError,  # Code 4 — ungültiger Endpunkt
    FieldError,         # Code 6 — feldspezifischer Fehler
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=123,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin",
    )
except AuthError:
    print("Ungültiger API-Schlüssel. Überprüfen Sie Ihren CLORE_API_KEY.")
except RateLimitError:
    print("Rate limit erreicht. Das SDK versucht automatisch erneut, aber Sie haben die maximale Anzahl von Versuchen erreicht.")
except InvalidInputError as e:
    print(f"Ungültige Anfrage: {e}")
except FieldError as e:
    # Code-6-Fehler enthalten Details in der Antwort
    print(f"Feldfehler: {e} (Details: {e.response})")
except CloreAPIError as e:
    print(f"API-Fehler: {e} (Code: {e.code})")

Fehlercodes

Code	Ausnahme	Beschreibung
0	—	Erfolg
1	DBError	Datenbankfehler
2	InvalidInputError	Ungültige Eingabedaten
3	AuthError	Ungültiges API-Token
4	InvalidEndpointError	Ungültiger Endpunkt
5	RateLimitError	Rate-Limit überschritten
6	FieldError	Fehler in einem bestimmten Feld (siehe error Feld in der Antwort)

Alle Ausnahmeklassen erben von CloreAPIError und enthalten:

• e.code — numerischer Fehlercode

• e.response — vollständiges API-Antwort-Objekt (wenn verfügbar)

---

Rate Limiting

Das SDK enthält einen eingebauten Ratenbegrenzer, der die Limits von Clore.ai automatisch durchsetzt:

Endpunkt	Limit
Die meisten Endpunkte	1 Anfrage/Sekunde
create_order	1 Anfrage/5 Sekunden

Wenn die API einen Rate-Limit-Fehler (Code 5) zurückgibt, wendet das SDK exponentielles Backoff an und wiederholt bis zu max_retries Versuche (Standard: 3). Sie müssen kein time.sleep() zwischen Aufrufen hinzufügen.

Funktionsweise

1. Vor jeder Anfrage wartet der Ratenbegrenzer, bis das minimale Intervall verstrichen ist.

2. create_order Aufrufe erzwingen eine zusätzliche 5-Sekunden-Abkühlzeit.

3. Bei Rate-Limit-Fehlern verringert das SDK die Wiederholungen exponentiell: 1s → 2s → 4s → ...

4. Nach max_retries fehlgeschlagenen Versuchen wird eine RateLimitError ausgelöst.

Anpassen des Wiederholungsverhaltens

client = CloreAI(
    max_retries=5,    # Mehr Versuche für lang laufende Skripte
    timeout=60.0      # Längere Zeitüberschreitung für langsame Verbindungen
)

---

Konfiguration

Konfigurationsdatei

Die CLI speichert die Konfiguration in ~/.clore/config.json:

{
  "api_key": "your_api_key_here"
}

Behebungsreihenfolge

Das SDK löst den API-Schlüssel in folgender Reihenfolge auf:

1. api_key als Argument an den Konstruktor übergeben

2. CLORE_API_KEY Umgebungsvariable

3. api_key Feld in ~/.clore/config.json

Umgebungsvariablen

Variable	Beschreibung
CLORE_API_KEY	API-Schlüssel zur Authentifizierung

---

Nächste Schritte

• CLI-Referenz — Verwenden Sie Clore.ai über Ihr Terminal

• REST-API — Rohdokumentation der API für benutzerdefinierte Integrationen

• On-Demand vs Spot — Preisgestaltungsmodelle verstehen

• Verfügbare Docker-Images — Vorgefertigte Images für GPU-Workloads