Starte mit einem Prompt.

Schnellstart#

npx -y scaledthought@0.3 init --region us

npx -y scaledthought@0.3 billing topup --amount-usd 20

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Authentifizierung#

Sende deinen Key als Bearer-Token. Keys gelten für eine Region und können ein eigenes Budget haben. Die Basis-URL ist der Host deiner Region, in .env als ST_BASE_URL gespeichert: https://api.us.scaledthought.com/v1 (Kanadas https://api.ca.scaledthought.com/v1 kommt demnächst).

Authorization: Bearer $ST_API_KEY
Content-Type: application/json

Chat Completions#

POST /v1/chat/completions akzeptiert das Anfrageformat von OpenAI. Nutze eine Modell-ID aus npx -y scaledthought@0.3 models --live oder von /pricing.

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Streaming#

Setze stream: true, um Server-Sent Events im Delta-Format von OpenAI zu empfangen.

stream = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Write a haiku about open weights"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Tool Calling#

Übergib tools im OpenAI-Format. Modelle, die Tool Calling unterstützen, liefern standardmäßige tool_calls. Unterstützung und Qualität unterscheiden sich je nach Modell, also prüf die Modellkarte, bevor du dich darauf verlässt.

resp = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Weather in Toronto?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
)
print(resp.choices[0].message.tool_calls)

Strukturierte Ausgabe#

Nutze response_format mit einem JSON-Schema. Bei Modellen, die das unterstützen, wird die Ausgabe schon beim Decoding auf das Schema beschränkt. Prüf das Ergebnis, bevor du dich darauf verlässt.

resp = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": invoice_text}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "invoice", "schema": {
            "type": "object",
            "properties": {"vendor": {"type": "string"}, "total": {"type": "number"}},
            "required": ["vendor", "total"],
        }},
    },
)

Responses API & Codex#

POST $ST_BASE_URL/responses spricht die OpenAI Responses API, sodass Clients, die nur dieses Protokoll nutzen, etwa Codex, ScaledThought als Modellanbieter verwenden können. Der Endpunkt nimmt input (einen String oder Nachrichten, function_call- und function_call_output-Elemente), instructions, Function-Tools und Custom-Tools (Freiform), tool_choice, max_output_tokens, text.format für JSON-Ausgabe und stream: true (Responses-Events, die mit response.completed oder response.incomplete samt usage enden, oder mit response.failed samt error).

Er ist zustandslos. Wir speichern keine Antworten, also sende in jeder Runde die ganze Unterhaltung in input (Codex macht das) und lass previous_response_id weg, das 400 invalid_request liefert; store ist immer false. Gehostete Tools wie die Dateisuche liefern 400; ein Websuche-Tool wird ignoriert. Anfragen ohne max_output_tokens werden auf das begrenzt, was der Kontext des Modells nach deinem Prompt übrig lässt, höchstens 32.768 Tokens.

Die Abrechnung ist dieselbe wie bei Chat Completions: pro Token, nach der Nutzung, die der Modellserver meldet, bezahlt aus deinem Guthaben.

# ~/.codex/config.toml
model = "deepseek-v4-1-flash"  # or a model id from `npx -y scaledthought@0.3 models --live`
model_provider = "scaledthought"

[model_providers.scaledthought]
name = "ScaledThought"
base_url = "https://api.us.scaledthought.com/v1"  # your ST_BASE_URL
env_key = "ST_API_KEY"
wire_api = "responses"
model_catalog_url = "https://api.us.scaledthought.com/v1/codex/models"  # same host (and region) as base_url

Codex liest ST_API_KEY aus der Umgebung, also lade ./.env zuerst in die Shell. wire_api = "responses" ist Pflicht: ScaledThought bedient Codex über die Responses API.

model_catalog_url teilt Codex die Kontextfenster der Modelle mit, die in deiner Region live sind, damit es lange Sitzungen rechtzeitig komprimiert, und gibt ihm sein Bearbeitungs-Tool apply_patch. Der Katalog wird bei jeder Anfrage aus den Live-Modellen erzeugt; Codex sendet dabei deinen Key mit, also halte ihn auf demselben Host wie base_url (dem deiner Region).

Modelle & Benchmarks#

GET /v1/models listet die Modell-IDs, die in deiner Region live sind, im Format von OpenAI. Diese Liste ist maßgeblich dafür, was du aufrufen kannst. GET /v1/models/{id} liefert für ein Modell Preise, Kontextlänge, Veröffentlichungsdatum, Benchmark-Werte und Live-Status, sodass ein Agent wählen kann, ohne dass ein Mensch eine Webseite liest. Zum Suchen und Filtern nutze npx -y scaledthought@0.3 models --live oder das MCP-Tool models_search. Für Menschen listet /pricing jedes Modell, das in den USA live ist, mit seinem Preis, aus derselben API.

curl "$ST_BASE_URL/models"
curl "$ST_BASE_URL/models/deepseek-v4-1-flash"

Regionen & Speicherung#

Jeder Key ist an seine Region gebunden. Die Region USA ist jetzt offen; Kanada (ca) kommt demnächst, und bis zur Eröffnung antwortet seine API nicht. Anfragen werden nur in diesem Land bedient und protokolliert, und Konto- und Nutzungsdaten werden nur dort gespeichert. Kartenzahlungen für jede Region verarbeitet Stripe in den USA. Prompts und Completions werden nach der Rückgabe der Antwort nicht gespeichert und nie zum Training verwendet. Batch- und Fine-Tuning-Dateien werden nach 30 Tagen gelöscht, oder früher mit DELETE /v1/files/{id}. Jede Antwort trägt x-st-region und x-st-data-retention: none. Siehe Sicherheit (oder /security.json) und die Datenschutzerklärung (Englisch).

Keys & Budgets#

Agenten können eingeschränkte Keys mit festen täglichen Ausgabelimits anlegen. Ist ein Budget erreicht, liefern Aufrufe 402, statt mehr auszugeben. Ein widerrufener Key funktioniert nach etwa 30 Sekunden nicht mehr.

npx -y scaledthought@0.3 keys create --name support-bot --budget-usd 40

Scopes sind inference, read, keys, billing. Ein Key kann einem neuen Key nur Scopes geben, die er selbst hat (sonst 403 scope_not_allowed). Ablauf: Sende expires_in (etwa "30d") oder expires_at, bis zu 365 Tage; danach bekommt der Key 401 key_expired. Ein Key lebt nie länger als der Key, der ihn erstellt hat.

Sub-Agent-Keys: Mit child: true speichert der neue Key den aufrufenden Key als seinen Parent. Sein Tagesbudget passt in das, was dem Parent heute noch bleibt, seine Rate-Limits und sein Ablauf liegen nicht über denen des Parents, und er kann nur seine eigenen Sub-Keys verwalten. Wird ein Key widerrufen, werden alle Keys darunter mit widerrufen.

Rotation: POST /v1/keys/{id}/rotate erzeugt einen Ersatz mit demselben Namen, denselben Scopes, demselben Budget und denselben Limits, einmalig zurückgegeben. Der alte Key funktioniert noch für grace (Standard 24h, "0" bis "7d"). Selbstwiderruf: DELETE /v1/keys/self widerruft den aufrufenden Key und seine Sub-Agent-Keys, ohne dass ein Scope nötig ist, sodass ein Agent, der ein Leck vermutet, sofort handeln kann.

npx -y scaledthought@0.3 keys create --name sub-agent --child --scopes inference --budget-usd 2 --expires-in 12h
npx -y scaledthought@0.3 keys rotate key_… --grace 24h
npx -y scaledthought@0.3 keys revoke-self

Mehr dazu, wie Keys und Daten geschützt sind: Sicherheit.

Guthaben & Freigabe#

Die Nutzung wird aus Prepaid-Guthaben bezahlt, $20 bis $2,000 pro Aufladung, höchstens $2,000 pro 24 Stunden und 2 offene Freigabelinks gleichzeitig. Der Agent fordert eine Aufladung an (standardmäßig $20) und bekommt eine approval_url zurück: eine Aufladeseite, auf der die Person, für die er arbeitet, den Betrag bestätigt oder ändert, Auto-Reload einschalten kann und per Karte zahlt. Das Guthaben kommt an, sobald die Zahlung bestätigt ist, und wir schicken eine Quittung per E-Mail. Ohne diese Freigabe wird nie etwas belastet. Guthaben verfällt nicht. Ist es aufgebraucht, liefern Anfragen 402 insufficient_credits mit dem Saldo und dem benötigten Betrag.

npx -y scaledthought@0.3 billing topup --amount-usd 20

Auto-Reload ist optional und empfohlen: Fällt der Saldo unter einen Schwellenwert (standardmäßig $5), lädt die gespeicherte Karte einen festen Betrag nach (standardmäßig $20), damit der Agent nie stehen bleibt. Die Person, für die der Agent arbeitet, schaltet es auf der Aufladeseite einer beliebigen Aufladung ein, oder ohne etwas zu kaufen über einen Einrichtungslink für Auto-Reload (billing auto-reload setup), wo sie eine Karte hinterlegt. Aufladungen sind auf $2.000 pro 24 Stunden begrenzt. Einschalten oder ein Limit erhöhen braucht eine neue Freigabe; Ausschalten oder Senken nicht. Wird eine Nachladung abgelehnt, schaltet sich Auto-Reload selbst ab, und der nächste 402 sagt dem Agenten, dass er einen neuen Link holen soll. billing status zeigt den Saldo und offene Aufladungen; billing transactions listet jeden Kauf, jede Nachladung und jede Belastung.

npx -y scaledthought@0.3 billing topup --amount-usd 20 --auto-reload-below 5 --auto-reload-amount 20
npx -y scaledthought@0.3 billing auto-reload setup --below 5 --amount 20   # no purchase: they save a card
npx -y scaledthought@0.3 billing auto-reload off

Hinweise & Webhooks#

Antworten können x-st-notice mit kommagetrennten Codes tragen: low_balance (ein Konto, dessen Saldo unter $5 liegt). Ein Agent, der einen solchen Code sieht, sollte der Person, für die er arbeitet, sagen, was freizugeben ist. GET /v1/account, MCP account_status, status und doctor zeigen dieselben Codes mit dem Text, den der Agent weitergeben soll.

Webhooks liefern dieselben Signale per Push: balance.low, key.expiring und budget.exhausted. Endpunkte müssen öffentliche https-URLs auf Port 443 sein. Jeder POST trägt x-st-signature: t=…,v1=…, ein HMAC-SHA256 über <t>.<raw body> mit dem Signing-Secret des Endpunkts als Schlüssel, das einmal angezeigt wird, wenn du ihn hinzufügst. Zustellungen gehen an deine URL, wo auch immer sie gehostet ist, auch außerhalb der Region deines Kontos, und enthalten nur id, type, created_at, region, account_id und data: IDs, ganzzahlige Beträge in Mikrodollar, Anzahlen von Tagen und Zeitstempel, nie Prompts, Namen oder E-Mail-Adressen. data pro Event: balance.low {balance_micros, threshold_micros}, key.expiring {key_id, expires_at}, budget.exhausted {scope, key_id, budget_micros, spent_today_micros, resets_at}. Fehlgeschlagene Zustellungen werden mit Backoff etwa zwei Tage lang wiederholt.

npx -y scaledthought@0.3 webhooks add https://hooks.example.com/st --events balance.low,budget.exhausted

Optionale Request-Header: x-st-app benennt deine App in den Nutzungsdaten (nicht veröffentlicht), und x-st-session hält eine Unterhaltung auf derselben Replica, damit ihr gecachtes Präfix wiederverwendet wird (nur im Arbeitsspeicher, nie gespeichert). In Kanada weichen Anfragen nie in ein anderes Land aus: Sind alle Replicas eines Modells ausgelastet, wartet eine Anfrage kurz und bekommt dann 429 capacity_exhausted mit Retry-After.

Batch-Inferenz#

Lade eine JSONL-Datei mit Anfragen hoch und bekomm die Ergebnisse für 50 % des normalen Preises. Batches laufen in einem Zeitfenster von 24 Stunden und sind in der Regel darin fertig, zugesichert ist das aber nicht. Die Endpunkte für Files und Batches folgen denen von OpenAI, also funktioniert client.batches.create. Jede Zeile wird vorab geprüft, sodass eine fehlerhafte Datei innerhalb von Sekunden scheitert.

batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
    input_file_id=batch_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
# later
batch = client.batches.retrieve(batch.id)
results = client.files.content(batch.output_file_id).text

Embeddings#

POST /v1/embeddings mit einem Embedding-Modell (finde eines mit models --live --modality embedding). Der Input kann ein String oder ein Array von Strings sein.

vecs = client.embeddings.create(model="<embedding-model-id>", input=["open weights", "served hot"])

Fine-Tuning#

Trainiere einen LoRA-Adapter mit deinen eigenen Beispielen. Das Ergebnis ist eine private Modell-ID, die nur dein Konto aufrufen kann, bedient auf denselben Replicas wie das Basismodell und zum Token-Preis des Basismodells abgerechnet. Trainieren lassen sich nur Basismodelle, die auf unseren eigenen GPUs in deiner Region laufen, und Adapter lassen sich nicht herunterladen. Training wird pro 1M Trainings-Tokens abgerechnet (Dataset-Tokens × Epochen); die Job-Antwort enthält eine Schätzung, bevor irgendetwas läuft. Bezahlt aus Prepaid-Guthaben. Siehe Preise.

f = client.files.create(file=open("examples.jsonl", "rb"), purpose="fine-tune")
job = client.fine_tuning.jobs.create(model="<base-id>", training_file=f.id, suffix="triage")
# poll
job = client.fine_tuning.jobs.retrieve(job.id)
resp = client.chat.completions.create(model=job.fine_tuned_model, messages=[...])

MCP-Server#

Remote-MCP auf dem API-Host deiner Region: https://api.us.scaledthought.com/mcp (Kanadas https://api.ca.scaledthought.com/mcp kommt demnächst; Streamable HTTP, Spezifikation 2026-07-28). Authentifiziere dich mit deinem API-Key als Bearer-Token. Über MCP lassen sich keine Konten anlegen: Registriere dich zuerst mit npx -y scaledthought@0.3 init oder POST /v1/accounts, dann gibt npx -y scaledthought@0.3 mcp den genauen Befehl und die Konfiguration für deine Region aus. Der Agent bekommt diese Tools:

npx -y scaledthought@0.3 mcp

CLI#

Führ sie als npx -y scaledthought@0.3 <command> aus. Die Ausgabe ist JSON, wann immer stdout kein Terminal ist (oder mit --json), und Fehler sind eine JSON-Zeile auf stderr mit code, message und hint. Nichts fragt interaktiv nach. Keys kommen aus ST_API_KEY oder ./.env, nie aus Flags.

API-Referenz#

Rate-Limits#

Limits gelten pro Key. Über dem Limit liefern Aufrufe 429 rate_limit_exceeded mit einem Retry-After-Header in Sekunden. Bis zum ersten Guthabenkauf des Kontos können Keys ihre Limits senken, aber nicht erhöhen.

Fehler#

API-Fehler haben die Form {"error":{"message","type","code"}}. CLI-Fehler ergänzen einen hint und enden mit einem Exit-Code ungleich null.