# LumyxAI API — for LLMs

> Drop this file into ChatGPT, Claude, or any LLM and ask questions about the API.

LumyxAI is an OpenAI-compatible AI API gateway. One endpoint, every model.

- **Base URL:** `https://lumyx-ai.site/api/v1`
- **Auth:** `Authorization: Bearer YOUR_API_KEY`
- **Compatibility:** OpenAI Chat Completions spec + Anthropic Messages spec

Get an API key at https://lumyx-ai.site/dashboard/api-keys.

---

## Endpoints

### `POST /api/v1/chat/completions`
OpenAI-compatible chat completion. Drop-in replacement for OpenAI's endpoint — just change the base URL.

**Request body:**
```json
{
  "model": "lumyx-plus_v1",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024,
  "top_p": 1.0,
  "frequency_penalty": 0,
  "presence_penalty": 0
}
```

**Headers:**
- `Authorization: Bearer YOUR_API_KEY` (required)
- `Content-Type: application/json`

**Response (non-streaming):**
```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "lumyx-plus_v1",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hi! How can I help?"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20}
}
```

**Streaming:** set `"stream": true` and receive SSE chunks (`data: {...}\n\n`, terminated by `data: [DONE]`).

### `POST /api/v1/messages`
Anthropic Messages-compatible endpoint. Use this with the official `@anthropic-ai/sdk` by setting the base URL to `https://lumyx-ai.site/api/v1`.

**Request body:**
```json
{
  "model": "lumyx-plus_v1",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "system": "You are a helpful assistant.",
  "stream": false
}
```

Supports tool use, vision (image input), and streaming via the same shape as Anthropic's official API.

### `GET /api/v1/models`
Returns all available models with metadata (context window, pricing, capabilities, tags).

**Response:**
```json
{
  "object": "list",
  "data": [
    {
      "id": "lumyx-plus_v1",
      "object": "model",
      "_meta": {
        "displayName": "Lumyx Plus v1",
        "description": "...",
        "contextWindow": 128000,
        "supportsStreaming": true,
        "tags": ["reasoning", "vision", "tools"],
        "pricing": {"input": 0.5, "output": 1.5, "free": false}
      }
    }
  ]
}
```

### `POST /api/v1/embeddings`
OpenAI-compatible embedding endpoint.

**Request body:**
```json
{
  "model": "embedding-model-id",
  "input": "Text to embed",
  "encoding_format": "float"
}
```

---

## Capabilities by model

Models advertise capabilities via the `_meta.tags` array on `/models`. Common tags:

- `streaming` — supports SSE streaming via `stream: true`
- `vision` — accepts image inputs in the message content array
- `tools` — supports function calling / tool use
- `reasoning` — extended thinking / chain-of-thought capable
- `uncensored` — requires policy acceptance before use

---

## Vision input (multi-modal)

For models tagged `vision`, image inputs follow OpenAI's content-array format:

```json
{
  "model": "vision-model-id",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What's in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ]
  }]
}
```

Data URLs (`data:image/png;base64,...`) are also supported.

---

## Tool use / function calling

OpenAI-style tools (`tools` + `tool_choice` fields) for models tagged `tools`:

```json
{
  "model": "tool-capable-model",
  "messages": [{"role": "user", "content": "What's the weather in SF?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"]
      }
    }
  }],
  "tool_choice": "auto"
}
```

The model responds with `tool_calls` in the assistant message; you call the function and submit the result as a `tool` role message.

---

## Reasoning models

Models tagged `reasoning` support an extended-thinking pass before the final answer. The reasoning content is exposed in the response (`message.reasoning_content` on chat completions, or `thinking` blocks on the Anthropic endpoint). You can configure effort via `reasoning_effort`: `"low" | "medium" | "high"`.

---

## Errors

All errors follow this shape:

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

Common error types:
- `authentication_error` (401) — missing or invalid API key
- `authorization_error` (403) — key valid but lacks access
- `invalid_request_error` (400) — malformed body / params
- `rate_limit_error` (429) — too many requests
- `server_error` (502/500) — upstream provider issue
- `not_found_error` (404) — model or resource missing

---

## Rate limits

Free-tier accounts: 25 requests per day across free models. VIP tiers scale daily limits up to 1,000/day. Paid credits never expire; VIP credits refresh monthly.

Rate-limit response headers:
- `x-ratelimit-limit-requests`
- `x-ratelimit-remaining-requests`
- `x-ratelimit-reset-requests`

---

## SDKs — drop-in compatibility

**OpenAI (Python):**
```python
from openai import OpenAI
client = OpenAI(
    base_url="https://lumyx-ai.site/api/v1",
    api_key="lx-..."
)
resp = client.chat.completions.create(
    model="lumyx-plus_v1",
    messages=[{"role": "user", "content": "Hi"}]
)
```

**OpenAI (Node):**
```js
import OpenAI from "openai"
const client = new OpenAI({
  baseURL: "https://lumyx-ai.site/api/v1",
  apiKey: "lx-...",
})
const resp = await client.chat.completions.create({
  model: "lumyx-plus_v1",
  messages: [{ role: "user", content: "Hi" }],
})
```

**Anthropic SDK:**
```js
import Anthropic from "@anthropic-ai/sdk"
const client = new Anthropic({
  baseURL: "https://lumyx-ai.site/api/v1",
  apiKey: "lx-...",
})
const msg = await client.messages.create({
  model: "lumyx-plus_v1",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hi" }],
})
```

**cURL:**
```bash
curl https://lumyx-ai.site/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"lumyx-plus_v1","messages":[{"role":"user","content":"Hi"}]}'
```

---

## Account links

- Sign in / register: https://lumyx-ai.site/login
- Dashboard: https://lumyx-ai.site/dashboard
- API keys: https://lumyx-ai.site/dashboard/api-keys
- Usage analytics: https://lumyx-ai.site/dashboard/usage
- Buy credits: https://lumyx-ai.site/dashboard/credits
- Models catalog: https://lumyx-ai.site/models
- Pricing: https://lumyx-ai.site/pricing
- Full docs (HTML): https://lumyx-ai.site/docs