Python-SDK (clore-ai)

Das clore-ai Paket ist das offizielle Python-SDK für den Clore.ai GPU-Marktplatz. Es kapselt die gesamte REST-API in eine saubere, typsichere Schnittstelle mit integriertem Rate Limiting, automatischen Wiederholungsversuchen und strukturierter Fehlerbehandlung — damit Sie sich auf das Mieten von GPUs konzentrieren können, nicht auf das HTTP-Handling.

---

Installation

pip install clore-ai

Anforderungen: Python 3.9+

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

---

Authentifizierung

Holen Sie Ihren API-Schlüssel aus dem 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 zur Authentifizierung, nicht Authorization: Bearer. Das SDK übernimmt dies automatisch.

---

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,       # Greift auf CLORE_API_KEY aus der Umgebungsvariable / Konfiguration 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               # Wiederholungsversuche bei Rate-Limit-/Netzwerkfehlern
)

Der Client unterstützt Kontextmanager für die automatische Bereinigung:

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

---

wallets()

Rufen Sie Ihre Wallet-Guthaben und Einzahlungsadressen ab.

wallets = client.wallets()

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

Rückgabe: List[Wallet]

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

---

marketplace()

Durchsuchen Sie den GPU-Marktplatz mit optionalen Filterkriterien auf der Client-Seite.

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

# Nach GPU-Modell und Maximalpreis 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 (Groß-/Kleinschreibung wird bei der Teilzeichenübereinstimmung ignoriert)
min_gpu_count	int | None	None	Mindestanzahl der GPUs
min_ram_gb	float | None	None	Mindestens RAM in GB
max_price_usd	float | None	None	Maximaler Preis pro Stunde in USD
available_only	bool	True	Nur Server zurückgeben, die zum Mieten verfügbar sind

Rückgabe: List[MarketplaceServer]

Jeder MarketplaceServer bietet praktische Eigenschaften für die häufigsten Felder sowie Zugriff auf die vollständigen verschachtelten Daten:

Eigenschaft	Typ	Beschreibung
id	int	Eindeutige Server-ID
gpu_model	str | None	Beschreibung der primären GPU (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)
Standort	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 Hardwarespezifikationen (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.)
vermietet	bool | None	Ob der Server derzeit vermietet ist
Zuverlässigkeit	float | None	Zuverlässigkeitswert des Servers
Bewertung	ServerRating | None	Serverbewertung (rating.avg, rating.cnt)

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

---

my_servers()

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

my_servers = client.my_servers()

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

Rückgabe: List[MyServer]

Eigenschaft	Typ	Beschreibung
id	int	Server-ID
name	str | None	Servername
gpu_model	str | None	Beschreibung der primären GPU
ram_gb	float | None	RAM in GB
status	str	Menschenlesbarer Status: "Online", "Offline", "Getrennt", oder "Nicht funktionsfähig"
verbunden	bool | None	Ob der Server verbunden ist
online	bool | None	Ob der Server online ist
Sichtbarkeit	str | None	"öffentlich" oder "privat"

---

server_config(server_name)

Rufen Sie die Konfiguration eines bestimmten Servers ab, den Sie hosten.

config = client.server_config("MyGPU")

print(f"Server: {config.name}")
print(f"GPU: {config.gpu_model}")
print(f"Mindestmietdauer: {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

Rückgabe: ServerConfig

Eigenschaft	Typ	Beschreibung
name	str | None	Servername
gpu_model	str | None	Beschreibung der primären GPU
mrl	int | None	Maximale Mietdauer in Stunden
on_demand_price	float | None	Erster verfügbarer On-Demand-USD-Preis
spot_price	float | None	Erster verfügbarer Spot-USD-Preis
specs	ServerSpecs | None	Vollständige Hardwarespezifikationen
verbunden	bool | None	Ob der Server verbunden ist
Sichtbarkeit	str | None	"öffentlich" oder "privat"

---

my_orders(include_completed)

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

# Nur aktive Bestellungen
orders = client.my_orders()

# Abgeschlossene Bestellungen einschließen
all_orders = client.my_orders(include_completed=True)

for order in orders:
    print(f"Bestellung {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 einschließen

Rückgabe: List[Order]

Feld	Typ	Beschreibung
id	int	Eindeutige Bestell-ID
server_id	int | None	Server-ID
Typ	str	"on-demand" oder "spot"
status	str | None	Bestellstatus
image	str | None	Docker-Image
Währung	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-Port-Zuordnungen

---

spot_marketplace(server_id)

Sehen Sie sich Spot-Marktangebote für einen bestimmten Server an.

spot = client.spot_marketplace(server_id=6)

if spot.offers:
    for offer in spot.offers:
        print(f"Bestellung {offer.order_id}: ${offer.price}/Tag (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

Rückgabe: SpotMarket

Feld	Typ	Beschreibung
Angebote	List[SpotOffer] | None	Liste der Spot-Angebote (order_id, price, server_id)
Server	SpotServerInfo | None	Serverinformationen (Mindestpreis, Sichtbarkeit, Online-Status)
currency_rates_in_usd	Dict[str, float] | None	Wechselkurse der Währungen 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"Bestellung 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	Server-ID zum Mieten
image	str	Ja	Docker-Image (z. B. "cloreai/ubuntu22.04-cuda12")
Typ	str	Ja	"on-demand" oder "spot"
Währung	str	Ja	Zahlungswährung (z. B. "bitcoin")
ssh_password	str	Nein	SSH-Passwort (alphanumerisch, max. 32 Zeichen)
ssh_key	str	Nein	Öffentlicher SSH-Schlüssel (max. 3072 Zeichen)
ports	dict	Nein	Port-Zuordnungen, 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 Containerstart ausgeführt wird
spot_price	float	Nur Spot	Preis pro Tag für Spot-Bestellungen
required_price	float	Nein	Einen bestimmten Preis festlegen (nur On-Demand)
autossh_entrypoint	str	Nein	Clore.ai-SSH-Entrypoint verwenden
gpu_count	int	Nein	Miete nur N GPUs auf Servern mit Teilvermietung (nur On-Demand); weglassen, um das gesamte Rig zu mieten
gpu_indices	list[int]	Nein	Exakte GPU-Slots aus partial_gpu_rental.free_indices; Länge muss gleich sein gpu_count; weglassen für automatische Auswahl

Rückgabe: Roh-API-Antwort ({"code": 0} bei Erfolg); rufe die erstellte Bestellung über my_orders()

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

---

cancel_order(order_id, issue)

Storniere eine aktive Bestellung oder ein Spot-Angebot. Melde optional ein Problem mit dem Server.

# Einfaches Stornieren
client.cancel_order(order_id=38)

# Stornieren mit Problembericht
client.cancel_order(
    order_id=38,
    issue="GPU #1 wurde zu heiß und drosselte"
)

Parameter:

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

Rückgabe: Dict[str, Any]

---

set_server_settings(...)

Aktualisiere die Einstellungen für einen Server, den du auf dem Marktplatz hostest.

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 vermietet werden kann
mrl	int	Nein	Maximale Mietdauer in Stunden
on_demand	float	Nein	On-Demand-Preis pro Tag
spot	float	Nein	Mindest-Spotpreis pro Tag

Rückgabe: Dict[str, Any]

---

set_spot_price(order_id, price)

Aktualisiere den Preis deines Spot-Marktplatzangebots.

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

Rückgabe: Dict[str, Any]

Hinweis: Du kannst Spotpreise nur alle 600 Sekunden und nur in begrenzter Schrittweite senken. Die API gibt code: 6 mit Details zurück, wenn du diese Limits überschreitest.

---

Asynchroner Client (AsyncCloreAI)

Das AsyncCloreAI Client bietet dieselben Methoden wie CloreAI an, aber alle geben Coroutines zurück. Verwende ihn, wenn du gleichzeitige API-Aufrufe brauchst oder in einer asynchronen Anwendung arbeitest.

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ühre mehrere API-Aufrufe parallel aus mit asyncio.gather:

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # Suche gleichzeitig nach mehreren GPU-Modellen
        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 Preis ${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-Guthaben abrufen
await marketplace(...)	Marktplatz durchsuchen
await my_servers()	Deine gehosteten Server auflisten
await server_config(name)	Serverkonfiguration abrufen
await my_orders(...)	Deine Bestellungen auflisten
await spot_marketplace(server_id)	Spot-Marktplatzangebote abrufen
await create_order(...)	Eine neue Bestellung erstellen
await cancel_order(...)	Eine Bestellung stornieren
await set_server_settings(...)	Servereinstellungen aktualisieren
await set_spot_price(...)	Spotpreis aktualisieren

---

Fehlerbehandlung

Das SDK stellt strukturierte Ausnahme-Klassen 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 — Rate-Limit überschritten
    InvalidInputError,  # Code 2 — ungültige Anfragedaten
    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. Prüfe deinen CLORE_API_KEY.")
except RateLimitError:
    print("Rate-Limit erreicht. Das SDK versucht es automatisch erneut, aber du hast die maximale Anzahl an Wiederholungen erreicht.")
except InvalidInputError as e:
    print(f"Fehlerhafte Anfrage: {e}")
except FieldError as e:
    # Fehler des Codes 6 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 Fehler Feld in der Antwort)

Alle Ausnahme-Klassen erben von CloreAPIError und enthalten:

• e.code — numerischer Fehlercode

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

---

Rate-Limitierung

Das SDK enthält einen integrierten Rate-Limiter, 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 und wiederholt es bis zu max_retries Mal (Standard: 3). Du musst kein time.sleep() zwischen Aufrufen hinzufügen.

So funktioniert es

1. Vor jeder Anfrage wartet der Rate-Limiter, bis das Mindestintervall abgelaufen ist.

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

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

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

Wiederholungsverhalten anpassen

client = CloreAI(
    max_retries=5,    # Mehr Wiederholungen für lang laufende Skripte
    timeout=60.0      # Längeres Timeout für langsame Verbindungen
)

---

Konfiguration

Konfigurationsdatei

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

{
  "api_key": "your_api_key_here"
}

Auflösungsreihenfolge

Das SDK ermittelt den API-Schlüssel in dieser Reihenfolge:

1. api_key an den Konstruktor übergebenes Argument

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 — Nutze Clore.ai von deinem Terminal aus

• REST-API — Roh-API-Dokumentation für benutzerdefinierte Integrationen

• On-Demand vs. Spot — Verstehe Preismodelle

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