API setup
Connect Luma Cloud as an OpenAI-compatible provider.
Use one public endpoint and a named bearer key for each app, environment, or team. Builder subscription quota and API Wallet usage remain separate ledgers.
Connection fields
Copy these values into any OpenAI-compatible provider form.
Provider ID
luma-cloud
Display name
Luma Cloud
Provider type
OpenAI-compatible
Base URL
https://api.lumaos.cloud/v1
Health URL
https://api.lumaos.cloud/healthz
Readiness URL
https://api.lumaos.cloud/readyz
API key env
LUMA_CLOUD_API_KEY
Default model
gpt-5.5
First smoke model
gpt-5.5-medium
API is not just Builder renamed.
Builder includes up to three external keys against subscription quota. API Wallet is available independently on every account: create multiple named keys, all sharing one prepaid balance and account limit.
Pricing rule
Each family uses its own OpenAI standard token rate divided by 10. Effort changes token burn, not the per-token price.
Settlement mechanism
Use API balance/top-up ledger first; wire Stripe metered billing only after reconciliation and abuse caps are locked.
Flow
Four checks before giving a key to a client.
This keeps customer setup short while preserving the difference between product subscription quota and API token spend.
Create an API key
Use the /v1 endpoint
Start with the smoke model
Read the right ledger
Plan split
Subscriptions and API balance stay readable.
The public docs should not imply that Plus or Pro are generic resale API products. Builder starts external keys; standalone API is priced by actual token usage.
Plus
Pro
Builder
Metered API
Reasoning effort
Choose the family and effort; the Gateway preserves that exact public identity.
Base family ids default to medium. Chat Completions accepts reasoning_effort; Responses accepts reasoning.effort. Private provider qualification and capacity selection are intentionally not part of the customer contract.
Supported effort matrix
Model suffixes and effort fields express the same choice. Canonical ids stay public and provider-neutral.
gpt-5.5
low, medium, high, xhigh
Metered API: $0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write not published. Above 272K input, the full request is charged at 2× input and 1.5× output.
gpt-5.6-sol
low, medium, high, xhigh, max, ultra
Metered API: $0.50 input / $3.00 output per 1M tokens.
Cached input $0.05 / 1M; cache write $0.625 / 1M. Above 272K input, the full request is charged at 2× input and 1.5× output.
gpt-5.6-terra
low, medium, high, xhigh, max, ultra
Metered API: $0.25 input / $1.50 output per 1M tokens.
Cached input $0.025 / 1M; cache write $0.3125 / 1M. Above 272K input, the full request is charged at 2× input and 1.5× output.
gpt-5.6-luna
low, medium, high, xhigh, max
Metered API: $0.10 input / $0.60 output per 1M tokens.
Cached input $0.01 / 1M; cache write $0.125 / 1M. Above 272K input, the full request is charged at 2× input and 1.5× output.
Fail-closed resolution
A base id with no effort uses medium. An explicit suffix is authoritative. A suffix that conflicts with the body returns HTTP 400 before any provider request.
gpt-5.6-terra + xhigh resolves to the effective public id gpt-5.6-terra-xhigh.
gpt-5.6-terra-high + xhigh fails with reasoning_effort_conflict.
Clients select only public model ids and efforts. Private capacity classes, cells, accounts, proxies, and provider ids are never request parameters.
Chat Completions
Use the top-level reasoning_effort field.
curl https://api.lumaos.cloud/v1/chat/completions \
-H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"reasoning_effort": "xhigh",
"messages": [
{ "role": "user", "content": "Review this patch." }
],
"stream": true
}'Responses
Use the nested reasoning.effort field.
curl https://api.lumaos.cloud/v1/responses \
-H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"reasoning": { "effort": "ultra" },
"input": "Plan and implement the requested change.",
"stream": true
}'Copy blocks
Use the same shape in terminals and SDKs.
The key is secret; examples use environment variables. The base URL always ends at /v1, not at a specific completion route.
Environment
Recommended local shell shape.
export LUMA_CLOUD_API_KEY="lc_live_..."
export LUMA_CLOUD_BASE_URL="https://api.lumaos.cloud/v1"
export LUMA_CLOUD_MODEL="gpt-5.5"Streaming smoke
Use this before switching a client to xHigh by default.
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-medium",
"messages": [
{ "role": "user", "content": "Reply with one short sentence." }
],
"max_tokens": 80,
"stream": true
}'Client guides
Pick the smallest working path for each tool.
Native listings come later; these guides are the current customer-safe setup routes.
OpenCode
Create a key and use the Custom provider form. The optional secret-free config references LUMA_CLOUD_API_KEY.
OpenClaw
Use the public endpoint, an explicitly created API key, and a canonical model id.
Cursor
Use OpenAI-compatible/custom base URL fields when available.
Cline
OpenAI Compatible provider: base URL, key, model id.
Roo Code
Same OpenAI-compatible provider contract; verify tool-call streaming before claiming full tool support.
Continue / VS Code
Add an OpenAI-compatible model block and keep the key in a local secret or environment variable.
Zed
Add the endpoint and canonical model ids in assistant/provider settings.
SDKs
OpenAI SDK-compatible baseURL plus bearer key.
Provider submissions are gated.
Do not request native marketplace listings until public conformance, request-id support, and pricing copy are reviewed.