Cas d'usage

Chaque recette présente l'objectif, la voie (serveur MCP, API ou les deux), du code qui fonctionne, ce qu'elle a coûté lors de notre essai et son niveau de confidentialité. Configuration à faire une fois :

export CARPE_API_KEY=cdm_your_key   # API → Keys
pip install openai requests          # Python recipes

Les coûts ci-dessous ont été mesurés le 2026-11-06 et varient avec le prix dynamique. Avant de lancer un traitement volumineux, demandez un devis — c'est gratuit : POST /router/quote pour le texte, POST /v1/video/quote pour la vidéo, /pricing pour tout le reste.

Le modèle le moins cher pour une tâche

Objectif : obtenir une réponse suffisamment bonne au prix le plus bas, sans tester les modèles à la main.

Avec le serveur MCP, lancez le prompt cheapest_model_for, ou demandez simplement : « Trouve le modèle le moins cher capable de bien traduire ceci en allemand, puis fais-le. » L'assistant présélectionne des modèles, obtient un devis pour chacun sur /v1 et /router avec carpe_quote (gratuit), exécute le moins cher qui convient et vous indique ce qu'il a coûté et qui l'a servi.

Avec l'API, demandez d'abord un devis, puis envoyez la requête au router — il choisit lui-même le marché le moins cher :

import os, requests
from openai import OpenAI
 
BASE = "https://carpe-diem.xyz/api/operator"
 
# 1. Free quote: what would 500 tokens in / 300 out cost, on each market?
q = requests.post(f"{BASE}/router/quote", json={"model": "deepseek-v4-flash", "input_tokens": 500, "max_tokens": 300}).json()
print("best:", q["best"]["market"], q["best"]["costUsd"], "USD")
 
# 2. Run it through the router: the cheapest market serves it.
client = OpenAI(base_url=f"{BASE}/router", api_key=os.environ["CARPE_API_KEY"])
raw = client.chat.completions.with_raw_response.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Translate into German: The meeting moved to Thursday."}],
)
print(raw.parse().choices[0].message.content)
print("served by", raw.headers.get("x-carpe-route-market"), "for", raw.headers.get("x-carpe-route-cost-usdc"), "USDC")

Coût : 0,00003 $ pour cette traduction (servie par OpenRouter lors de notre essai). Confidentialité : le router peut la servir hors du TEE ; ajoutez extra_body={"privacy": True} pour rester sur des marchés TEE.

Analyse confidentielle dans le TEE

Objectif : résumer un contrat, un courrier médical ou du code interne sans que personne ne le conserve.

Utilisez la surface /v1 (toujours via le TEE de Carpe) et un modèle listé privacy: "private" dans /v1/models — Venice exécute ces modèles sans conserver prompts ni réponses.

Avec le serveur MCP, lancez le prompt private_inference, ou demandez : « De façon privée, uniquement dans le TEE, résume ./contract.txt en cinq points. » Le résultat indique tee: true.

import os, requests
from openai import OpenAI
 
BASE = "https://carpe-diem.xyz/api/operator"
models = requests.get(f"{BASE}/v1/models").json()["data"]
private = [m["id"] for m in models if m.get("carpe_diem_type") == "text" and m.get("privacy") == "private"]
print(len(private), "private text models, e.g.", private[:3])
 
client = OpenAI(base_url=f"{BASE}/v1", api_key=os.environ["CARPE_API_KEY"])
document = "This agreement is made between Alpha SA and Beta GmbH. Term: 24 months. Either party may terminate with 90 days' notice."
r = client.chat.completions.create(
    model="deepseek-v4-flash",                       # listed "private"
    messages=[
        {"role": "system", "content": "You summarise legal documents in five short bullet points."},
        {"role": "user", "content": document},
    ],
)
print(r.choices[0].message.content)

Coût : 0,0001 $ pour ce résumé ; comptez environ 0,0005 $ pour une page entière. Confidentialité : TEE de bout en bout côté Carpe, et un modèle qui ne conserve rien. Les modèles e2ee-* vont plus loin (chiffrement de bout en bout jusqu'à l'enclave du modèle lui-même). Vérifiez l'attestation sur /attestation et sur la page Privacy.

Un agent de code moins cher

Objectif : garder votre agent de code, payer moins par tâche.

Pointez l'agent vers Carpe et choisissez un modèle selon son prix et ses compétences : les modèles Claude pour le travail le plus difficile, kimi-k2-7-code, qwen3-coder-480b-a35b-instruct-turbo ou deepseek-v4-pro pour l'essentiel. Configuration pas à pas pour Claude Code, OpenCode, Aider, Cline, Continue, Zed et VS Code : Agents de code.

Donnez au même agent le serveur MCP et il pourra aussi produire les ressources dont votre projet a besoin — icônes, maquettes, voix off — sans quitter le terminal.

Coût : vous payez au token, au prix de Carpe, affiché en direct sur la page Models ; l'espace API montre ce que chaque clé a dépensé. Confidentialité : préférez un modèle private pour du code propriétaire ; les modèles Claude sont anonymized.

Images : générer, modifier, agrandir

Objectif : une image d'en-tête pour une page, puis une variante, puis une version au format impression.

Avec le serveur MCP : « Génère une illustration flat 16:9 d'un renard roux dans une forêt, puis rends le renard bleu, puis agrandis-la ×2. Enregistre tout dans ./assets. » — carpe_image_generate, carpe_image_edit, carpe_image_upscale.

import base64, os, time, requests
 
BASE = "https://carpe-diem.xyz/api/operator/v1"
H = {"Authorization": f"Bearer {os.environ['CARPE_API_KEY']}"}
 
def queued(path, body):
    """Queue a slow image job, poll until the image comes back (binary)."""
    qid = requests.post(f"{BASE}/{path}/queue", headers=H, json=body).json()["queue_id"]
    while True:
        r = requests.post(f"{BASE}/{path}/retrieve", headers=H, json={"queue_id": qid})
        if r.headers.get("content-type", "").startswith("image/"):
            return r.content
        if r.json().get("status") != "pending":
            raise RuntimeError(r.text)
        time.sleep(2)
 
# 1. Generate (synchronous for fast models) → base64 WebP
gen = requests.post(f"{BASE}/image/generate", headers=H, json={
    "model": "z-image-turbo", "prompt": "a red fox in a forest, flat illustration",
}).json()
fox = gen["images"][0]
open("fox.webp", "wb").write(base64.b64decode(fox))
 
# 2. Edit (queued: edit models take longer) — the source goes in as a data URI
blue = queued("image/edit", {
    "model": "qwen-image-2-1-turbo-edit", "prompt": "make the fox blue",
    "image": f"data:image/webp;base64,{fox}",
})
open("fox-blue.png", "wb").write(blue)
 
# 3. Upscale ×2: raw base64, no data: prefix
up = requests.post(f"{BASE}/image/upscale", headers=H, json={
    "model": "upscaler", "image": base64.b64encode(blue).decode(), "scale": 2,
}, timeout=180)
up.raise_for_status()
open("fox-blue-2x.png", "wb").write(up.content)
print("cost of the last step:", up.headers.get("x-carpe-cost-usdc-micro"), "µUSDC")

Coût : environ 0,005 $ pour générer, 0,011 $ pour modifier et 0,011 $ pour agrandir ×2. Confidentialité : sur /v1, via le TEE. Un modèle trop lent pour une requête unique répond 409 MODEL_REQUIRES_ASYNC avec l'endpoint à utiliser : la fonction queued() ci-dessus fonctionne pour image/generate, image/edit et image/multi-edit (référence de la file d'attente).

Un court clip vidéo

Objectif : un clip de 5 secondes pour une publication ou une landing page.

Avec le serveur MCP : « Fais un clip 16:9 de 5 secondes d'un bateau en papier sur un lac calme. Donne-moi d'abord un devis. » — carpe_video_generate établit le devis et met en file d'attente, puis carpe_video_status attend et enregistre le MP4.

import os, time, requests
 
BASE = "https://carpe-diem.xyz/api/operator"
H = {"Authorization": f"Bearer {os.environ['CARPE_API_KEY']}"}
job = {"model": "grok-imagine-1-5-lite-text-to-video", "prompt": "a paper boat on a calm lake, morning light",
       "duration": "5s", "aspect_ratio": "16:9"}
 
print("quote:", requests.post(f"{BASE}/v1/video/quote", headers=H, json=job).json()["cost_usdc"], "USD")
qid = requests.post(f"{BASE}/v1/video/queue", headers=H, json=job).json()["queue_id"]
 
while True:
    r = requests.post(f"{BASE}/v1/video/retrieve", headers=H, json={"queue_id": qid}).json()
    if r["status"] == "completed":
        url = r.get("video_url") or r.get("url")
        video = requests.get(url if url.startswith("http") else BASE + url)   # kept ~10 minutes
        open("boat.mp4", "wb").write(video.content)
        break
    if r["status"] == "failed":
        raise RuntimeError(r)
    time.sleep(5)

Coût : 0,097 $ pour ces 5 secondes, exactement le devis (selon les modèles, de quelques centimes à plusieurs dollars : demandez toujours un devis d'abord). Durées, formats d'image et résolutions varient selon le modèle : lisez-les dans constraints de /v1/models. Confidentialité : sur /v1, via le TEE. Téléchargez le fichier dès qu'il est prêt.

Voix : lire à voix haute, transcrire

Objectif : transformer un paragraphe en MP3, et un fichier audio en texte.

Avec le serveur MCP : « Lis ce paragraphe à voix haute en français et enregistre le MP3. Puis transcris-le pour vérifier. » — carpe_tts, carpe_transcribe.

import os, requests
 
BASE = "https://carpe-diem.xyz/api/operator/v1"
H = {"Authorization": f"Bearer {os.environ['CARPE_API_KEY']}"}
 
speech = requests.post(f"{BASE}/audio/speech", headers=H, json={
    "model": "tts-kokoro", "input": "Bonjour ! Ceci est un test de synthèse vocale.", "response_format": "mp3",
})
speech.raise_for_status()
open("hello.mp3", "wb").write(speech.content)
 
text = requests.post(f"{BASE}/audio/transcriptions", headers=H,
    files={"file": ("hello.mp3", speech.content, "audio/mpeg")},
    data={"model": "openai/whisper-large-v3"}).json()
print(text["text"])

Coût : 0,0003 $ pour cette phrase, les deux étapes comprises (la synthèse vocale est facturée au caractère, la transcription à la minute d'audio). Les voix dépendent du modèle : omettez voice pour la voix par défaut, ou choisissez-en une parmi les voices du modèle dans /v1/models. Confidentialité : sur /v1, via le TEE. Cloner une voix (carpe_voice_clone, POST /v1/audio/voices) exige le consentement de la personne enregistrée, et la voix est conservée 7 jours par le fournisseur.

Une musique pour une vidéo

Objectif : une piste de fond à la durée de votre clip.

Avec le serveur MCP : « Compose un morceau de piano lo-fi calme de 60 secondes, instrumental, et enregistre-le. » — carpe_music_generate, carpe_music_status.

import os, time, requests
 
BASE = "https://carpe-diem.xyz/api/operator/v1"
H = {"Authorization": f"Bearer {os.environ['CARPE_API_KEY']}"}
 
qid = requests.post(f"{BASE}/audio/music/queue", headers=H, json={
    "model": "ace-step-15", "prompt": "calm lo-fi piano loop, warm, slow", "duration_seconds": 60,
}).json()["queue_id"]
 
while True:
    r = requests.post(f"{BASE}/audio/music/retrieve", headers=H, json={"queue_id": qid, "model": "ace-step-15"})
    if r.headers.get("content-type", "").startswith("audio/"):
        open("track.flac", "wb").write(r.content)  # ace-step-15 delivers FLAC; a /v1 track can be fetched once
        break
    if r.json().get("status") == "failed":
        raise RuntimeError(r.text)
    time.sleep(5)

Coût : environ 0,016 $ pour 60 secondes avec ace-step-15. Chaque modèle de musique accepte des durées, des options et des formats de fichier différents (duration_options, supports_lyrics, default_format…) : lisez d'abord ses constraints dans /v1/models. Confidentialité : sur /v1, via le TEE.

Répondre à des questions sur vos documents (RAG)

Objectif : un petit bot de questions-réponses sur vos propres notes.

import os, math
from openai import OpenAI
 
client = OpenAI(base_url="https://carpe-diem.xyz/api/operator/v1", api_key=os.environ["CARPE_API_KEY"])
docs = [
    "Refunds are possible within 30 days of purchase.",
    "Support answers in English and French, Monday to Friday.",
    "Enterprise plans include a dedicated account manager.",
]
 
def embed(texts):
    r = client.embeddings.create(model="text-embedding-bge-m3", input=texts)
    return [d.embedding for d in r.data]
 
def cos(a, b):
    return sum(x * y for x, y in zip(a, b)) / (math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b)))
 
index = embed(docs)
question = "Can I get my money back after three weeks?"
q = embed([question])[0]
best = max(range(len(docs)), key=lambda i: cos(q, index[i]))
 
answer = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": f"Answer only from this context: {docs[best]}"},
        {"role": "user", "content": question},
    ],
)
print(answer.choices[0].message.content)

Coût : 0,00015 $ pour cette question, embeddings compris ; vectoriser une seule fois un grand ensemble de documents coûte une fraction de centime par centaine de pages. Confidentialité : les deux appels passent par /v1, via le TEE ; text-embedding-bge-m3 et deepseek-v4-flash sont des modèles private. La même chose fonctionne avec LangChain ou LlamaIndex.

Recherche web avec sources

Objectif : une réponse courte et sourcée sur un sujet récent.

Avec le serveur MCP : « Cherche sur le web la dernière mise à jour du réseau Base et résume-la avec les sources. » — carpe_web_search, carpe_web_scrape, puis carpe_chat.

import os, requests
from openai import OpenAI
 
BASE = "https://carpe-diem.xyz/api/operator/v1"
H = {"Authorization": f"Bearer {os.environ['CARPE_API_KEY']}"}
 
results = requests.post(f"{BASE}/augment/search", headers=H, json={"query": "Base network latest upgrade"}).json()["results"][:5]
context = "\n\n".join(f"[{i + 1}] {r['title']} ({r['url']})\n{r['content']}" for i, r in enumerate(results))
 
client = OpenAI(base_url=BASE, api_key=os.environ["CARPE_API_KEY"])
r = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Answer from the sources below and cite them as [n].\n\n" + context},
        {"role": "user", "content": "What changed in the latest Base network upgrade?"},
    ],
)
print(r.choices[0].message.content)

Pour lire une page entière, POST /v1/augment/scrape avec {"url": "https://…"} renvoie son contenu. Coût : 0,0054 $ par recherche ou extraction de page, plus la réponse (0,0056 $ au total pour celle-ci). Confidentialité : sur /v1, via le TEE ; la recherche elle-même part sur le web.

Extraction structurée à grande échelle

Objectif : transformer des milliers d'e-mails, de factures ou de tickets en JSON propre, à moindre coût et sans double facturation lors des nouvelles tentatives.

import json, os, uuid
from openai import OpenAI
 
client = OpenAI(base_url="https://carpe-diem.xyz/api/operator/router", api_key=os.environ["CARPE_API_KEY"], max_retries=3)
schema = {
    "name": "invoice",
    "strict": True,
    "schema": {
        "type": "object",
        "properties": {
            "vendor": {"type": "string"},
            "total": {"type": "number"},
            "currency": {"type": "string"},
            "due_date": {"type": "string"},
        },
        "required": ["vendor", "total", "currency", "due_date"],
        "additionalProperties": False,
    },
}
 
def extract(text: str) -> dict:
    r = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=[{"role": "user", "content": f"Extract the invoice fields:\n\n{text}"}],
        response_format={"type": "json_schema", "json_schema": schema},
        # Same key on a retry → the router replays the first answer instead of billing twice.
        extra_headers={"Idempotency-Key": str(uuid.uuid5(uuid.NAMESPACE_URL, text))},
    )
    return json.loads(r.choices[0].message.content)
 
print(extract("ACME Corp — Invoice 1042 — Total due: 1,250.00 EUR by 2026-12-01."))

Coût : 0,00004 $ pour cette facture sur le router. Confidentialité : le router peut la servir hors du TEE : ajoutez extra_body={"privacy": "private"} pour des marchés qui ne conservent rien (la relecture idempotente est alors désactivée), ou utilisez /v1. Restez sous les limites de débit : consultez les vôtres avec GET /v1/rate_limits.

Garder les dépenses sous contrôle

Objectif : savoir où va l'argent, et s'assurer qu'un agent ne peut pas s'emballer.

• Par clé : créez une clé par application ou par agent dans API → Keys, pour séparer les dépenses de chacun (GET /buyer/api-keys/usage).
• Dans le serveur MCP : CARPE_MAX_PER_CALL_USD et CARPE_MAX_SPEND_USD refusent un appel avant son envoi ; CARPE_READ_ONLY=1 pour un assistant qui doit seulement consulter.
• Rapports : lancez le prompt cost_report, ou demandez « Combien ai-je dépensé cette semaine, sur quels modèles, et combien le router m'a-t-il fait économiser ? ». Avec l'API :

curl -s https://carpe-diem.xyz/api/operator/v1/credits -H "Authorization: Bearer $CARPE_API_KEY"
curl -s "https://carpe-diem.xyz/api/operator/buyer/usage/summary?days=7" -H "Authorization: Bearer $CARPE_API_KEY"
curl -s "https://carpe-diem.xyz/api/operator/buyer/routing/summary" -H "Authorization: Bearer $CARPE_API_KEY"

• Chaque réponse indique son coût (X-Carpe-Cost-Usdc-Micro sur /v1, X-Carpe-Route-Cost-Usdc sur /router) et votre solde restant (X-Carpe-Available-Credits), pour qu'une application puisse s'arrêter d'elle-même.
• Si une clé fuite : révoquez-la dans API → Keys, ou laissez la clé se révoquer elle-même : POST /v1/keys/self/revoke (l'outil MCP carpe_revoke_this_key).

Un agent qui paie lui-même (x402)

Objectif : un agent autonome avec son propre wallet et un budget strict — sans compte, sans clé à gérer.

Approvisionnez un wallet dédié avec un peu d'USDC sur Base, puis donnez sa clé privée au serveur MCP avec un budget :

{
  "mcpServers": {
    "carpe": {
      "command": "npx",
      "args": ["-y", "carpe-diem-mcp"],
      "env": {
        "CARPE_X402_PRIVATE_KEY": "0xYOUR_AGENT_WALLET_KEY",
        "CARPE_X402_BUDGET_USD": "2",
        "CARPE_MAX_PER_CALL_USD": "0.25"
      }
    }
  }
}

Le serveur signe un seul permit USDC dont la valeur est le budget : Carpe ne peut jamais prélever plus de 2 $ au total, quoi que fasse l'agent, et la dépense est mémorisée d'un redémarrage à l'autre. carpe_x402_status affiche le wallet, son USDC et ce qu'il reste. Pour le faire depuis votre propre code, voir x402 dans la référence de l'API.

Coût : ce que l'agent consomme, aux mêmes prix. Confidentialité : ni compte ni e-mail : le wallet est l'identité.

Une application de chat privée pour une équipe

Objectif : une application de type ChatGPT pour votre équipe, sur les modèles de votre choix, sans que chacun ait besoin d'un compte où que ce soit.

Déployez Open WebUI ou LibreChat avec une seule clé Carpe (ou une clé par utilisateur avec l'option user_provided de LibreChat). Pointez-la vers https://carpe-diem.xyz/api/operator/v1 pour que chaque conversation passe par le TEE, et ne laissez visibles que les modèles private pour le travail confidentiel. Donnez aussi le serveur MCP à l'application (LibreChat) et chacun pourra demander des images, de la voix et des recherches web depuis le même chat.

Coût : au message, au prix de Carpe ; suivez-le par clé dans API → Usage. Confidentialité : sur /v1, via le TEE ; avec les modèles private, le fournisseur du modèle ne conserve rien.