managarten/services/mana-research/API_KEYS.md

Research-Provider API-Keys — Setup-Anleitung

Alle Provider, die in mana-research einen externen API-Key brauchen, wo du den Key bekommst, was er kostet und wohin er im Repo gehört.

Alle genannten Anbieter sind pay-per-use (keine Pflicht-Abos). Wo sich das nicht vermeiden lässt, ist es explizit genannt.

---

Überblick

Provider	Env-Var	Kosten	Free-Tier	Kategorie	Dringlich?
SearXNG	–	0	unbegrenzt	Search	— (läuft self-hosted)
DuckDuckGo	–	0	rate-limited	Search	—
Brave Search	BRAVE_API_KEY	$5/1k Queries	2000/Monat	Search	⭐ hoch
Tavily	TAVILY_API_KEY	Credit-Packs ab ~$0.008/Query	1000 Credits/Monat	Search	⭐ hoch
Exa	EXA_API_KEY	$0.001–0.01/Query	$10 Guthaben bei Signup	Search (semantisch)	mittel
Serper	SERPER_API_KEY	$0.001–0.003/Query	2500 Queries einmalig	Search (Google SERP)	mittel
Jina Reader	JINA_API_KEY	$0.02/1M Tokens	1M Tokens/Monat + unauthed	Extract	niedrig (läuft auch ohne Key)
Firecrawl	FIRECRAWL_API_KEY	$16 = 2000 Credits PAYG	500 Credits Signup	Extract (JS-Render)	mittel
Perplexity Sonar	PERPLEXITY_API_KEY	$5 Token-Credit + $5/1k Suchen	Keiner	Agent	⭐ hoch
Google Gemini	GOOGLE_GENAI_API_KEY	Token + per-Grounding	großzügig (gemini-2.0-flash)	Agent + Async	⭐ hoch
Anthropic Claude	ANTHROPIC_API_KEY	$10/1k web_search + Tokens	Variabel ($5 Guthaben bei Start)	Agent	hoch
OpenAI	OPENAI_API_KEY	Token + per-Tool	Nein (ab ~2024)	Agent + Async	hoch
ScrapingBee	SCRAPINGBEE_API_KEY	ab $49/Mo	1000 Credits Signup	Extract	❌ deferred (Abo-Pflicht)

Empfohlene Minimum-Auswahl für einen vollwertigen Research Lab Vergleich: Brave + Tavily + Exa + Perplexity + Google Gemini + OpenAI. Das gibt dir 2 unabhängige Search-Indizes, einen semantischen Index, und drei qualitativ unterschiedliche Agents. Typische Startkosten: $0 (Free-Tiers decken Evaluation ab).

---

0. SearXNG (kein Key)

Läuft bereits als Docker-Container auf localhost:8080 via docker-compose.yml. Du musst nichts tun. mana-search (port 3021) proxied dahin.

0a. DuckDuckGo (kein Key)

Die DuckDuckGo Instant-Answer-API braucht keinen Key. Sie ist rate-limited und liefert nur bei klaren Entities brauchbare Ergebnisse — gut als kostenloser Sanity-Check, nicht als Hauptanbieter.

---

1. Brave Search

Was ist das: Eigener Web-Index (nicht Google-Relay). Starke Privacy-Story, unabhängig, stabile Qualität.

Signup:

1. Gehe zu https://api.search.brave.com
2. „Get Started Free" → mit E-Mail registrieren
3. E-Mail verifizieren
4. Im Dashboard: Subscription wählen → „Data for Search" + „Free plan" (keine Kreditkarte nötig) ODER „Pro AI" Plan ($5/1k Queries, pay-per-use)
5. „API Keys" → „Generate API Key" → kopieren (Format BSA...)

Free Tier: 2000 Queries/Monat, 1 Query/Sekunde. Reicht für Testing. Kosten (paid): $5/1000 Queries, pay-as-you-go, keine monatliche Mindestgebühr.

Dokumentation: https://api.search.brave.com/app/documentation/web-search/get-started

Env-Var: BRAVE_API_KEY=BSA...

---

2. Tavily

Was ist das: LLM-agent-optimierte Suche. Liefert extrahierte Inhalte direkt mit (nicht nur Links).

Signup:

1. Gehe zu https://tavily.com
2. „Get Free API Key" → mit Google/GitHub oder E-Mail
3. Im Dashboard sofort sichtbar: der Key (Format tvly-...)
4. Für mehr als 1000 Credits/Monat: „Upgrade" → Credit Pack kaufen (persistent, läuft nicht ab, keine Abo-Verpflichtung)

Free Tier: 1000 Credits/Monat (entspricht 1000 Suchanfragen). Reicht für moderate Nutzung. Kosten (paid): Credit-Packs, ab $30 für 4000 Credits ($0.0075/Credit), läuft nicht ab.

Dokumentation: https://docs.tavily.com/docs/rest-api/api-reference

Env-Var: TAVILY_API_KEY=tvly-...

---

3. Exa

Was ist das: Neuronale/semantische Suche. Bestes Tool für „find similar to …" und akademische Paper.

Signup:

1. Gehe zu https://dashboard.exa.ai
2. Mit Google oder E-Mail einloggen
3. Du bekommst $10 Startguthaben (reicht für ~1000–10.000 Queries je nach Modus)
4. „API Keys" → „Create Key" → kopieren
5. Zahlung hinzufügen optional — erst nötig wenn Guthaben verbraucht

Kosten: neural ~$0.005/Query, keyword $0.001/Query, mit contents Aufpreis. Pay-per-use.

Dokumentation: https://docs.exa.ai

Env-Var: EXA_API_KEY=...

---

4. Serper

Was ist das: Google-SERP-Ergebnisse als JSON. Liefert People-Also-Ask, Knowledge Panels, Shopping-Boxen — 1:1 was Google anzeigt.

Signup:

1. Gehe zu https://serper.dev
2. „Sign Up" mit E-Mail oder Google
3. 2500 Gratis-Queries werden automatisch gutgeschrieben (einmalig, kein Monatsreset)
4. „API Key" im Dashboard kopieren
5. Paid: „Billing" → $50 einzahlen = 50k Queries, pay-as-you-go. Kein Abo-Zwang.

Kosten: $0.30–1 pro 1000 Queries je nach Plan. Pay-per-use ab $50.

Dokumentation: https://serper.dev/api-key

Env-Var: SERPER_API_KEY=...

---

5. Jina Reader

Was ist das: Inhaltsextraktion von jeder Webseite als sauberes Markdown. Läuft ohne Key mit moderaten Rate-Limits — Key ist optional aber hebt das Limit.

Signup (optional):

1. Gehe zu https://jina.ai
2. Oben rechts „API" → „Get API Key"
3. Mit E-Mail registrieren → Key wird direkt angezeigt (Format jina_...)
4. 1M Tokens/Monat kostenlos, danach $0.02/1M Tokens PAYG

Ohne Key: Funktioniert auch, nur mit niedrigerem Rate-Limit (~60 Requests/Min).

Dokumentation: https://jina.ai/reader

Env-Var: JINA_API_KEY=jina_... (optional, aber empfohlen)

---

6. Firecrawl

Was ist das: Playwright-basierter Scraper. Rendert JavaScript, liefert LLM-ready Markdown. Beste Option für Single-Page-Apps, Paywalls (Teaser), PDFs.

Signup (Cloud):

1. Gehe zu https://firecrawl.dev
2. „Get started" → GitHub/Google/E-Mail
3. 500 Credits gratis beim Signup
4. „API Keys" → „Create" → Key kopieren (Format fc-...)
5. Paid: Credit-Packs ab $16 für 2000 Credits, pay-per-use. Es gibt auch Abos ($99/Mo), aber du kannst bei PAYG bleiben.

Alternative (Self-Hosted):

# Firecrawl hat eine Open-Source-Version
git clone https://github.com/mendableai/firecrawl
cd firecrawl && docker compose up -d
# Dann in mana-research:
# FIRECRAWL_API_URL=http://localhost:3002  (im Provider-Code anpassen)
# FIRECRAWL_API_KEY=beliebig-nicht-leer

Kosten (Cloud): ~$0.008/Scrape (Standard), $0.015 (mit JS-Render).

Dokumentation: https://docs.firecrawl.dev

Env-Var: FIRECRAWL_API_KEY=fc-...

---

7. Perplexity Sonar

Was ist das: Der beste „Plug&Play"-Research-Agent am Markt. Vier Modelle: sonar (schnell), sonar-pro (balanced), sonar-reasoning (Chain-of-Thought), sonar-deep-research (umfangreich).

Signup:

1. Gehe zu https://www.perplexity.ai/settings/api
2. Einloggen (Google/Apple/E-Mail)
3. Kreditkarte hinterlegen — kein echter Free-Tier auf der API. Du kannst aber ein Mini-Guthaben einzahlen (ab $5) und nur das verbrauchen.
4. „Generate" → Key kopieren (Format pplx-...)

Kosten:

• sonar: $1/1M Input-Tokens, $1/1M Output-Tokens, $5/1000 Web-Suchen
• sonar-pro: $3/1M Input, $15/1M Output, $5/1000 Suchen
• sonar-reasoning: $1/1M Input, $5/1M Output, $5/1000 Suchen
• sonar-deep-research: teurer, mehrere Suchen pro Anfrage

Eine typische Anfrage kostet ~$0.01–0.10.

Dokumentation: https://docs.perplexity.ai

Env-Var: PERPLEXITY_API_KEY=pplx-...

---

8. Google Gemini

Was ist das: Gemini mit Google-Search-Grounding = Echte Google-Suche im LLM-Antwortprozess. Günstig, guter Free-Tier für Testing.

Signup:

1. Gehe zu https://aistudio.google.com/apikey
2. Mit Google-Konto einloggen
3. „Create API key" → Projekt auswählen/erstellen
4. Key kopieren (Format AIza...)
5. Free-Tier aktiv by default — rate-limited (~15 RPM für Flash-Modelle)
6. Für höhere Limits: In Google Cloud Console Billing aktivieren

Free Tier: gemini-2.0-flash, gemini-1.5-flash haben einen großzügigen kostenlosen Tier. Achtung: Wenn dein Google-Konto bereits Paid-API-Nutzung hatte, kann das Free-Tier ausgeschöpft sein — dann musst du entweder Billing aktivieren oder ein frisches Google-Projekt anlegen.

Kosten (Paid, wenn aktiviert):

• gemini-2.0-flash: $0.10/1M Input, $0.40/1M Output
• Grounding-Query: $35/1000 Suchen
• gemini-1.5-pro: teurer

Deep Research & Deep Research Max (derselbe Key): Seit 2026-04-21 deckt derselbe GOOGLE_GENAI_API_KEY auch die zwei neuen async Agents ab — gemini-deep-research ($1–3/Task, Standard) und gemini-deep-research-max ($3–7/Task, nächtliche Tiefenrecherche). Beide laufen über die Interactions API mit background=true und sind im Service über POST /v1/research/async { provider: "gemini-deep-research" | "gemini-deep-research-max" } erreichbar. Preview-Status — Rate-Limits niedrig, Modell-IDs enden auf -preview-04-2026. Details: docs/reports/gemini-deep-research.md.

Dokumentation: https://ai.google.dev/gemini-api/docs/api-key Deep-Research-Doku: https://ai.google.dev/gemini-api/docs/deep-research

Env-Var: GOOGLE_GENAI_API_KEY=AIza...

---

9. Anthropic Claude

Was ist das: Claude-API mit dem server-seitigen web_search_20250305-Tool. Claude kann bis zu 5 Websuchen pro Anfrage machen und liefert präzise Zitate.

Signup:

1. Gehe zu https://console.anthropic.com
2. Registrieren (E-Mail oder Google)
3. Billing einrichten (Kreditkarte) — es gibt kein dauerhaftes Free-Tier, manche neue Konten bekommen $5 Startguthaben
4. „API Keys" → „Create Key" → kopieren (Format sk-ant-...)

Kosten:

• claude-opus-4-7: $15/1M Input, $75/1M Output Tokens
• claude-sonnet-4-6: $3/1M Input, $15/1M Output
• claude-haiku-4-5: $0.80/1M Input, $4/1M Output
• web_search-Tool: $10 pro 1000 Suchen (zusätzlich zu Tokens)

Typische Research-Anfrage mit Opus + 3 Suchen: ~$0.10–0.30.

Modell-Wahl: Unser Provider nutzt claude-opus-4-7 als Default. Für Kostenersparnis kannst du im UI options.model: "claude-sonnet-4-6" setzen.

Dokumentation: https://docs.anthropic.com/en/api/getting-started

Env-Var: ANTHROPIC_API_KEY=sk-ant-...

---

10. OpenAI

Was ist das: OpenAI Responses API mit web_search_preview-Tool (sync) und o3-deep-research (async). Deckt zwei Provider ab: openai-responses + openai-deep-research.

Signup:

1. Gehe zu https://platform.openai.com/api-keys
2. Registrieren / einloggen
3. Billing einrichten (platform.openai.com/account/billing) — kein Free-Tier auf der API
4. Mindestens $5 Guthaben einzahlen
5. „Create new secret key" → kopieren (Format sk-proj-... oder sk-...)

Kosten:

• gpt-4o: $2.50/1M Input, $10/1M Output
• gpt-4.1: aktuellere Version, ähnlich bepreist
• web_search_preview-Tool: $25–30 pro 1000 Calls (zusätzlich zu Tokens)
• o3-deep-research: $10–20/1M Input (nutzt intern viele Suchen, kann $0.50–5 pro Task kosten)

Async-Hinweis: Der openai-deep-research-Provider startet Hintergrundjobs. Die laufen 5–30 Minuten. Das UI pollt /v1/research/async/:taskId. Denke an Quota: deine OpenAI-Org hat ggf. ein RPM- und TPM-Limit, das bei parallelen Jobs erreicht werden kann.

Dokumentation: https://platform.openai.com/docs/guides/tools-web-search

Env-Var: OPENAI_API_KEY=sk-proj-...

---

11. ScrapingBee (deferred)

ScrapingBee hat nur Abo-Pläne ab $49/Monat — passt nicht zur Pay-per-use-Regel dieses Projekts. Der Provider ist im Code-Stub angelegt aber nicht implementiert. Wenn du trotzdem ein Abo hast und es brauchst: Issue öffnen, ich implementiere die Extraction-Pipeline (Raw-HTML → Readability-Post-Process) nach.

---

Wohin mit den Keys?

Dev (lokal)

Kopiere .env.secrets.example nach .env.secrets (ist gitignored):

cd /Users/till/Documents/Code/mana-monorepo
cp .env.secrets.example .env.secrets

Füge deine Keys in .env.secrets hinzu:

# === Research-Provider Keys ===
BRAVE_API_KEY=BSA-dein-key-hier
TAVILY_API_KEY=tvly-dein-key-hier
EXA_API_KEY=dein-exa-key
SERPER_API_KEY=dein-serper-key
JINA_API_KEY=jina_dein-key-hier
FIRECRAWL_API_KEY=fc-dein-key-hier
PERPLEXITY_API_KEY=pplx-dein-key-hier
ANTHROPIC_API_KEY=sk-ant-dein-key-hier
OPENAI_API_KEY=sk-proj-dein-key-hier
GOOGLE_GENAI_API_KEY=AIza-dein-key-hier

Dann neu generieren und Service neustarten:

pnpm setup:env
# mana-research neu starten (existierende PID killen, dann:)
cd services/mana-research && MANA_SERVICE_KEY=dev-service-key bun run dev

Hinweis: Der manuelle MANA_SERVICE_KEY=dev-service-key ist temporär nötig wegen einem cross-service env-Mismatch. Wenn mana-credits neu mit dem neueren Service-Key gestartet wird (oder .env.development angepasst), entfällt das.

Produktion (Mac-Mini Docker)

Die Keys sind bereits im docker-compose.macmini.yml als ${BRAVE_API_KEY:-} etc. referenziert. Setze sie in der Docker-Compose-.env-Datei auf dem Mac-Mini oder als Docker-Secrets. Detail siehe docs/DEPLOYMENT.md und docs/MAC_MINI_SERVER.md.

BYO-Keys pro User (Frontend)

User können ihre eigenen Keys in /research-lab/keys hinterlegen — die landen in research.provider_configs pro userId. Diese Keys überschreiben den Server-Key für diesen User und umgehen mana-credits (kein Credit-Verbrauch, der User zahlt direkt beim Provider).

Aktuell plaintext in der DB. TODO: AES-GCM-256 via shared-crypto KEK — siehe storage/configs.ts:decryptKey().

---

Verifikation nach Setup

Nach pnpm setup:env und Service-Restart:

# 1. Welche Provider sind ready (haben Server-Key)?
curl -s http://localhost:3068/api/v1/providers/health | python3 -m json.tool

# Erwarten: Jeder Provider mit Key zeigt status=ready, ohne Key: status=needs-key

# 2. Echter Testcall (JWT via Login holen)
TOKEN=$(curl -s -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"tills95@gmail.com","password":"Aa-123456789"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])")

# Compare-Call mit allen Such-Providern:
curl -s -X POST http://localhost:3068/api/v1/search/compare \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"Claude Opus 4.7","providers":["brave","tavily","exa","serper","searxng"],"options":{"limit":3}}' \
  | python3 -m json.tool | head -80

# Agent-Call:
curl -s -X POST http://localhost:3068/api/v1/research/compare \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is Mana (the app at mana.how)?","providers":["perplexity-sonar","gemini-grounding","claude-web-search"]}' \
  | python3 -m json.tool | head -60

Kosten-Monitoring

Jede Compare-Anfrage reserviert Credits via mana-credits. Bei Fehler wird refundet. Check das Ledger:

docker exec mana-postgres psql -U mana -d mana_platform -c "
SELECT provider_id, COUNT(*), SUM(cost_credits) AS total_credits, AVG(latency_ms)::int AS avg_latency
FROM research.eval_results
WHERE success = true
GROUP BY provider_id
ORDER BY total_credits DESC;"

Troubleshooting

Fehler	Ursache	Fix
needs-key im Health-Check	Env-Var nicht gesetzt oder Service nicht neu gestartet	.env.secrets prüfen → pnpm setup:env → Service restart
credits.reserve failed: 401	MANA_SERVICE_KEY zwischen mana-research und mana-credits mismatch	mana-research mit MANA_SERVICE_KEY=dev-service-key starten
429 RESOURCE_EXHAUSTED (Gemini)	Free-Tier verbraucht oder Account ohne Billing	Neues Google-Projekt oder Billing aktivieren
Insufficient credits (402)	User-Balance in mana-credits zu niedrig	Credits gutschreiben (/api/v1/internal/credits/init + direkt DB-Update in Dev)
Provider "X" is not configured (501)	Provider requiresApiKey=true aber weder Server- noch BYO-Key	Key setzen (siehe oben)
Redis NOAUTH Authentication required	Redis hat Passwort, aber REDIS_URL ohne Credentials	REDIS_URL=redis://:password@localhost:6379 — Cache degradiert sonst graceful (nicht fatal)