Workspace setup
Luma Cloud setup, SuperCodex installer, and API clients.
Use SuperCodex for the managed coding-agent product. Use Builder keys against subscription quota, or create any number of named API Wallet keys against one prepaid balance. Both paths share public model ids and request ids, while billing stays separate.
SuperCodex installer
Install from the dashboard, understand the macOS and Windows prompts, and collect the right logs when support needs them.
External API keys
Use the /v1 endpoint from your dashboard with a Luma key in OpenAI-compatible CLIs, IDEs, and SDK clients.
Native provider listings
Manual setup works today. Provider catalog submissions are tracked separately with conformance and support gates.
Connection defaults
Everything a client needs to make the first request.
Base URL
https://api.lumaos.cloud/v1
Health URL
https://api.lumaos.cloud/healthz
Authentication
Send the key as Authorization: Bearer <key>. The recommended env variable is LUMA_CLOUD_API_KEY.
Request id header
Every response carries x-lumacloud-request-id; quote it in support requests.
Client timeouts
Recommended request timeout 600s and streaming chunk timeout 300s for long reasoning runs.
Published limits
GPT-5.5 uses 272,000 context tokens; GPT-5.6 families use 372,000. The requested output cap is at most 128,000 tokens.
API key
Open App → API, fund the API wallet when needed, and explicitly create a key. The secret is shown once.
Runtime endpoints
The public gateway is the API compatibility boundary.
These routes power SuperCodex, Builder external keys, and API Wallet keys. Customers should only see the branded /v1 endpoint and request-id support flow.
/healthz
Stateless process liveness. A 200 response does not mean Postgres or model capacity is ready.
/readyz
Deployment readiness: Postgres plus the fresh, signed exact-model capacity projection must both pass.
/v1/models
Authoritative model discovery limited to exact canonical ids enabled for the calling key.
/v1/responses
Responses-compatible product path for SuperCodex, with Luma key auth and usage writes.
/v1/responses/compact
Compaction path for Codex-style clients; real SuperCodex payload coverage is still being hardened.
/v1/chat/completions
Standard chat completions with quota checks and per-request usage accounting.
/v1/diagnostics/echo
Low-cost connectivity check for provider setup. It validates auth, key state, account state, and model access without reserving quota or billing usage.
Model field
Use one exact copy-safe model id.
For OpenCode, SDKs, and direct calls, put the exact lowercase canonical id below into the `model` field. Display labels, spaces, case variants, provider prefixes, and legacy ids are rejected before routing.
gpt-5.5
GPT-5.5 family id; when effort is omitted the gateway dispatches exact medium.
gpt-5.5-xhigh
Best explicit preset for deep agent and reasoning work.
gpt-5.5-high
Strong reasoning when xHigh is more than the task needs.
gpt-5.5-medium
Balanced mixed work and everyday automation.
gpt-5.5-low
Fast control loops, previews, and light tasks.
Model catalog
Authenticated GET /v1/models is the runtime source of truth.
The cards below are the maximum stock candidate universe. Only exact lowercase ids returned for your key right now are available; a failed candidate disappears instead of being mapped to another model.
gpt-5.5
GPT-5.5 with medium as the default reasoning effort.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write not published. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.5-low
GPT-5.5 Low reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write not published. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.5-medium
GPT-5.5 Medium reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write not published. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.5-high
GPT-5.5 High reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write not published. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.5-xhigh
GPT-5.5 xHigh reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write not published. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-sol
GPT-5.6 Sol with medium as the default reasoning effort.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-sol-low
GPT-5.6 Sol Low reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-sol-medium
GPT-5.6 Sol Medium reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-sol-high
GPT-5.6 Sol High reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-sol-xhigh
GPT-5.6 Sol xHigh reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-sol-max
GPT-5.6 Sol Max reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-sol-ultra
GPT-5.6 Sol Ultra reasoning preset.
Request identity
Canonical id only
Metered price
$0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-terra
GPT-5.6 Terra with medium as the default reasoning effort.
Request identity
Canonical id only
Metered price
$0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-terra-low
GPT-5.6 Terra Low reasoning preset.
Request identity
Canonical id only
Metered price
$0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-terra-medium
GPT-5.6 Terra Medium reasoning preset.
Request identity
Canonical id only
Metered price
$0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-terra-high
GPT-5.6 Terra High reasoning preset.
Request identity
Canonical id only
Metered price
$0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-terra-xhigh
GPT-5.6 Terra xHigh reasoning preset.
Request identity
Canonical id only
Metered price
$0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-terra-max
GPT-5.6 Terra Max reasoning preset.
Request identity
Canonical id only
Metered price
$0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-terra-ultra
GPT-5.6 Terra Ultra reasoning preset.
Request identity
Canonical id only
Metered price
$0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-luna
GPT-5.6 Luna with medium as the default reasoning effort.
Request identity
Canonical id only
Metered price
$0.10 input / $0.60 output per 1M tokens.
Cached input $0.01 / 1M; cache write $0.125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-luna-low
GPT-5.6 Luna Low reasoning preset.
Request identity
Canonical id only
Metered price
$0.10 input / $0.60 output per 1M tokens.
Cached input $0.01 / 1M; cache write $0.125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-luna-medium
GPT-5.6 Luna Medium reasoning preset.
Request identity
Canonical id only
Metered price
$0.10 input / $0.60 output per 1M tokens.
Cached input $0.01 / 1M; cache write $0.125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-luna-high
GPT-5.6 Luna High reasoning preset.
Request identity
Canonical id only
Metered price
$0.10 input / $0.60 output per 1M tokens.
Cached input $0.01 / 1M; cache write $0.125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-luna-xhigh
GPT-5.6 Luna xHigh reasoning preset.
Request identity
Canonical id only
Metered price
$0.10 input / $0.60 output per 1M tokens.
Cached input $0.01 / 1M; cache write $0.125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
gpt-5.6-luna-max
GPT-5.6 Luna Max reasoning preset.
Request identity
Canonical id only
Metered price
$0.10 input / $0.60 output per 1M tokens.
Cached input $0.01 / 1M; cache write $0.125 / 1M. Requests above 272K input apply 2× input and 1.5× output to the full request.
Plans and stops
Quota, spend, and stop reasons are explicit in the local build.
The gateway enforces plan-aware limits for subscription traffic and one shared account capacity and prepaid balance across every named API Wallet key.
Luma Cloud Plus
Plus tier: 1x SuperGPT quota with 150M raw-equivalent weekly tokens and 40M weighted weekly units.
Price: $10
Weekly quota: 150,000,000
Weighted cap: 40,000,000
Hard RPM / TPM: 600 / 2,000,000
Luma Cloud Pro
Pro tier: 3x Plus quota for heavier SuperGPT work. Self-service external API keys start at Builder.
Price: $24
Weekly quota: 450,000,000
Weighted cap: 120,000,000
Hard RPM / TPM: 600 / 2,000,000
Luma Cloud Builder
Builder tier: 5x Plus quota for SuperGPT plus up to 3 self-service external API keys for the user's own CLI agents and tools.
Price: $49
Weekly quota: 750,000,000
Weighted cap: 200,000,000
Hard RPM / TPM: 1,200 / 4,000,000
Error semantics
Gateway errors return `error.type`, `error.code`, `error.message`, `error.request_id`, `error.docs_url`, and safe details when available.
Key missing or invalid
Authentication errors use `type: authentication_error` and carry `request_id` for support.
Quota or balance exhausted
Billing and quota stops include safe details such as requested tokens, cap, or remaining balance.
Operator hold or frozen keys
Access stops map to `type: access_error`; operators see the corresponding audit and account state.
RPM or TPM gate
Rate-limit errors use the stricter of key limits and plan limits before routing.
OpenCode setup
Give normal users a click-by-click OpenCode setup path.
OpenCode should use provider id luma-cloud, endpoint https://api.lumaos.cloud/v1, and model gpt-5.5. Native catalog adoption is tracked separately from manual setup.
Provider name
Show this label in the OpenCode provider list.
Provider ID
Use the same lowercase id everywhere OpenCode asks for it.
Endpoint
Copy the /v1 endpoint from your dashboard; never paste internal or localhost URLs into customer tools.
Candidate default family
Use this base id only when authenticated GET /v1/models returns it; omitted effort resolves to medium.
SDK snippets
Use the branded base URL for private Luma clients.
The public API supports the Responses path used by SuperCodex alongside chat completions. Neither surface substitutes an unavailable model or effort. JSON responses include Luma Cloud telemetry and all successful requests write usage rows.
curl
Quickest smoke path.
curl https://api.lumaos.cloud/v1/chat/completions \
-H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5-xhigh",
"messages": [
{ "role": "user", "content": "Summarize the active Luma Cloud guardrails." }
],
"max_tokens": 180
}'Responses
SuperCodex-compatible smoke path.
curl https://api.lumaos.cloud/v1/responses \
-H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5-xhigh",
"input": [
{
"role": "user",
"content": [{ "type": "input_text", "text": "Confirm the Luma Cloud product contour." }]
}
],
"max_output_tokens": 180
}'TypeScript
OpenAI SDK-compatible `baseURL`.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.lumaos.cloud/v1",
apiKey: process.env.LUMA_CLOUD_API_KEY!
});
const response = await client.chat.completions.create({
model: "gpt-5.5-xhigh",
messages: [
{ role: "user", content: "Summarize the active Luma Cloud guardrails." }
],
max_tokens: 180
});
console.log(response.choices[0]?.message?.content);Python
Same base URL and key shape.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.lumaos.cloud/v1",
api_key=os.environ["LUMA_CLOUD_API_KEY"]
)
response = client.chat.completions.create(
model="gpt-5.5-xhigh",
messages=[
{"role": "user", "content": "Summarize the active Luma Cloud guardrails."}
],
max_tokens=180,
)
print(response.choices[0].message.content)