Authentication & basics

Base URL

https://api.openhippo.io/v1

Authentication

Every request carries the API key as a bearer token:

Authorization: Bearer hk_live_0123456789abcdef0123456789abcdef

• Keys have the format hk_live_ followed by 32 hex characters.
• The console shows a key only once, when it is created. Lost it? Regenerate it in the console.
• A missing or invalid key returns 401:

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

You manage keys in the console: create, edit (name, budget), regenerate, revoke. See Console & team administration.

Keys belong on the server

An API key gives access to your balance. Never put it in frontend code, apps or public repositories. Set a budget for every key.

Endpoints

Two API families on the same base URL:

• OpenAI-compatible: /v1/chat/completions and the further paths below.
• Anthropic-compatible: /v1/messages (streaming included) and /v1/messages/count_tokens.

Method	Path	Purpose
POST	/v1/chat/completions	Chat (OpenAI format), streaming, tool calling, images
POST	/v1/completions	Text completion (OpenAI format)
POST	/v1/messages	Chat (Anthropic format), streaming
POST	/v1/messages/count_tokens	Count tokens (Anthropic format)
POST	/v1/responses	Responses API, create only
POST	/v1/embeddings	Embeddings
POST	/v1/rerank, /v2/rerank	Reranking
POST	/v1/audio/transcriptions	Transcription (file upload)
POST	/v1/audio/speech	Text to speech
GET	/v1/models, /v1/models/{id}	List models
GET	/v1/usage	Usage of the calling key

The paths for chat completions, completions, embeddings, rerank and models also work without /v1 (e.g. /chat/completions). Every other path answers 404.

Examples for further endpoints

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."]
  }'

The result is in the results field.

Transcription

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

With speaker labels: model openhippo/whisper-large-v3-speakers. Billed per audio second; the model list shows the price per minute.

Text to speech

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: at most 2000 characters. response_format: wav, pcm, mp3 or flac.
• instructions (required, at most 500 characters) describes the voice in words; voice must be sent as any string. The voice is made up from the description and never imitates a real person.
• Only the input text is billed; instructions are free.

OCR

Text recognition runs through chat completions, see OCR.

Checking usage

GET /v1/usage returns the spend of the calling key in the current month:

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

• month in the format YYYY-MM; the current and the previous month are available. Without the parameter: the current month.
• The response contains total, by_model and by_day (amounts in EUR), plus key_limit, currency, timezone (Europe/Berlin) and updated_at.
• At most 30 queries per minute and key, then 429. Bearer authentication only.
• The query also works when the balance is empty or a budget is reached.