Reference

Documentation

Kiminohappydays implements the OpenAI REST schema. If you have an OpenAI-compatible client, set the base URL and key and everything below works unchanged.

Authentication

All requests use a bearer token in the Authorization header. Keys begin with khd_ and are scoped per project. Create and rotate them from the dashboard; a leaked key can be revoked instantly without affecting other keys.

Keys are invite-only during the current capacity ramp. Email hello@kiminohappydays.org with a line about what you are building and we send one in the next batch, usually within a week.

Authorization: Bearer khd_live_xxxxxxxxxxxxxxxxxxxx

Base URL

One base URL serves every endpoint. Append the region hint header to pin processing to a jurisdiction.

https://api.kiminohappydays.org/v1

# optional region pin: eu | us
X-Kiminohappydays-Region: eu

Chat completions

Standard chat endpoint with streaming, tool calls, JSON mode, and vision on the multimodal models. Set stream: true for server-sent events.

POST/v1/chat/completions

Generate a chat response. Reasoning models return a reasoning field alongside content.

curl https://api.kiminohappydays.org/v1/chat/completions \
  -H "Authorization: Bearer $KIMINOHAPPYDAYS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-r1",
    "messages": [{"role": "user", "content": "Prove sqrt(2) is irrational."}],
    "stream": true
  }'

Embeddings

Batch up to 2048 inputs per call. Returns 1024-dimension vectors from bge-m3.

POST/v1/embeddings

Vectorise text for retrieval. Accepts a string or an array of strings in input.

curl https://api.kiminohappydays.org/v1/embeddings \
  -H "Authorization: Bearer $KIMINOHAPPYDAYS_KEY" \
  -d '{"model": "bge-m3", "input": ["first doc", "second doc"]}'

Reranking

Cross-encoder scoring for the retrieval step of a RAG pipeline. Pass a query and a list of documents; get sorted relevance scores back.

POST/v1/rerank

Score documents against a query with bge-reranker-v2-m3.

Audio

Two audio endpoints, both OpenAI-shaped. Transcription accepts a multipart file upload; synthesis returns an audio stream.

POST/v1/audio/transcriptions

Speech to text with whisper-large-v3. Optional timestamp_granularities of word or segment; set task=translate to render any language into English.

curl https://api.kiminohappydays.org/v1/audio/transcriptions \
  -H "Authorization: Bearer $KIMINOHAPPYDAYS_KEY" \
  -F model=whisper-large-v3 \
  -F file=@meeting.mp3 \
  -F timestamp_granularities[]=word

POST/v1/audio/speech

Text to speech with kokoro-82m. Choose a voice, a response_format of wav, mp3, or opus, and optionally stream PCM as it renders.

curl https://api.kiminohappydays.org/v1/audio/speech \
  -H "Authorization: Bearer $KIMINOHAPPYDAYS_KEY" \
  -d '{
    "model": "kokoro-82m",
    "voice": "af_sky",
    "input": "Rendered on open weights.",
    "response_format": "mp3"
  }' --output speech.mp3

Errors & limits

Errors follow the OpenAI error envelope. Rate and spend limits return 429; the body names which limit tripped and Retry-After gives the backoff.

401 — missing or invalid key
404 — unknown model ID
429 — rate limit or spend cap reached
503 — model warming; retry after the given interval

Data & privacy

Request and response bodies are held only for the life of the request and are never used to train models. Metadata needed for billing (token counts, timestamps, model ID) is retained; content is not. Pin X-Kiminohappydays-Region: eu and both compute and metadata stay within the EU. A DPA is available for reserved accounts.