Lunos logoLunos
DocsIntegration

API reference

The Lunos HTTP API exposes chat, completions, embeddings, images, audio, balance, and model listing on an OpenAI-style surface, and also serves the Anthropic Messages API at /v1/messages for Anthropic-native clients. This page summarizes how to call it safely and where to read more.

Important: Treat API keys like passwords. Only use them on servers, workers, or other trusted environments — never in public clients.

Request headers

X-App-ID (optional)

Identifies the calling app for analytics and usage attribution. If omitted, traffic may be recorded as unknown.

Header Type Required Description
X-App-ID string No Logical app or service name (e.g. billing-v2).

Example

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-App-ID: my-application-v1

Analytics: The same key can power multiple apps if you vary X-App-ID per deployment.

Observability flag

Lunos supports opt-in completion observability using an internal request flag:

Field Type Required Description
observability boolean No When true, stores request/output details linked to the same query history row.

Use this only when you need deep request inspection. If omitted (or false), no observability payload is stored.

Example (/chat/completions)

{
  "model": "google/gemma-4-26b-a4b-it",
  "observability": true,
  "messages": [
    {
      "role": "user",
      "content": [{ "type": "text", "text": "Can you jogging?" }]
    }
  ]
}

After the request completes, open Dashboard → Logs → Detail on that row to inspect:

  • generated id
  • request messages
  • response output
  • usage breakdown (tokens, cost, TPS)

Base URL

https://api.lunos.tech/v1

All paths below are rooted here.

Endpoint overview

Path Method Description
/models GET List models, pricing, and capabilities
/completions POST Legacy-style text completions (when supported by model)
/chat/completions POST Chat / multi-turn completions
/embeddings POST Text embeddings
/images/generations POST Image generation
/audio/transcriptions POST Speech-to-text
/balance GET Account balance and alert settings

Exact payloads match common OpenAI-style fields; always confirm against the live API and dedicated endpoint references:

Models endpoint (summary)

GET /v1/models returns model metadata you can use before calling chat or completions.

curl "https://api.lunos.tech/v1/models"
curl "https://api.lunos.tech/v1/models?output=image"
curl "https://api.lunos.tech/v1/models?input=text,image&output=text"

Available filters:

  • input: filter by supported input modalities (comma-separated)
  • output: filter by supported output modalities (comma-separated)

See Models API for the current schema returned by Lunos.

Completions parameters (classic)

POST /completions accepts typical completion fields:

Parameter Type Required Description
model string Yes Model id
prompt string Yes Input prompt
max_tokens integer No Max generated tokens (default varies)
temperature number No 0–2 sampling temperature
top_p number No Nucleus sampling

Prefer POST /chat/completions for modern chat models.

Client snippets with X-App-ID

JavaScript

const response = await lunos.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
  appId: "my-web-app",
});

Python

response = lunos.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"X-App-ID": "my-python-app"},
)

cURL

curl -X POST "https://api.lunos.tech/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-App-ID: my-curl-app" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Migration note

X-App-ID is optional. Existing integrations keep working; add the header when you want cleaner analytics.

See also