API setup

Connect Luma Cloud as an OpenAI-compatible provider.

Use one public endpoint, one bearer key, and canonical model ids across CLI agents, IDEs, and SDK clients. SuperCodex subscription quota and standalone metered API usage are separate ledgers.

Open API keys

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

API key env

LUMA_CLOUD_API_KEY

Default model

gpt-5.5-xhigh

First smoke model

gpt-5.5-medium

Metered path

API is not just Builder renamed.

Builder includes external API keys against a subscription quota. Standalone API access is a separate metered account path for token spend.

Current benchmark

$0.25 / 1M input, $1.50 / 1M output

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.

Get a Luma key

Open App -> API. Builder workspaces can create external API keys for their own agents and tools. Standalone API users receive keys on the metered API account path.

Use the /v1 endpoint

Set the provider base URL to https://api.lumaos.cloud/v1. Do not paste bridge, shard, VPS, or localhost OmniRoute URLs into customer tools.

Start with the smoke model

Run the first request with gpt-5.5-medium; switch the default to gpt-5.5-xhigh after streaming and quota state are confirmed.

Read the right ledger

Subscription traffic burns plan quota. Standalone API traffic burns metered API balance and is settled separately from Plus/Pro/Builder checkout.

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

SuperCodex-only subscription quota. No self-service external API keys.

Pro

3x Plus quota for heavier SuperCodex work. External API keys still start at Builder.

Builder

$49/mo, 5x Plus quota for SuperCodex plus self-service external API keys for the user's own CLI agents and tools.

Metered API

Separate API account path. Requests are priced by token usage, not by a fixed subscription window.

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-xhigh"

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

Dashboard installer first; manual opencode.json fallback when custom-provider metadata is missing.

OpenClaw

Use the public endpoint, workspace key, and 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.

Provider adoption