Lumo API Tracker
Developer Tracker

Lumo API

Unofficial development tracker for the Proton Lumo API. Documents what works, what doesn't, and tested Python examples updated as the API evolves.

API v1 — Early Access API Functional Remaining tools to be fixed 2 Last tested: July 26 2026
I welcome any information you may wish to share. Reach out to Threema: *0001337 Note: Keys generation methods are available. Inquire directly for potential details
▶ GET API KEY ▶ OPENCODE ▶ Lumodroid ▶ GENERATE IMAGES ▶ DESCRIBE IMAGE ▶ Comic Story ▶ SKETCH & DESCRIBE ▶ API DEBUG ▶ CUSTOM AGENTS TEST ▶ RED TEAM
LATEST UPDATES
reasoning_effort validated — only "none" (fast) and "high" (~2-3x slower with thinking) accepted; invalid values return HTTP 422
Response now includes provider, finish_reason, usage.prompt_tokens_details.cached_tokens, and remaining_limits (lite/max/images)
Models renamed: lumo-lite (fast) and lumo-max (reasoning); auto routes optimally
Chat tools: weather, stock, web_search, cryptocurrency, proton_info
Image tools: generate_image, describe_image, edit_image, web_search, web_extract
Limits endpoint returns static quotas: remaining_limits.lite, remaining_limits.max, remaining_limits.images
"provider": "lumo",
"finish_reason": "stop",
"usage": {
    "completion_tokens": 55,
    "prompt_tokens": 2136,
    "total_tokens": 2191,
    "prompt_tokens_details": {
        "cached_tokens": 1800
    },
    "remaining_limits": {
        "lite": 19,
        "max": 20,
        "images": 20
    },
    "applied_limit_category": "lite"
}
Overview

Feature Status

Tested directly against the live API. The Lumo API launched recently and the backend does not yet expose all features described in the frontend documentation config.

POST /chat/completions
Core endpoint works. Can be turned on/off and is now required.
POST /account/1337/personal-access-token
Core endpoint works. Allows to list and create keys (requires special commands not disclosed here.)
temperature
The API just ignores this field.
max_tokens
The API does not respects this field. But now returns the number of tokens used on the response.
system role
System prompt in messages array works and influences tone and behavior.
Multi-turn conversations
Full message history with user/assistant alternation works correctly.
stream: True
Streaming is enabled. API always returns SSE stream.
Encryption
The Endpoint ignores the Encrypted field for both True/False, some progress here...
OpenCode

OpenCode Integration

Drop this config into your project's opencode.json to use the Lumo API directly from OpenCode. Lumo is auto detected.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lumo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Lumo",
      "options": {
        "baseURL": "https://api.carlostkd.ch/v1"
      },
      "models": {
        "auto": {
          "name": "Lumo Auto"
        }
      }
    }
  }
}
Models

Available API Models

Three models are available on the chat completions endpoint. The auto model is recommended for general use as it routes to the best backend model for the task.

auto
Auto-route
Lumo selects the optimal model based on task type, prompt complexity, and cost. Recommended for most use cases.
200k ctx chat analysis vision code
lumo-lite
Lumo Lite
Optimised for low-latency and high-throughput. Best for classification, short-form generation, and real-time applications.
266k ctx chat vision classification extraction
lumo-max
Lumo Max
Best-in-class reasoning for complex analytical tasks, multi-step code generation, and long-document synthesis. Produces a visible thinking block before the answer.
200k ctx reasoning analysis vision code
Request Schema

Supported Parameters

The endpoint is OpenAI chat completions compatible. Only parameters confirmed as working are listed here.

Parameter Type Required Description
model string required Model ID. Use auto, lumo-lite, or lumo-max.
messages array required Conversation history as {role, content} objects. Roles: system, user, assistant.
Create/List Keys array required Its possible to do this I do not intend to disclose this method publicly
temperature number optional Sampling temperature 0.0–2.0. Lower = more deterministic. Default: 1.0.
max_tokens integer optional Maximum tokens in the completion. Defaults to model output limit.
stream boolean optional Can be turned ON/OFF and is now required.
reasoning_effort string optional Controls model thinking. Valid values: "none" (fast, no thinking) and "high" (slow, ~2-3x latency with visible thinking block). Invalid values like "low", "medium" return HTTP 422. Default: "high".
Complete Example

Full Working Script

Production ready script with all confirmed working features. Switch models by commenting and uncommenting the MODEL lines. Extend MESSAGES for multi-turn conversations. Includes reasoning_effort, streaming, and all available tools.

python — lumo_chat.py
import requests
import json

API_KEY = "your_api_key_here"
# MODEL = "auto"
# MODEL = "lumo-max"
MODEL = "lumo-lite"

TEMPERATURE = 0.7
MAX_TOKENS = 1024
# "none" = fast (no thinking), "high" = slow (with thinking)
REASONING_EFFORT = "high"

# Tools must be in OpenAI function format. Simple string names may not work.
TOOLS = [
    {"type": "function", "function": {"name": "weather", "description": "Get weather data", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "stock", "description": "Get stock price", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "web_search", "description": "Search the web", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "cryptocurrency", "description": "Get crypto prices", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "proton_info", "description": "Get Proton product info", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "generate_image", "description": "Generate an image", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "describe_image", "description": "Describe an image", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "edit_image", "description": "Edit an image", "parameters": {"type": "object", "properties": {}, "required": []}}},
    {"type": "function", "function": {"name": "web_extract", "description": "Extract content from web page", "parameters": {"type": "object", "properties": {}, "required": []}}}
]

SYSTEM_PROMPT = "You are a helpful assistant that gives concise and accurate answers."

MESSAGES = [
    {"role": "user", "content": "why is the sky blue?"},
]

url = "https://lumo-api.proton.me/api/ai/v1/chat/completions"
headers = {
    "Authorization": "Bearer " + API_KEY,
    "Content-Type": "application/json",
}
payload = {
    "model": MODEL,
    "messages": [{"role": "system", "content": SYSTEM_PROMPT}] + MESSAGES,
    "temperature": TEMPERATURE,
    "max_tokens": MAX_TOKENS,
    "reasoning_effort": REASONING_EFFORT,
    "stream": True,
    "tools": TOOLS,
}

r = requests.post(url, headers=headers, json=payload, timeout=120)
r.raise_for_status()

chunks = []
for line in r.iter_lines():
    if line and line.startswith(b"data:"):
        data = line[5:].decode('utf-8')
        if data == "[DONE]":
            break
        try:
            chunk = json.loads(data)
            choices = chunk.get("choices", [])
            if choices:
                delta = choices[0].get("delta", {})
                if isinstance(delta, dict):
                    content = delta.get("content")
                    if content:
                        chunks.append(content)
        except (json.JSONDecodeError, KeyError, TypeError):
            continue

full_content = "".join(chunks)

if "</think>" in full_content:
    full_content = full_content.split("</think>", 1)[1].strip()

print(full_content)
python — list_models.py
import requests
import json

API_KEY = "your_api_key_here"

url = "https://lumo-api.proton.me/api/ai/v1/models"
headers = {
    "Authorization": "Bearer " + API_KEY,
    "Content-Type": "application/json",
}

r = requests.get(url, headers=headers, timeout=30)
print("Status:", r.status_code)
print("Response:", json.dumps(r.json(), indent=2))
response — list_models.py output
Status: 200
Response: {
  "object": "list",
  "data": [
    {
      "object": "model",
      "id": "lumo-lite",
      "created": 1779890182,
      "owned_by": "proton",
      "capabilities": {
        "completion_chat": true,
        "function_calling": true,
        "vision": true
      },
      "name": "Lumo Lite",
      "description": "Fast, efficient model for everyday tasks.",
      "max_context_length": 131072,
      "aliases": [],
      "deprecation": null,
      "deprecation_replacement_model": null,
      "default_model_temperature": 1,
      "archived": false
    },
    {
      "object": "model",
      "id": "lumo-max",
      "created": 1779890182,
      "owned_by": "proton",
      "capabilities": {
        "completion_chat": true,
        "function_calling": true,
        "vision": true
      },
      "name": "Lumo Max",
      "description": "More capable model for complex reasoning and longer context.",
      "max_context_length": 131072,
      "aliases": [],
      "deprecation": null,
      "deprecation_replacement_model": null,
      "default_model_temperature": 1,
      "archived": false
    }
  ]
}
python — create_keys.py
Redacted: I do not intend to disclose this method publicly prior to its official launch
      
Native Endpoint

Real-Time Tools via /api/ai/v1/chat/completions

The native endpoint uses a proprietary Prompt wrapper format and supports real-time tools fully. This is separate from the OpenAI-compatible endpoint tools passed to /chat/completions are still ignored there.

Key discovery: Some tools only activate when the full tools array is passed. Passing ["web_search"] alone returns a "web search is OFF" response. Passing all five tools together activates whichever tool the model decides is appropriate for the query.

Available Tools

ToolStandaloneFull ArrayNotes
weatherReturns temperature, humidity, wind, pressure
stockReal-time stock price by ticker symbol
web_searchReturns full search results with sources
web_extractExtract content from web pages
cryptocurrencyReal-time crypto prices across exchanges
proton_info?Likely Proton product documentation
generate_imageGenerate images from text prompts
describe_imageAnalyze and describe uploaded images
edit_imageEdit existing images with text instructions
python — native endpoint with tools
import requests, json

ALL_TOOLS = ["proton_info", "web_search", "web_extract", "weather", "stock", "cryptocurrency",
             "generate_image", "describe_image", "edit_image"]

payload = {
    "Prompt": {
        "type": "generation_request",
        "turns": [
            {"role": "user", "content": "What is the weather in Geneva today?",
             "images": [], "encrypted": True}
        ],
        "options": {"tools": ALL_TOOLS},
        "targets": ["message"]
    }
}

r = requests.post(
    "https://lumo.proton.me/api/ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
    json=payload, timeout=60, stream=True
)

message = ""
for raw in r.iter_lines():
    if not raw: continue
    line = raw.decode("utf-8").strip()
    if not line.startswith("data:"): continue
    try:
        chunk = json.loads(line[5:])
        if chunk.get("type") == "token_data" and chunk.get("target") == "message":
            message += chunk.get("content", "")
    except: continue

print(message.strip())

Stream Event Types

typetargetDescription
queuedRequest received by server
ingestingProcessing started. Contains job_id and model_name
token_datareasoningInternal thinking discard
token_datamessageResponse to display to user
token_datatitleAuto-generated conversation title
tool_callTool invoked. content is JSON with name and arguments
tool_resultTool response. content is JSON with real-time data
Known Issues

Limitations & Not Yet Working

The API is in early access. The frontend documentation config is ahead of what is actually deployed on the backend.

⚠️
No end-to-end encryption via API. The web interface encrypts message content client-side before sending. API calls use plain text over HTTPS only content is visible to Proton's backend infrastructure. The encrypted field is accepted for both values but ignored, some progress here looks good.
🪢
Stream parameter is now required. Omitting it returns a 400 error. Setting "stream": false now works correctly and returns a clean application/json response instead of SSE no chunk reassembly needed. Setting "stream": true returns text/event-stream as expected. Previously this parameter was ignored and SSE was always forced.
📄
Official docs published. but remains hidden from the majority of users...
🥶
Temperature is ignored. Values from -1.0 to 20.0 all return 200 with no validation error. Responses are identical regardless of the value passed. No observable effect on output determinism or randomness.

Lumo API Tracker — community tested · not affiliated with Proton · Live API

▶ STATUS BOARD
Status Board
LUMO API · DEPARTURES
LM-001Model Selection--DELAYED
LM-002Encrypted Field02LANDED
LM-003Web Search / Weather03LIVE
LM-004Image Generation04LIVE▲ Changed 2026-07-10 13:45:22

LM-007 PGP Encryption 07 BOARDING
LM-008max_tokens param08DELAYED
LM-009temperature param09DELAYED
--:--:--
LAST CHECK2026-07-26 16:59:01
TOTAL CHECKS499
CHECK INTERVAL1H