Lunos logoLunos
DocsIntegration

Lunos API documentation

Welcome to the Lunos API documentation. Lunos exposes many AI providers through OpenAI-compatible /v1 routes and the Anthropic Messages API (POST /v1/messages): one base URL, familiar request shapes for each stack, and unified billing.

New: The @lunos/client package is the first-party helper for JavaScript or TypeScript.

Install:

pnpm add @lunos/client

See the npm package for API surface and examples.

Warning: The published @lunos/client release on npm is not always updated in lockstep with the live Lunos API. Some requests may fail or behave differently until a new package version ships. For production workloads, prefer the OpenAI JavaScript SDK (or another OpenAI-compatible client) with baseURL set to https://api.lunos.tech/v1, or call the HTTP API directly.

Note: This documentation describes the Lunos API v1. Use the base URL below for all routes unless a page states otherwise.

Authentication

Every request must include your secret API key from the API Keys page.

Authorization: Bearer YOUR_API_KEY

Important: Never expose API keys in browsers, mobile apps, or public repositories. Call Lunos from your backend or a secure worker.

Base URL

https://api.lunos.tech/v1

Paths in this documentation are relative to this prefix (for example, POST /chat/completions means POST https://api.lunos.tech/v1/chat/completions).

Request format

Use POST with a JSON body unless an endpoint specifies GET. Set:

Content-Type: application/json

Optional header for per-app analytics (see API overview):

X-App-ID: my-service-v1

Successful response shape

Responses are JSON. A typical completion-style payload looks like:

{
  "id": "resp_abc123",
  "object": "completion",
  "created": 1677858242,
  "model": "openai/gpt-4o",
  "provider": "openai",
  "data": {
    "choices": [
      {
        "text": "The generated text response...",
        "index": 0,
        "finish_reason": "stop"
      }
    ]
  },
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Exact fields vary by endpoint; always inspect the live response for your route and model.

Errors

Errors return an HTTP status and a JSON body with details, for example:

{
  "error": {
    "code": "invalid_request_error",
    "message": "The model 'nonexistent-model' does not exist",
    "param": "model",
    "type": "invalid_request_error"
  }
}

Example: chat-style request

curl -X POST https://api.lunos.tech/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      { "role": "user", "content": "Write a short poem about artificial intelligence." }
    ],
    "max_tokens": 150,
    "temperature": 0.7
  }'

Next steps