Workspace setup
Luma Cloud setup, SuperCodex installer, and API clients.
Use SuperCodex for the managed coding-agent product. Use the OpenAI-compatible API for Builder external keys or standalone metered API accounts. Both paths share public model ids, request ids, and quota/usage ledgers.
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
Context window 400,000 tokens; default output limit 1,024 tokens per request in provider configs.
Workspace access key
Sign in to `/app` and copy the included starter key for the current workspace.
Runtime endpoints
The public gateway is the API compatibility boundary.
These routes power SuperCodex, Builder external keys, and standalone metered API accounts. Customers should only see the branded /v1 endpoint and request-id support flow.
/healthz
Minimal public readiness probe. Internal routing and key details stay operator-only.
/v1/models
OpenAI-compatible model discovery limited to aliases 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 copy-safe model id; the gateway accepts friendly variants.
For OpenCode, SDKs, and direct calls, put the canonical id below into the `model` field. Human spellings such as `GPT-5.5X High` are normalized server-side, but the dashed lowercase value is the safest format.
gpt-5.5
Default GPT-5.5 route; the gateway sends it to the xHigh preset unless a more specific model is selected.
Also accepted
cx/gpt-5.5, codex/gpt-5.5
gpt-5.5-xhigh
Best default for deep agent and reasoning work.
Also accepted
GPT-5.5X High, gpt-5.5 x high, cx/gpt-5.5-xhigh
gpt-5.5-high
Strong reasoning when xHigh is more than the task needs.
Also accepted
GPT-5.5 High, cx/gpt-5.5-high
gpt-5.5-medium
Balanced mixed work and everyday automation.
Also accepted
GPT-5.5 Medium, cx/gpt-5.5-medium
gpt-5.5-low
Fast control loops, previews, and light tasks.
Also accepted
GPT-5.5 Low, cx/gpt-5.5-low
Model catalog
The public model catalog is the source of truth for model ids.
`GET /v1/models` returns copy-safe canonical ids allowed by the calling key. `cx/...`, `codex/...`, case changes, spaces, and `GPT-5.5X High` style inputs are accepted as aliases but are not the primary list.
gpt-5.5
Default GPT-5.5 route for deep Codex-style agent and reasoning work.
Accepted aliases
cx/gpt-5.5, codex/gpt-5.5, gpt-5-codex, codex/gpt-5-codex, cx/gpt-5-codex, gpt-5, codex/gpt-5, cx/gpt-5, gpt-5.1, gpt-5.1-codex, gpt-5.3-codex-spark, cx/gpt-5.3-codex-spark, codex/gpt-5.3-codex-spark, gpt-5.3-codex, cx/gpt-5.3-codex, codex/gpt-5.3-codex, gpt-5.2, cx/gpt-5.2, codex/gpt-5.2
Metered price
$0.50 / 1M input, $3.00 / 1M output
gpt-5.5-xhigh
Copy-safe flagship model id for the highest GPT-5.5 reasoning preset.
Accepted aliases
cx/gpt-5.5-xhigh, codex/gpt-5.5-xhigh
Metered price
$0.50 / 1M input, $3.00 / 1M output
gpt-5.5-high
Strong GPT-5.5 reasoning preset for complex work when xHigh is more than needed.
Accepted aliases
cx/gpt-5.5-high, codex/gpt-5.5-high
Metered price
$0.50 / 1M input, $3.00 / 1M output
gpt-5.5-medium
Balanced GPT-5.5 preset for everyday automation and mixed product traffic.
Accepted aliases
cx/gpt-5.5-medium, codex/gpt-5.5-medium
Metered price
$0.50 / 1M input, $3.00 / 1M output
gpt-5.5-low
Fast GPT-5.5 preset for previews, light tasks, and thin control loops.
Accepted aliases
cx/gpt-5.5-low, codex/gpt-5.5-low
Metered price
$0.50 / 1M input, $3.00 / 1M output
Plans and stops
Quota, spend, and stop reasons are explicit in the local build.
The gateway enforces plan-aware rate limits, weekly subscription quota for Plus/Pro/Builder traffic, and balance or spend-cap checks for standalone metered API coverage.
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-xhigh. 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.
Default model
Copy-safe model id for the OpenCode model field.
SDK snippets
Use the branded base URL for private Luma clients.
The public API supports the Responses path used by SuperCodex, plus chat completions as a fallback. 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)