Authentifizierung & Basics

Base URL

https://api.openhippo.io/v1

Authentifizierung

Jeder Request trägt den API-Key als Bearer-Token:

Authorization: Bearer hk_live_0123456789abcdef0123456789abcdef

Keys haben das Format hk_live_ gefolgt von 32 Hex-Zeichen.
Die Console zeigt einen Key nur einmal beim Anlegen. Verloren? In der Console neu generieren.
Ein fehlender oder ungültiger Key gibt 401:

{"error":{"message":"No API key provided","type":"invalid_api_key","param":"api_key","code":"401"}}

Keys verwaltest du in der Console: anlegen, bearbeiten (Name, Budget), neu generieren, widerrufen. Siehe Console & Team-Administration.

Keys gehören auf den Server

Ein API-Key gibt Zugriff auf dein Guthaben. Lege ihn nie in Frontend-Code, Apps oder öffentliche Repositories. Setze für jeden Key ein Budget.

Endpunkte

Zwei Schnittstellen-Familien auf derselben Base URL:

OpenAI-kompatibel: /v1/chat/completions und die weiteren Pfade unten.
Anthropic-kompatibel: /v1/messages (inklusive Streaming) und /v1/messages/count_tokens.

Methode	Pfad	Zweck
`POST`	`/v1/chat/completions`	Chat (OpenAI-Format), Streaming, Tool Calling, Bilder
`POST`	`/v1/completions`	Text-Completion (OpenAI-Format)
`POST`	`/v1/messages`	Chat (Anthropic-Format), Streaming
`POST`	`/v1/messages/count_tokens`	Tokens zählen (Anthropic-Format)
`POST`	`/v1/responses`	Responses API, nur Anlegen
`POST`	`/v1/embeddings`	Embeddings
`POST`	`/v1/rerank`, `/v2/rerank`	Reranking
`POST`	`/v1/audio/transcriptions`	Transkription (Datei-Upload)
`POST`	`/v1/audio/speech`	Sprachausgabe (Text to Speech)
`GET`	`/v1/models`, `/v1/models/{id}`	Modelle auflisten
`GET`	`/v1/usage`	Verbrauch des aufrufenden Keys

Die Pfade für Chat Completions, Completions, Embeddings, Rerank und Models funktionieren auch ohne /v1 (z. B. /chat/completions). Alle anderen Pfade antworten mit 404.

Beispiele für weitere Endpunkte

Embeddings

curl https://api.openhippo.io/v1/embeddings \
  -H "Authorization: Bearer $OPENHIPPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openhippo/Qwen3-Embedding-0.6B", "input": "Augsburg is in Bavaria."}'

Reranking

curl https://api.openhippo.io/v1/rerank \
  -H "Authorization: Bearer $OPENHIPPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openhippo/bge-reranker-v2-m3",
    "query": "Where is the data centre?",
    "documents": ["The data centre is in Augsburg.", "The Lech flows through Augsburg."]
  }'

Das Ergebnis steht im Feld results.

Transkription

curl https://api.openhippo.io/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENHIPPO_API_KEY" \
  -F model="openhippo/whisper-large-v3" \
  -F file="@recording.mp3"

Mit Sprecher-Labels: Modell openhippo/whisper-large-v3-speakers. Abgerechnet wird pro Audio-Sekunde; in der Modellliste als Preis pro Minute angegeben.

Sprachausgabe

curl https://api.openhippo.io/v1/audio/speech \
  -H "Authorization: Bearer $OPENHIPPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openhippo/Qwen3-TTS-1.7B-VoiceDesign",
    "input": "Welcome to Open Hippo.",
    "instructions": "A calm, friendly female voice.",
    "voice": "design",
    "response_format": "mp3"
  }' \
  --output welcome.mp3

input: höchstens 2000 Zeichen. response_format: wav, pcm, mp3 oder flac.
instructions (Pflicht, höchstens 500 Zeichen) beschreibt die Stimme in Worten; voice muss als beliebiger String mitgeschickt werden. Die Stimme wird aus der Beschreibung erzeugt und imitiert keine reale Person.
Abgerechnet wird nur der input-Text, instructions sind kostenlos.

OCR

Texterkennung läuft über Chat Completions, siehe OCR.

Verbrauch abfragen

GET /v1/usage liefert den Verbrauch des aufrufenden Keys im laufenden Monat:

curl "https://api.openhippo.io/v1/usage?month=2026-10" \
  -H "Authorization: Bearer $OPENHIPPO_API_KEY"

month im Format YYYY-MM; verfügbar sind der laufende und der Vormonat. Ohne Parameter: laufender Monat.
Die Antwort enthält total, by_model und by_day (Beträge in EUR), dazu key_limit, currency, timezone (Europe/Berlin) und updated_at.
Höchstens 30 Abfragen pro Minute und Key, danach 429. Nur Bearer-Authentifizierung.
Die Abfrage funktioniert auch bei leerem Guthaben oder erreichtem Budget.

Base URL​