Documentation

API Docs

Two ways to use the router: the OpenAI-compatible gateway /api/v1 (using an API key from the dashboard) and the simple endpoint /api/ai/chat (anonymous or with a key).

Replace <domain> with your deployment domain, e.g. https://hymn-router.vercel.app

Account

How to sign in

Three ways in, one account

Sign in at /login with email + password, Google, or GitHub (GitHub is active if the server has its OAuth App configured).
Sign up with email: passwords must be at least 8 characters and are stored as scrypt hashes — the original password is never stored.
One email = one account: if you sign up with email and then sign in with Google/GitHub using the same email, the accounts are linked automatically — any sign-in method leads to the same account.
There is no email verification yet: accounts registered by email are active immediately.
Sign-in is limited to 10 attempts per 15 minutes per IP (anti brute force). Sign-in error messages are deliberately generic so registered emails cannot be guessed.

Gateway

API v1 — OpenAI-compatible

How it works

A single gateway, POST /api/v1/chat/completions, with the OpenAI request/response format. The OpenAI SDK, cURL, and plain fetch all work right away — just change the base URL.
The Authorization: Bearer hr_... header is required, with an API key from the dashboard. No key / invalid key → 401.
model can be hymn/auto (default, full fallback chain), a provider id (e.g. groq), a model id (e.g. openai/gpt-oss-120b), or an OpenRouter model ending in :free (e.g. google/gemma-4-26b-a4b-it:free). Unknown model → 404. The full list (live, may change) is on the /models page.
stream: true returns OpenAI-compatible SSE (chunks of choices[0].delta, ending with [DONE]). See the Streaming section below.
Rate limit: 60 requests/minute per API key (above that → 429). Free plan daily quota: 100 requests/day per user, resetting at 00:00 WIB (exhausted → 429 quota_exceeded). Remaining quota is visible in the dashboard and in the X-Quota-Remaining header.
Usage is recorded in the dashboard: requests, tokens, provider, model, a daily chart, and recent requests.
If all providers fail → 502, with each provider's reason.

POST /api/v1/chat/completions — cURL

curl <domain>/api/v1/chat/completions \
  -H "Authorization: Bearer hr_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hymn/auto",
    "messages": [{ "role": "user", "content": "Halo!" }],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

POST /api/v1/chat/completions — Python (OpenAI SDK)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HYMN_ROUTER_API_KEY"],
    base_url="<domain>/api/v1",
)

res = client.chat.completions.create(
    model="hymn/auto",  # atau "groq", atau id model
    messages=[{"role": "user", "content": "Halo!"}],
)

print(res.choices[0].message.content)

POST /api/v1/chat/completions — success response (200)

{
  "id": "chatcmpl-9f2ab41c...",
  "object": "chat.completion",
  "created": 1794569000,
  "model": "openai/gpt-oss-120b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Halo!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20 }
}

GET /api/v1/models — model list (no auth)

curl <domain>/api/v1/models

# -> { "object": "list", "data": [
#      { "id": "hymn/auto", "object": "model", "owned_by": "hymn-router",
#        "provider": "hymn-router", "configured": true, "needs_key": false,
#        "free_tier": "Fallback chain 9 provider..." },
#      { "id": "openai/gpt-oss-120b", "object": "model", "owned_by": "groq",
#        "provider": "groq", "configured": true, "needs_key": true,
#        "free_tier": "Free: 30 RPM, 1000 req/hari..." },
#      ... ] }
# Field tambahan (provider, configured, needs_key, free_tier) aman
# diabaikan client OpenAI. Versi visualnya ada di halaman /models.

Real-time

Streaming (SSE)

How it works

Send stream: true in the /v1 body (or /api/ai/chat) to receive tokens one by one over Server-Sent Events. The chunk format is the same as OpenAI: text deltas in choices[0].delta.content, the final chunk carries finish_reason, then the line data: [DONE].
The router waits for the first token from the provider before responding — so if the first provider fails, fallback to the next provider still works before the stream starts.
If a provider does not support streaming, the router uses a non-stream response and sends it as a single delta chunk. Clients never need to handle two formats.
Token usage in the dashboard: if the provider reports usage in the stream, those numbers are used; otherwise tokens are estimated from text length (±4 characters per token). This estimate is only for the dashboard and is not sent to the client.
The /api/ai/chat endpoint sends one extra event at the start of the stream: event: meta with the provider, model, and providers that failed along the way. The /v1 endpoint sends no meta (strictly OpenAI-compatible).

Streaming — cURL (use -N to disable buffering)

curl -N <domain>/api/v1/chat/completions \
  -H "Authorization: Bearer hr_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hymn/auto",
    "messages": [{ "role": "user", "content": "Cerita singkat tentang kucing." }],
    "stream": true
  }'

# -> data: {"id":"chatcmpl-...","object":"chat.completion.chunk",
#      "model":"...","choices":[{"index":0,
#      "delta":{"role":"assistant","content":""},"finish_reason":null}]}
# -> data: {"id":"...","object":"chat.completion.chunk",
#      "choices":[{"index":0,"delta":{"content":"Dulu"},"finish_reason":null}]}
# -> ... (satu chunk per delta teks)
# -> data: {"id":"...","object":"chat.completion.chunk",
#      "choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
# -> data: [DONE]

Streaming — Python (OpenAI SDK, stream=True)

from openai import OpenAI

client = OpenAI(api_key="hr_KEY_ANDA", base_url="<domain>/api/v1")

stream = client.chat.completions.create(
    model="hymn/auto",
    messages=[{"role": "user", "content": "Cerita singkat tentang kucing."}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Reference

Error codes

400invalid_request_errorInvalid body: empty messages / more than 50 messages, unknown role, content over 20,000 characters, temperature outside 0–2, max_tokens outside 1–8192, or stream not a boolean.

401invalid_api_keyMissing Authorization header, invalid key, or revoked key. Create a new key in the dashboard.

404model_not_foundUnknown model. Use "hymn/auto", a provider id, a model id from GET /api/v1/models, or an OpenRouter model ending in ":free".

429rate_limit_exceededAbove 60 requests/minute per API key (or 20/minute per IP for anonymous /api/ai/chat).

429quota_exceededThe free daily quota (100 requests/day) is exhausted. The response includes retry_after (seconds) and a Retry-After header; reset at 00:00 WIB.

502all_providers_failedAll providers failed (429 / 5xx / timeout). The error message contains each provider's reason.

503model_unavailableA :free model was requested but the server has not configured OPENROUTER_API_KEY.

503server_not_configuredDATABASE_URL is not set on the server — API keys cannot be validated yet.

Simple

API /api/ai/chat

How it works

The simple endpoint POST /api/ai/chat calls the 9 free providers (Groq, NVIDIA, Gemini, OpenRouter, Mistral, Kilo, LLM7, Pollinations, OVH) in order until one succeeds.
Anonymous: rate limit of 20 requests/minute per IP, with no daily quota. With the Authorization: Bearer hr_... header: a 60/minute per-key limit, usage recorded in the dashboard, and the 100 requests/day daily quota applies. An invalid Bearer → 401 (no anonymous fallback).
Add stream: true to the body for SSE (same format as /v1, plus an event: meta at the start with the provider/model). The /chat playground uses this mode.
A provider hit by 429 / 5xx / timeout enters a 60-second cooldown, then is retried on the next request.
All provider API keys are only read server-side from env. No key is ever sent to the browser.
If all providers fail, the response is a 502 with each provider's reason — so it is easy to debug.

POST /api/ai/chat — curl

curl -X POST <domain>/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"halo, jawab singkat"}]}'

# Dengan API key (limit 60/menit/key, tercatat di dasbor):
#   -H "Authorization: Bearer hr_KEY_ANDA"

POST /api/ai/chat — request body

{
  "messages": [
    { "role": "system", "content": "Jawab singkat." },
    { "role": "user", "content": "Apa itu LLM?" }
  ],
  "temperature": 0.7,        // opsional, 0–2, default 0.7
  "maxTokens": 1024,         // opsional, 1–8192, default 1024
  "preferProvider": "groq"   // opsional, tetap fallback jika gagal
}

POST /api/ai/chat — success response (200)

{
  "provider": "groq",
  "model": "openai/gpt-oss-120b",
  "content": "LLM adalah ...",
  "tried": [],               // provider yang gagal sebelum yang berhasil
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  }
}

GET /api/ai/chat — provider status (no key, safe to open)

curl <domain>/api/ai/chat

Notes

Limits & privacy

Things to keep in mind

Free tiers change over time: OpenRouter :free models can disappear or become paid at any time. Check https://openrouter.ai/api/v1/models if a model returns 404.
Never send sensitive data through this router — prompts on free tiers may be used by providers to improve their products or recorded in logs. This server itself does not store prompts or responses; only request counts, tokens, providers, and latency are recorded.
Statistics in the Provider section are per server process and reset on restart. Per-user usage history (dashboard) is stored permanently in the database.

<>Hymn Router

Start

Documentation

API Docs

Two ways to use the router: the OpenAI-compatible gateway /api/v1 (using an API key from the dashboard) and the simple endpoint /api/ai/chat (anonymous or with a key).

Replace <domain> with your deployment domain, e.g. https://hymn-router.vercel.app

Account

How to sign in

Three ways in, one account

Sign in at /login with email + password, Google, or GitHub (GitHub is active if the server has its OAuth App configured).
Sign up with email: passwords must be at least 8 characters and are stored as scrypt hashes — the original password is never stored.
One email = one account: if you sign up with email and then sign in with Google/GitHub using the same email, the accounts are linked automatically — any sign-in method leads to the same account.
There is no email verification yet: accounts registered by email are active immediately.
Sign-in is limited to 10 attempts per 15 minutes per IP (anti brute force). Sign-in error messages are deliberately generic so registered emails cannot be guessed.

Gateway

API v1 — OpenAI-compatible

How it works

A single gateway, POST /api/v1/chat/completions, with the OpenAI request/response format. The OpenAI SDK, cURL, and plain fetch all work right away — just change the base URL.
The Authorization: Bearer hr_... header is required, with an API key from the dashboard. No key / invalid key → 401.
model can be hymn/auto (default, full fallback chain), a provider id (e.g. groq), a model id (e.g. openai/gpt-oss-120b), or an OpenRouter model ending in :free (e.g. google/gemma-4-26b-a4b-it:free). Unknown model → 404. The full list (live, may change) is on the /models page.
stream: true returns OpenAI-compatible SSE (chunks of choices[0].delta, ending with [DONE]). See the Streaming section below.
Rate limit: 60 requests/minute per API key (above that → 429). Free plan daily quota: 100 requests/day per user, resetting at 00:00 WIB (exhausted → 429 quota_exceeded). Remaining quota is visible in the dashboard and in the X-Quota-Remaining header.
Usage is recorded in the dashboard: requests, tokens, provider, model, a daily chart, and recent requests.
If all providers fail → 502, with each provider's reason.

POST /api/v1/chat/completions — cURL

curl <domain>/api/v1/chat/completions \
  -H "Authorization: Bearer hr_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hymn/auto",
    "messages": [{ "role": "user", "content": "Halo!" }],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

POST /api/v1/chat/completions — Python (OpenAI SDK)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HYMN_ROUTER_API_KEY"],
    base_url="<domain>/api/v1",
)

res = client.chat.completions.create(
    model="hymn/auto",  # atau "groq", atau id model
    messages=[{"role": "user", "content": "Halo!"}],
)

print(res.choices[0].message.content)

POST /api/v1/chat/completions — success response (200)

{
  "id": "chatcmpl-9f2ab41c...",
  "object": "chat.completion",
  "created": 1794569000,
  "model": "openai/gpt-oss-120b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Halo!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20 }
}

GET /api/v1/models — model list (no auth)

curl <domain>/api/v1/models

# -> { "object": "list", "data": [
#      { "id": "hymn/auto", "object": "model", "owned_by": "hymn-router",
#        "provider": "hymn-router", "configured": true, "needs_key": false,
#        "free_tier": "Fallback chain 9 provider..." },
#      { "id": "openai/gpt-oss-120b", "object": "model", "owned_by": "groq",
#        "provider": "groq", "configured": true, "needs_key": true,
#        "free_tier": "Free: 30 RPM, 1000 req/hari..." },
#      ... ] }
# Field tambahan (provider, configured, needs_key, free_tier) aman
# diabaikan client OpenAI. Versi visualnya ada di halaman /models.

Real-time

Streaming (SSE)

How it works

Send stream: true in the /v1 body (or /api/ai/chat) to receive tokens one by one over Server-Sent Events. The chunk format is the same as OpenAI: text deltas in choices[0].delta.content, the final chunk carries finish_reason, then the line data: [DONE].
The router waits for the first token from the provider before responding — so if the first provider fails, fallback to the next provider still works before the stream starts.
If a provider does not support streaming, the router uses a non-stream response and sends it as a single delta chunk. Clients never need to handle two formats.
Token usage in the dashboard: if the provider reports usage in the stream, those numbers are used; otherwise tokens are estimated from text length (±4 characters per token). This estimate is only for the dashboard and is not sent to the client.
The /api/ai/chat endpoint sends one extra event at the start of the stream: event: meta with the provider, model, and providers that failed along the way. The /v1 endpoint sends no meta (strictly OpenAI-compatible).

Streaming — cURL (use -N to disable buffering)

curl -N <domain>/api/v1/chat/completions \
  -H "Authorization: Bearer hr_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hymn/auto",
    "messages": [{ "role": "user", "content": "Cerita singkat tentang kucing." }],
    "stream": true
  }'

# -> data: {"id":"chatcmpl-...","object":"chat.completion.chunk",
#      "model":"...","choices":[{"index":0,
#      "delta":{"role":"assistant","content":""},"finish_reason":null}]}
# -> data: {"id":"...","object":"chat.completion.chunk",
#      "choices":[{"index":0,"delta":{"content":"Dulu"},"finish_reason":null}]}
# -> ... (satu chunk per delta teks)
# -> data: {"id":"...","object":"chat.completion.chunk",
#      "choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
# -> data: [DONE]

Streaming — Python (OpenAI SDK, stream=True)

from openai import OpenAI

client = OpenAI(api_key="hr_KEY_ANDA", base_url="<domain>/api/v1")

stream = client.chat.completions.create(
    model="hymn/auto",
    messages=[{"role": "user", "content": "Cerita singkat tentang kucing."}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Reference

Error codes

401invalid_api_keyMissing Authorization header, invalid key, or revoked key. Create a new key in the dashboard.

404model_not_foundUnknown model. Use "hymn/auto", a provider id, a model id from GET /api/v1/models, or an OpenRouter model ending in ":free".

429rate_limit_exceededAbove 60 requests/minute per API key (or 20/minute per IP for anonymous /api/ai/chat).

429quota_exceededThe free daily quota (100 requests/day) is exhausted. The response includes retry_after (seconds) and a Retry-After header; reset at 00:00 WIB.

502all_providers_failedAll providers failed (429 / 5xx / timeout). The error message contains each provider's reason.

503model_unavailableA :free model was requested but the server has not configured OPENROUTER_API_KEY.

503server_not_configuredDATABASE_URL is not set on the server — API keys cannot be validated yet.

Simple

API /api/ai/chat

How it works

The simple endpoint POST /api/ai/chat calls the 9 free providers (Groq, NVIDIA, Gemini, OpenRouter, Mistral, Kilo, LLM7, Pollinations, OVH) in order until one succeeds.
Anonymous: rate limit of 20 requests/minute per IP, with no daily quota. With the Authorization: Bearer hr_... header: a 60/minute per-key limit, usage recorded in the dashboard, and the 100 requests/day daily quota applies. An invalid Bearer → 401 (no anonymous fallback).
Add stream: true to the body for SSE (same format as /v1, plus an event: meta at the start with the provider/model). The /chat playground uses this mode.
A provider hit by 429 / 5xx / timeout enters a 60-second cooldown, then is retried on the next request.
All provider API keys are only read server-side from env. No key is ever sent to the browser.
If all providers fail, the response is a 502 with each provider's reason — so it is easy to debug.

POST /api/ai/chat — curl

curl -X POST <domain>/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"halo, jawab singkat"}]}'

# Dengan API key (limit 60/menit/key, tercatat di dasbor):
#   -H "Authorization: Bearer hr_KEY_ANDA"

POST /api/ai/chat — request body

{
  "messages": [
    { "role": "system", "content": "Jawab singkat." },
    { "role": "user", "content": "Apa itu LLM?" }
  ],
  "temperature": 0.7,        // opsional, 0–2, default 0.7
  "maxTokens": 1024,         // opsional, 1–8192, default 1024
  "preferProvider": "groq"   // opsional, tetap fallback jika gagal
}

POST /api/ai/chat — success response (200)

{
  "provider": "groq",
  "model": "openai/gpt-oss-120b",
  "content": "LLM adalah ...",
  "tried": [],               // provider yang gagal sebelum yang berhasil
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  }
}

GET /api/ai/chat — provider status (no key, safe to open)

curl <domain>/api/ai/chat

Notes

Limits & privacy

Things to keep in mind

Free tiers change over time: OpenRouter :free models can disappear or become paid at any time. Check https://openrouter.ai/api/v1/models if a model returns 404.
Never send sensitive data through this router — prompts on free tiers may be used by providers to improve their products or recorded in logs. This server itself does not store prompts or responses; only request counts, tokens, providers, and latency are recorded.
Statistics in the Provider section are per server process and reset on restart. Per-user usage history (dashboard) is stored permanently in the database.