● Dokumentation

Integrationen

Binde Carpe Diem in die Tools ein, die du bereits nutzt – den MCP-Server für KI-Assistenten, die OpenAI- und Anthropic-kompatible API für Code, Coding-Agents und Chat-Apps.

Carpe Diem erreicht deine Tools auf zwei Wegen:

  • Der MCP-Server (carpe-diem-mcp) gibt einem KI-Assistenten – Claude Code, Claude Desktop, Cursor, Codex, VS Code, Zed… – rund dreißig Carpe-Tools: mit jedem Modell chatten, Bilder, Videos, Sprache und Musik generieren, im Web suchen, Preise vergleichen, dein Guthaben prüfen. Der Assistent entscheidet, wann er sie aufruft; du behältst die Kontrolle darüber, was er ausgeben darf.
  • Die API ist OpenAI- und Anthropic-kompatibel. Jedes SDK, jeder Coding-Agent und jede Chat-App, bei denen du die Basis-URL ändern kannst, kann Carpe-Modelle direkt nutzen, ohne etwas zu installieren.

Für beides brauchst du einen API-Key (oder eine aufgeladene Wallet, für x402): Erstelle einen in API → Keys und lade dann in API → Balance Credits auf. Keys beginnen mit cdm_.

Wähle deinen Weg

Du willst…NutzeAbschnitt
Deinen KI-Assistenten Bilder, Videos, Audio generieren oder andere Modelle aufrufen lassenMCP-ServerMCP-Server
Einen Coding-Agent (Claude Code, OpenCode, Aider, Cline…) mit Carpe-Modellen betreibenAPI, als Modell-Provider des AgentsCoding-Agents
Modelle aus deinem eigenen Code aufrufenAPI, über das OpenAI- oder Anthropic-SDKSDKs
Einem Team eine private Chat-App bereitstellenAPI, hinter Open WebUI oder LibreChatChat-Apps & Automatisierung
Einen autonomen Agent pro Anfrage zahlen lassen, ohne Kontox402 (USDC auf Base)Pro Anfrage bezahlen
Carpe in ChatGPT oder claude.ai im Web nutzenNoch nicht verfügbarChatGPT und claude.ai

Zwei Zugänge: /v1 und /router

Jede der folgenden Integrationen nutzt eine von zwei Basis-URLs. Sie nehmen denselben Key und dieselben Request-Bodies an; sie unterscheiden sich darin, wer die Anfrage bedient.

…/api/operator/v1…/api/operator/router
Bedient vonCarpe allein – Venice, über Provider-Keys im TEE von CarpeDem günstigsten Markt für jede Anfrage: Carpe oder ein externer (Surplus, AntSeed, OpenRouter, Chutes, Venice, Engy)
VertraulichkeitImmer im TEEKann das TEE verlassen. Sende "privacy": true, um auf TEE-Märkten zu bleiben, "privacy": "private", um auf Märkten zu bleiben, die nichts speichern
PreisDer Preis von CarpeDer Preis des gewinnenden Markts, plus eine Routing-Gebühr nur bei externen Märkten
PfadeOpenAI-Chat und -Embeddings; Medien im Venice-Stil (/v1/image/generate, /v1/video/queue)Überall im OpenAI-Stil (/router/chat/completions, /router/images/generations)

Vollständige Basis-URLs: https://carpe-diem.xyz/api/operator/v1 und https://carpe-diem.xyz/api/operator/router. Jede Antwort sagt dir, wer sie bedient hat (X-Carpe-Route-Market) und was sie gekostet hat; siehe die API-Referenz.

MCP-Server

carpe-diem-mcp ist ein Open-Source-Server (MIT) für das Model Context Protocol. Er läuft auf deinem Rechner, wird von deinem Assistenten per npx gestartet und spricht mit deinem Key mit Carpe. Quellcode: github.com/Irdanwen/carpe-diem-mcp. Erfordert Node.js 20 oder neuer.

Was er deinem Assistenten gibt

GruppeToolsKosten
Katalogcarpe_list_models, carpe_model_details, carpe_pricing, carpe_quote, carpe_markets, carpe_statusKostenlos, kein Key nötig
Kontocarpe_balance, carpe_usage_history, carpe_usage_summary, carpe_key_usage, carpe_routing_summary, carpe_rate_limits, carpe_purchases, carpe_session_spend, carpe_x402_status, carpe_topup_link, carpe_revoke_this_keyKostenlos
Textcarpe_chat, carpe_embeddings, carpe_web_search, carpe_web_scrapeKostenpflichtig
Bildcarpe_image_generate, carpe_image_edit, carpe_image_multi_edit, carpe_image_upscale, carpe_image_statusKostenpflichtig (Status ist kostenlos)
Audiocarpe_tts, carpe_transcribe, carpe_voice_cloneKostenpflichtig (Klonen erfordert ausdrückliche Einwilligung)
Video & Musikcarpe_video_generate, carpe_video_status, carpe_music_generate, carpe_music_statusKostenpflichtig (Status ist kostenlos)

Außerdem stellt er drei Ressourcen bereit – carpe://models, carpe://pricing, carpe://markets – und drei fertige Prompts:

  • cheapest_model_for – wählt passende Modelle für eine Aufgabe aus, holt für jedes ein Angebot auf beiden Zugängen ein, führt das günstigste brauchbare aus und meldet Kosten und Markt.
  • cost_report – Guthaben, Ausgaben nach Modell und nach Tag, Ersparnis durch den Router und eine Warnung, wenn das Guthaben für weniger als eine Woche reicht.
  • private_inference – beantwortet eine vertrauliche Anfrage ausschließlich über /v1, mit einem Modell, das Venice privat ausführt, und bestätigt, dass sie im TEE lief.

Jedes Ergebnis nennt, was es gekostet hat und wer es bedient hat (Markt und ob es ein TEE war). Tools, die es auf beiden Zugängen gibt, nehmen ein Argument route an: "carpe" (/v1, Standard) oder "router" (/router).

Deine Ausgaben bleiben unter Kontrolle

Der Server bepreist jeden kostenpflichtigen Aufruf, bevor er ihn sendet – anhand kostenloser Angebote – und lehnt ihn lokal ab, ohne Carpe aufzurufen, wenn er Folgendes überschreiten würde:

  • CARPE_MAX_PER_CALL_USD – pro Aufruf (Standard 0.50), oder
  • den verbleibenden Rest von CARPE_MAX_SPEND_USD – pro Session (Standard 5).

carpe_session_spend zeigt den Zwischenstand. CARPE_READ_ONLY=1 entfernt jedes Tool, das Geld ausgeben oder etwas ändern kann. Wenn ein Key geleakt ist, deaktiviert ihn carpe_revoke_this_key (mit confirm: "REVOKE") sofort. carpe_topup_link liefert einen Checkout-Link, den ein Mensch öffnen muss: Der Assistent zahlt nie per Karte.

Kostenpflichtige Aufrufe werden nur dann wiederholt, wenn Carpe sie mit Sicherheit nicht ausgeführt hat (Rate Limit, Kapazität), sodass eine Wiederholung nie doppelt abgerechnet wird.

Installation

Wähle deinen Client. Jedes Snippet startet den Server mit npx; ersetze cdm_your_key durch deinen Key. Starte dann den Client neu (oder lade seine MCP-Server neu) und prüfe, ob alles funktioniert, indem du fragst: „Ruf carpe_status auf.“

# Available in every project (--scope user). Use --scope project to share it via .mcp.json.
claude mcp add carpe --scope user \
  --env CARPE_API_KEY=cdm_your_key \
  --env CARPE_MAX_SPEND_USD=5 \
  -- npx -y carpe-diem-mcp

Andere MCP-Clients – LM Studio (Program → Install → Edit mcp.json), Devin Desktop (ehemals Windsurf: ~/.config/devin/mcp_config.json), LibreChat – nehmen denselben mcpServers-Block wie Claude Desktop oben.

Verwendung

Sprich ganz normal mit deinem Assistenten; er wählt die Tools selbst. Ein paar Prompts, die gut funktionieren:

  • „Finde das günstigste Modell, das diese Datei gut zusammenfassen kann, und fasse sie dann zusammen.“ – nutzt carpe_quote auf beiden Zugängen, bevor Geld ausgegeben wird.
  • „Generiere ein 16:9-Hero-Bild eines Leuchtturms im Morgengrauen, flache Illustration, und speichere es in ./assets.“
  • „Lies diesen Absatz auf Französisch mit ruhiger Stimme vor und speichere die MP3.“
  • „Mach einen 5-Sekunden-Clip von einem Papierboot auf einem ruhigen See. Hol vorher ein Angebot ein.“ – Video und Musik sind Jobs; der Assistent fragt carpe_video_status ab und speichert die Datei.
  • „Such im Web nach dem neuesten Upgrade des Base-Netzwerks und fasse es mit Quellen zusammen.“
  • „Wie viel habe ich diese Woche ausgegeben, für welche Modelle, und wie viel hat mir der Router gespart?“ – oder führe den Prompt cost_report aus.
  • „Beantworte das privat, nur im TEE: …“ – oder führe den Prompt private_inference aus.

Vollständige Szenarien mit Code und Kosten: Anwendungsfälle.

Medieneingaben akzeptieren eine https://-URL, eine data:-URI oder einen lokalen Dateipfad. Bilder unter 4 MiB und Audio unter 8 MiB kommen inline zurück; setze CARPE_OUTPUT_DIR, um sie zusätzlich auf der Festplatte zu speichern. Videos und Musik werden immer in eine Datei gespeichert (ein fertiges Video bleibt etwa zehn Minuten bei Carpe).

Konfiguration

VariableStandardBedeutung
CARPE_API_KEY—Dein cdm_…-Key. Wird deinem Konto belastet.
CARPE_MAX_SPEND_USD5Session-Budget. 0 deaktiviert es.
CARPE_MAX_PER_CALL_USD0.50Limit pro Aufruf. 0 deaktiviert es.
CARPE_DEFAULT_ROUTEcarpecarpe (/v1, immer TEE) oder router (/router, günstigster Markt).
CARPE_DEFAULT_CHAT_MODELdeepseek-v4-flashModell, das genutzt wird, wenn der Assistent keins nennt.
CARPE_OUTPUT_DIR—Wohin Bilder, Audio, Video und Musik geschrieben werden.
CARPE_READ_ONLY01 behält nur die kostenlosen Tools.
CARPE_X402_PRIVATE_KEY / CARPE_X402_BUDGET_USD—Pro Anfrage aus einer Wallet statt mit einem Key bezahlen (siehe x402).
CARPE_HTTP_TIMEOUT_MS120000Timeout eines einzelnen Aufrufs an Carpe.

Ohne Key oder Wallet funktionieren die kostenlosen Tools (Katalog, Preise, Angebote, Märkte, Status) trotzdem.

Lokaler HTTP-Modus

Für einen Client, der nur HTTP spricht, startest du den Server selbst:

CARPE_API_KEY=cdm_your_key npx -y carpe-diem-mcp --http --port 3333
# → http://127.0.0.1:3333/mcp  (Streamable HTTP)

Er bindet an 127.0.0.1. Jede andere Adresse erfordert CARPE_MCP_AUTH_TOKEN (mindestens 16 Zeichen, gesendet als Authorization: Bearer), und Browser-Origins werden abgelehnt, sofern sie nicht in CARPE_MCP_ALLOWED_ORIGINS aufgeführt sind.

Fehlerbehebung

SymptomLösung
Der Server startet nicht, oder npx wird nicht gefundenInstalliere Node.js 20+ und starte den Client aus einer Shell neu, in der node --version funktioniert. Wenn der Client unter Windows npx nicht starten kann, nutze "command": "cmd", "args": ["/c", "npx", "-y", "carpe-diem-mcp"].
NO_PAYMENT_METHODWeder CARPE_API_KEY noch eine x402-Wallet ist beim Server angekommen. Prüfe den env-Block und starte den Client neu.
SPEND_LIMIT_PER_CALL / SPEND_LIMIT_SESSIONDie Ausgabensperre hat den Aufruf abgelehnt, bevor er gesendet wurde. Erhöhe das Limit oder starte eine neue Session.
402 PAYMENT_REQUIREDDein Guthaben deckt die Anfrage nicht: Lade in API → Balance Credits auf oder bitte den Assistenten um carpe_topup_link.
API_KEY_REQUIREDKonto-Tools brauchen einen Key; im x402-Modus sind sie nicht verfügbar.
GEO_RESTRICTED (HTTP 451)Carpe ist in deiner Region nicht verfügbar.
Der Key wird beim Start abgelehntKeys sehen aus wie cdm_ gefolgt von hexadezimalen Zeichen; kopiere ihn erneut aus API → Keys.

ChatGPT und claude.ai

ChatGPT sowie Claude im Web und auf Mobilgeräten akzeptieren nur Remote-MCP-Server – eine öffentliche HTTPS-URL mit Anmeldung per OAuth. Der Carpe-MCP-Server läuft auf deinem Rechner und lässt sich dort daher noch nicht hinzufügen. Ein gehosteter Carpe-MCP-Server mit Anmeldung ist geplant; diese Seite wird es vermerken, sobald er live ist.

Bis dahin:

  • Claude – nutze Claude Desktop oder Claude Code, die den Server lokal ausführen (Installation).
  • OpenAI – Codex (CLI, IDE-Erweiterung, Desktop-App) führt ihn lokal aus (Installation).

Coding-Agents

Betreibe deinen Coding-Agent mit Carpe-Modellen. Der Agent schickt seine Anfragen mit deinem Key an Carpe statt an seinen üblichen Provider. Wähle ein Modell mit Tool Calling (capabilities.supportsFunctionCalling in /v1/models); die Seite Models zeigt Live-Preise.

Gute Ausgangspunkte: claude-sonnet-5-5 und claude-haiku-5-5 (Anthropic), kimi-k2-7-code, qwen3-coder-480b-a35b-instruct-turbo, deepseek-v4-pro.

Claude Code

Claude Code spricht das Anthropic-Format; richte es auf /v1/messages von Carpe aus:

export ANTHROPIC_BASE_URL=https://carpe-diem.xyz/api/operator
export ANTHROPIC_AUTH_TOKEN=cdm_your_key          # sent as Authorization: Bearer
export ANTHROPIC_MODEL=claude-sonnet-5-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5   # background tasks
claude
  • ANTHROPIC_AUTH_TOKEN wird als Authorization: Bearer gesendet, wie jeder andere Carpe-Aufruf. (ANTHROPIC_API_KEY, gesendet als x-api-key, wird auf /v1/messages ebenfalls akzeptiert.)
  • Anfragen laufen über /v1, durch das TEE von Carpe. Claude-Modelle sind im Katalog als anonymized gelistet, nicht als private: Wähle für vertraulichen Code ein private-Modell.
  • Carpe hat kein /v1/messages/count_tokens; Claude Code schätzt die Token-Anzahl dann selbst.
  • Meldet Claude Code einen Fehler zu Beta-Headern, füge export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 hinzu.

OpenCode

Füge Carpe in opencode.json als OpenAI-kompatiblen Provider hinzu und wähle dann mit /models ein Modell:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "carpe": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Carpe Diem",
      "options": {
        "baseURL": "https://carpe-diem.xyz/api/operator/v1",
        "apiKey": "{env:CARPE_API_KEY}"
      },
      "models": {
        "kimi-k2-7-code": { "name": "Kimi K2.7 Code", "limit": { "context": 256000, "output": 65536 } },
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5", "limit": { "context": 1000000, "output": 128000 } }
      }
    }
  }
}

Nutze @ai-sdk/openai-compatible, nicht @ai-sdk/openai: Letzteres ruft /v1/responses auf, das Carpe nicht bedient. Für den besten Preis bei jeder Anfrage nimm https://carpe-diem.xyz/api/operator/router als baseURL.

Aider

export OPENAI_API_BASE=https://carpe-diem.xyz/api/operator/v1
export OPENAI_API_KEY=cdm_your_key
aider --model openai/kimi-k2-7-code

Cline

In den Einstellungen von Cline: API Provider → OpenAI Compatible, Base URL https://carpe-diem.xyz/api/operator/v1, dein Key als API Key und eine Modell-ID aus dem Katalog (zum Beispiel kimi-k2-7-code).

Continue

# config.yaml
models:
  - name: Carpe — Kimi K2.7 Code
    provider: openai
    model: kimi-k2-7-code
    apiBase: https://carpe-diem.xyz/api/operator/v1
    apiKey: ${{ secrets.CARPE_API_KEY }}
    useResponsesApi: false

Zed

{
  "language_models": {
    "openai_compatible": {
      "carpe": {
        "api_url": "https://carpe-diem.xyz/api/operator/v1",
        "available_models": [
          { "name": "kimi-k2-7-code", "display_name": "Kimi K2.7 Code (Carpe)", "max_tokens": 256000 }
        ]
      }
    }
  }
}

Zed liest den Key aus der Umgebungsvariable CARPE_API_KEY (die Provider-ID in Großbuchstaben plus _API_KEY) oder fragt im Agent-Panel danach.

VS Code (Copilot)

Copilot Chat kann einen eigenen Endpoint nutzen: Chat → Manage Language Models → Custom Endpoint, oder in chatLanguageModels.json:

[
  {
    "name": "Carpe Diem",
    "vendor": "customendpoint",
    "apiKey": "${input:carpeKey}",
    "apiType": "chat-completions",
    "models": [
      {
        "id": "kimi-k2-7-code",
        "name": "Kimi K2.7 Code (Carpe)",
        "url": "https://carpe-diem.xyz/api/operator/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 256000,
        "maxOutputTokens": 65536
      }
    ]
  }
]

Die Copilot-Richtlinie deiner Organisation kann eigene Modelle deaktivieren.

Goose und llm

// ~/.config/goose/custom_providers/carpe.json — the key comes from $CARPE_API_KEY
{
  "name": "carpe",
  "engine": "openai",
  "display_name": "Carpe Diem",
  "api_key_env": "CARPE_API_KEY",
  "base_url": "https://carpe-diem.xyz/api/operator/v1/chat/completions",
  "models": [{ "name": "kimi-k2-7-code", "context_limit": 256000 }],
  "supports_streaming": true,
  "requires_auth": true
}

Nicht als Modell-Provider unterstützt

  • Codex CLI spricht nur die Responses API von OpenAI (/v1/responses), die Carpe nicht bedient. Nutze Codex stattdessen mit dem MCP-Server.
  • Gemini CLI spricht nur mit Gemini-Endpoints. Nutze es mit dem MCP-Server.
  • Cursor erlaubt keine eigene Basis-URL für seine eigenen Modelle. Nutze es mit dem MCP-Server.

SDKs

Jedes OpenAI- oder Anthropic-SDK funktioniert: Basis-URL und Key ändern, Code beibehalten.

from openai import OpenAI
 
client = OpenAI(
    base_url="https://carpe-diem.xyz/api/operator/v1",   # or …/router for the best price
    api_key="cdm_your_key",
)
r = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(r.choices[0].message.content)

Was wie bei OpenAI funktioniert: Streaming (stream: true, SSE), Tools und tool_choice, response_format (JSON-Schema), Bilder in Nachrichten (Vision-Modelle), Embeddings (/v1/embeddings). Bilder, Audio, Video und Musik haben eigene Endpoints: siehe die API-Referenz. Aufrufe laufen von Server zu Server – eine Browserseite auf einer anderen Website kann die API nicht direkt aufrufen (CORS).

Chat-Apps & Automatisierung

Open WebUI

Admin settings → Connections → OpenAI → Add connection: URL https://carpe-diem.xyz/api/operator/v1 (oder /router), dein Key. Verify connection listet die Modelle auf. Oder mit Umgebungsvariablen:

OPENAI_API_BASE_URL=https://carpe-diem.xyz/api/operator/v1
OPENAI_API_KEY=cdm_your_key

Open WebUI verbindet sich nur über HTTP mit MCP-Servern. Um ihm die Carpe-Tools zu geben, betreibe den lokalen HTTP-Modus dort, wo Open WebUI ihn erreicht (hinter seinem Auth-Token), oder den Proxy mcpo von Open WebUI.

LibreChat

# librechat.yaml
endpoints:
  custom:
    - name: "Carpe Diem"
      apiKey: "${CARPE_API_KEY}"        # or "user_provided": each user brings a key
      baseURL: "https://carpe-diem.xyz/api/operator/v1"
      models:
        default: ["deepseek-v4-flash", "claude-sonnet-5-5"]
        fetch: true
mcpServers:
  carpe:
    type: stdio
    command: npx
    args: ["-y", "carpe-diem-mcp"]
    env:
      CARPE_API_KEY: "${CARPE_API_KEY}"
      CARPE_MAX_SPEND_USD: "5"

n8n

Lege ein OpenAI-Credential an, setze Base URL auf https://carpe-diem.xyz/api/operator/v1 und füge deinen Key ein. Der Node OpenAI Chat Model listet dann die Carpe-Modelle auf; lass Use Responses API ausgeschaltet. (Das OpenAI-Modul von Make hat keine Einstellung für die Basis-URL: Nutze dessen HTTP-Modul mit demselben Endpoint.)

Pro Anfrage bezahlen, ohne Konto (x402)

Ein autonomer Agent kann jede Anfrage aus seiner eigenen Wallet bezahlen – USDC auf Base, kein Key, keine Registrierung – mit dem Protokoll x402.

  • Mit dem MCP-Server: Hinterlege eine Wallet statt eines Keys. Der Server signiert ein einziges USDC-Permit, dessen Wert dein Budget ist: Carpe kann insgesamt nie mehr als diesen Betrag einziehen.

    "env": {
      "CARPE_X402_PRIVATE_KEY": "0x…",
      "CARPE_X402_BUDGET_USD": "2",
      "CARPE_MAX_PER_CALL_USD": "0.25"
    }

    Nutze eine dedizierte Wallet, die nur so viel enthält, wie du auszugeben bereit bist. In diesem Modus wird der Chat nicht gestreamt, Konto-Tools sind nicht verfügbar und geklonte Stimmen können nicht genutzt werden.

  • Aus deinem eigenen Code: POST /v1/x402/… ohne Zahlung liefert eine 402 mit den Zahlungsoptionen; signiere und sende erneut mit einem X-PAYMENT-Header. Den Ablauf, die beiden Schemes (carpe-session, exact) und die Fehlercodes findest du in der API-Referenz.

Für KI-Agents, die das hier lesen

Eine Klartext-Zusammenfassung von Carpe für Sprachmodelle findest du unter /llms.txt, die vollständige englische Dokumentation in einer Datei unter /llms-full.txt. Der Modellkatalog (/v1/models), die Preise (/pricing), die Router-Märkte (/router/markets) und Angebote (POST /router/quote) sind öffentlich und kostenlos.

Aktualisiert 2026-11-06