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.
reasoning_effort validated — only "none" (fast) and "high" (~2-3x slower with thinking) accepted; invalid values return HTTP 422provider, finish_reason, usage.prompt_tokens_details.cached_tokens, and remaining_limits (lite/max/images)lumo-lite (fast) and lumo-max (reasoning); auto routes optimallyweather, stock, web_search, cryptocurrency, proton_infogenerate_image, describe_image, edit_image, web_search, web_extractremaining_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" }
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.
lumo-lite, lumo-max) with vision capabilities."none" (fast, no thinking) and "high" (slow, ~2-3x latency with thinking). Invalid values like "low", "medium" return HTTP 422.provider, finish_reason, and usage.prompt_tokens_details.cached_tokens.OpenCode Integration
Drop this config into your project's opencode.json to use the Lumo API directly from OpenCode. Lumo is auto detected.
{
"$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"
}
}
}
}
}
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.
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". |
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.
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)
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))
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
}
]
}
Redacted: I do not intend to disclose this method publicly prior to its official launch
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.
["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
| Tool | Standalone | Full Array | Notes |
|---|---|---|---|
weather | ✓ | ✓ | Returns temperature, humidity, wind, pressure |
stock | ✓ | ✓ | Real-time stock price by ticker symbol |
web_search | ✗ | ✓ | Returns full search results with sources |
web_extract | ✗ | ✓ | Extract content from web pages |
cryptocurrency | ✗ | ✓ | Real-time crypto prices across exchanges |
proton_info | ? | ✓ | Likely Proton product documentation |
generate_image | ✓ | ✓ | Generate images from text prompts |
describe_image | ✓ | ✓ | Analyze and describe uploaded images |
edit_image | ✓ | ✓ | Edit existing images with text instructions |
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
| type | target | Description |
|---|---|---|
queued | — | Request received by server |
ingesting | — | Processing started. Contains job_id and model_name |
token_data | reasoning | Internal thinking discard |
token_data | message | Response to display to user |
token_data | title | Auto-generated conversation title |
tool_call | — | Tool invoked. content is JSON with name and arguments |
tool_result | — | Tool response. content is JSON with real-time data |
Limitations & Not Yet Working
The API is in early access. The frontend documentation config is ahead of what is actually deployed on the backend.
encrypted field is accepted for both values but ignored, some progress here looks good."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.-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