OpenAI Python SDK: Carpe Diem base_url, cdm_-Key, echte Kosten

Dieses Tutorial dient dazu, Carpe Diem aus einem Python-Skript aufzurufen, mit dem OpenAI-SDK, das du schon nutzt: Chat, Modellliste, Modellwechsel, Streaming, Kostenauslese. Du installierst ein Paket, openai==3.36.0, in einem venv. Danach reichen zwei Felder: base_url auf https://carpe-diem.xyz/api/operator/v1 und ein cdm_-Key. Unser Lauf vom 22. Oktober 2026 bekam pong von llama-3.3-70b für 524 micro-USDC; derselbe Client listete 392 Modelle.

Illustration erzeugt mit seedream-v5-lite auf Carpe Diem.

Was du brauchst

Nichts außer Python, einem venv, dem festgeschriebenen OpenAI-SDK und einem Key Carpe Diem. Keine CLI Carpe Diem, kein eigenes SDK.

• Ein Carpe Diem Konto mit Credits oder einem Prepaid-Konto und einen cdm_-Key (API Keys-Tab im Käufer-Dashboard).
• Python 3.10 oder neuer (openai==3.36.0 verlangt das).
• pip in einem venv, um openai==3.36.0 festzuschreiben.

Am Ende kannst du: ein chat.completions.create senden (Schritt 3), IDs über models.list() listen (Schritt 3), x-carpe-cost-usdc-micro lesen (Schritt 4), von llama-3.3-70b auf claude-haiku-5-5 wechseln durch eine Zeichenkette (Schritt 5) und ein Haiku streamen (Schritt 6).

Schritt 1: einen cdm_-Key anlegen

Öffne Credits & keys, Tab API Keys. Keys beginnen mit cdm_ und werden nur einmal angezeigt. Wähle, wie der Key zahlt (Credits oder Prepaid), optional einen Namen, dann Create a key.

Credits: Nutzungsguthaben, 1 Credit = 0,01 $, keine Auszahlung. Prepaid: ein Konto, das du besitzt; das Protokoll zieht nur die Kosten jedes Aufrufs ein, eine Auszahlung bleibt möglich. Beide werden in USDC auf Base abgerechnet (Guide, §4.1). Ein dritter Zahlungsweg, x402, zahlt aus einer Wallet ohne cdm_-Key; dieses Tutorial behandelt diesen Weg nicht.

Kopiere ihn sofort in einen Secret-Manager: er wird nicht erneut angezeigt. In der Tutorial-Shell:

export OPENAI_API_KEY=cdm_your_key_here

Um ein Modell ohne Code zu testen, gibt es Create Hub.

Schritt 2: openai 3.36.0 installieren

python3 -m venv .venv
.venv/bin/pip install openai==3.36.0

Wir haben keine andere Version des Pakets getestet. Der OpenAI-Client sendet POST /chat/completions unter base_url. Für Carpe Diem muss base_url also bereits /v1 enthalten:

https://carpe-diem.xyz/api/operator/v1

Nicht https://carpe-diem.xyz/api/operator: das ist die URL des Anthropic-Adapters, ein anderes Protokoll. Der SDK-Guide sagt es so am Seitenanfang, direkt über dem OpenAI-Python-Beispiel.

Schritt 3: die erste Nachricht senden

Datei hello.py (der Client wird dort neu erzeugt, wie in jedem Ausschnitt):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://carpe-diem.xyz/api/operator/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

response = client.chat.completions.create(
    model="llama-3.3-70b",
    messages=[{"role": "user", "content": "Reply with the exact word: pong"}],
    max_tokens=16,
)

print(response.choices[0].message.content)
print("model:", response.model)
print("usage:", response.usage)

.venv/bin/python hello.py

Erhaltene Ausgabe:

pong
model: llama-3.3-70b
usage: CompletionUsage(completion_tokens=2, prompt_tokens=1675, total_tokens=1677, …)

Zwei Tokens in der Ausgabe, aber 1675 in der Eingabe für einen Satz aus sechs Wörtern. Bei unseren zwei Aufrufen an llama-3.3-70b mit diesem Prompt wurden 1675, dann 1695 Eingabe-Tokens abgerechnet (2714 bei Haiku). Die Herkunft dieser Präambel ist nicht dokumentiert. max_tokens=16 begrenzt nur die Ausgabe.

Um zu prüfen, dass eine Id existiert, bevor du den Rest schreibst:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://carpe-diem.xyz/api/operator/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

models = client.models.list()
ids = sorted(m.id for m in models.data)
print("count:", len(ids))
print("has llama-3.3-70b:", "llama-3.3-70b" in ids)
print("has claude-haiku-5-5:", "claude-haiku-5-5" in ids)

Ausgabe: 392 Ids, beide True. models.list() ruft GET /v1/models mit demselben Key auf: ein zweiter Client ist nicht nötig.

Schritt 4: die Kosten des Aufrufs lesen

Der JSON-Body des SDK enthält den Preis nicht. Carpe Diem legt ihn in die HTTP-Header, in micro-USDC (1 USDC = 1 000 000 micro-USDC), ohne Streaming. Das steht im SDK-Guide, in der Tabelle der X-Carpe-*-Header. with_raw_response legt sie offen; raw.parse() gibt das übliche Objekt zurück.

Datei cost.py:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://carpe-diem.xyz/api/operator/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

raw = client.chat.completions.with_raw_response.create(
    model="llama-3.3-70b",
    messages=[{"role": "user", "content": "Reply with the exact word: pong"}],
    max_tokens=16,
)

headers = raw.headers
print("x-carpe-cost-usdc-micro:", headers.get("x-carpe-cost-usdc-micro"))
print("x-carpe-input-tokens:", headers.get("x-carpe-input-tokens"))
print("x-carpe-output-tokens:", headers.get("x-carpe-output-tokens"))
print("x-carpe-available-credits:", headers.get("x-carpe-available-credits"))
print("x-carpe-cached-tokens:", headers.get("x-carpe-cached-tokens"))

response = raw.parse()
print("text:", response.choices[0].message.content)
print("usage:", response.usage)

Bei diesem Aufruf ausgelesene Header:

• x-carpe-cost-usdc-micro: 524
• x-carpe-input-tokens: 1675
• x-carpe-output-tokens: 2
• x-carpe-available-credits: dein Restguthaben, in Credits
• x-carpe-cached-tokens: nicht vorhanden (None im SDK)

524 micro-USDC. Zum Tarif 0,311 $ / 1,24 $ pro Million Tokens (31,1 / 124 cr/M auf /models, 1 Credit = 0,01 $), 1675 × 0,311 $ / M + 2 × 1,24 $ / M = 523 micro-USDC. 523 berechnet, 524 abgebucht: der Betrag scheint auf den nächsten micro-USDC aufgerundet.

Schritt 5: das Modell per Zeichenkette wechseln

Gleicher Client, andere Id. Der öffentliche Katalog zeigt die Preise in Credits pro Million (1 Credit = 0,01 $): llama-3.3-70b mit 31,1 / 124 cr/M, claude-haiku-5-5 mit 4,5 / 22,2 cr/M.

Datei switch_model.py:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://carpe-diem.xyz/api/operator/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

for model in ("llama-3.3-70b", "claude-haiku-5-5"):
    raw = client.chat.completions.with_raw_response.create(
        model=model,
        messages=[{"role": "user", "content": "Reply with the exact word: pong"}],
        max_tokens=16,
    )
    text = raw.parse().choices[0].message.content
    print(model)
    print("  text:", text)
    print("  cost-usdc-micro:", raw.headers.get("x-carpe-cost-usdc-micro"))
    print("  in:", raw.headers.get("x-carpe-input-tokens"), "out:", raw.headers.get("x-carpe-output-tokens"))

Beide antworteten pong. Bei diesem zweiten Durchlauf kostete llama-3.3-70b 530 micro-USDC für 1695 + 2 Tokens, in derselben Größenordnung wie die 524 / 1675 aus Schritt 4. Bei claude-haiku-5-5 wurden 14 micro-USDC abgebucht, mit 2714 + 4 Tokens in den Headern. Zum Katalogtarif 4,5 / 22,2 cr/M ergäben diese Tokens etwa 123 micro-USDC: die Abweichung ist nicht erklärt (wir haben x-carpe-cached-tokens bei diesem Aufruf nicht gelesen). Maßgeblich ist der Header, nicht die Handrechnung.

Ids kopierst du von /models. llama-3.3-70b-typo wurde nicht zu llama-3.3-70b umgeschrieben: füge die Id von der Karte ein.

Schritt 6: Streaming einschalten

Behalte den Test chunk.choices: der SDK-Guide nutzt ihn, und ein Chunk ohne choices würde bei chunk.choices[0] abstürzen.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://carpe-diem.xyz/api/operator/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

stream = client.chat.completions.create(
    model="llama-3.3-70b",
    messages=[{"role": "user", "content": "Write a haiku about the sea."}],
    max_tokens=64,
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()

Empfangener Text, Token für Token:

Crashing waves ascend
Foam kisses the sandy shore
Ocean's gentle song

Beim Streaming wird X-Carpe-Cost-Usdc-Micro nicht gesendet (SDK-Doku). Um die Kosten festzuhalten, bleib beim nicht gestreamten Aufruf.

Wenn es nicht klappt

401 AUTH_REQUIRED. Mit OPENAI_API_KEY=cdm_invalid warf das SDK openai.AuthenticationError: Error code: 401 - {'error': 'Unauthorized', 'code': 'AUTH_REQUIRED'}. Der Key ist unvollständig, schlecht kopiert, oder die Umgebungsvariable ist in dieser Shell nicht exportiert. Ein export in einem Terminal erreicht keine IDE, die vom Dock gestartet wurde.

400 MODEL_ERROR. model="llama-3.3-70b-typo" lieferte: This model is no longer available upstream. Try a newer version of the same model. Die Meldung spricht von einer Upstream-Abkündigung; hier war es nur ein Tippfehler. Prüfe die Id auf /models oder über client.models.list().

URL ohne /v1. Siehe Schritt 2.

Weiter gehen

Dieselbe base_url mit /v1 durch /router ersetzt schickt den Aufruf an den Bestpreis-Router: gleicher Key, gleicher Body. Wir haben hello.py in diesem Lauf nicht auf /router wiederholt.

Für einen Agenten im Terminal statt eines Skripts haben wir OpenCode schon angeschlossen: Kimi K3 und Claude Fable in OpenCode.

Um ein Modell ohne hello.py auszuprobieren, öffne Create Hub, dann komm zurück und füge die Id in model= ein.

Versuch vom 22 Oktober 2026 mit openai==3.36.0 und einem Test-Key mit Guthaben. Die Ausschnitte sind genau die, die hier bei uns gelaufen sind.