# 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-searxng-kein-key) | – | 0 | unbegrenzt | Search | — (läuft self-hosted) | | [DuckDuckGo](#0a-duckduckgo-kein-key) | – | 0 | rate-limited | Search | — | | [Brave Search](#1-brave-search) | `BRAVE_API_KEY` | $5/1k Queries | 2000/Monat | Search | ⭐ hoch | | [Tavily](#2-tavily) | `TAVILY_API_KEY` | Credit-Packs ab ~$0.008/Query | 1000 Credits/Monat | Search | ⭐ hoch | | [Exa](#3-exa) | `EXA_API_KEY` | $0.001–0.01/Query | $10 Guthaben bei Signup | Search (semantisch) | mittel | | [Serper](#4-serper) | `SERPER_API_KEY` | $0.001–0.003/Query | 2500 Queries einmalig | Search (Google SERP) | mittel | | [Jina Reader](#5-jina-reader) | `JINA_API_KEY` | $0.02/1M Tokens | 1M Tokens/Monat + unauthed | Extract | niedrig (läuft auch ohne Key) | | [Firecrawl](#6-firecrawl) | `FIRECRAWL_API_KEY` | $16 = 2000 Credits PAYG | 500 Credits Signup | Extract (JS-Render) | mittel | | [Perplexity Sonar](#7-perplexity-sonar) | `PERPLEXITY_API_KEY` | $5 Token-Credit + $5/1k Suchen | Keiner | Agent | ⭐ hoch | | [Google Gemini](#8-google-gemini) | `GOOGLE_GENAI_API_KEY` | Token + per-Grounding | großzügig (`gemini-2.0-flash`) | Agent + Async | ⭐ hoch | | [Anthropic Claude](#9-anthropic-claude) | `ANTHROPIC_API_KEY` | $10/1k web_search + Tokens | Variabel ($5 Guthaben bei Start) | Agent | hoch | | [OpenAI](#10-openai) | `OPENAI_API_KEY` | Token + per-Tool | Nein (ab ~2024) | Agent + Async | hoch | | [ScrapingBee](#11-scrapingbee-deferred) | `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):** ```bash # 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`](../../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): ```bash cd /Users/till/Documents/Code/managarten cp .env.secrets.example .env.secrets ``` Füge deine Keys in `.env.secrets` hinzu: ```env # === 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: ```bash 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: ```bash # 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: ```bash 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) |