# Any OpenAI-compatible client + Luma Cloud

Connect another editor, agent or app that accepts a custom OpenAI API URL and key.

API connection: Check client requirements. Instructions checked: 2026-09-28. Client capabilities and versions may vary; follow the verification steps below.

This is an API setup guide. SuperGPT desktop installation and sign-in are separate; use a customer API key for the client described here.

## Before you start

- A client with a documented custom Base URL, API-key field and model selector. A model selector alone is not sufficient.

- A Luma Cloud API key from Dashboard → API, with Wallet funds or an eligible subscription key. SuperGPT desktop sign-in is separate.

- An exact model ID from GET /models using that key, and a client protocol matching Chat Completions or Responses.

## Setup

1. **Check the client's provider options**
   Open Settings → Models, Providers or Connections. Look for OpenAI Compatible, Custom OpenAI or a configurable OpenAI endpoint. If it only accepts a vendor login or an Anthropic/Gemini endpoint, use one of the supported clients in this directory instead; changing a URL cannot translate the protocol.

2. **Add a separate connection**
   Name it Luma Cloud. Keep existing providers and the current default until the new connection is verified. In a config file, merge only the new provider entry; do not replace the whole file. Use the client's own documentation for its schema and file location.

3. **Set the URL and credentials**
   Use https://api.lumaos.cloud/v1 for a Base URL field. Enter your key in the client's secure credential field. If it asks for a full Chat Completions endpoint instead, use https://api.lumaos.cloud/v1/chat/completions. A header-based connector needs Authorization: Bearer followed by the actual key and Content-Type: application/json.

4. **Choose the protocol and model**
   Start with Chat Completions unless the client specifically requires Responses. Paste an exact model ID returned for your key. Do not add an OpenAI or Luma prefix unless that client's guide explicitly requires one. Only enable tools, vision or other optional features after checking both model and client support.

5. **Save and select the connection**
   Reload the client if its documentation requires it. Select Luma Cloud and the intended model in the chat or agent itself; saving a provider does not always select it. A GUI app opened from the Dock or Start menu may not inherit variables set in a terminal.

## Connection fields

- Provider: OpenAI Compatible / Custom OpenAI

- Base URL: https://api.lumaos.cloud/v1

- API key: Your key from Dashboard → API, stored in the client's secure field

- Model ID: MODEL_ID_FROM_CATALOG

## macOS / Linux: private terminal variables

```sh
# macOS / Linux: enter the key when prompted, not in the command itself.
read -r -s LUMA_CLOUD_API_KEY
export LUMA_CLOUD_API_KEY
export LUMA_CLOUD_BASE_URL="https://api.lumaos.cloud/v1"
# Replace the value below with an ID returned for your key.
export LUMA_CLOUD_MODEL="MODEL_ID_FROM_CATALOG"
```

Enter the key at the hidden prompt. Replace the model placeholder after listing available models. These variables only last in this terminal session.

## List models for your key

```sh
curl --fail-with-body "https://api.lumaos.cloud/v1/models" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY"
```



## Check Chat Completions

```sh
curl --fail-with-body -N "https://api.lumaos.cloud/v1/chat/completions" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "messages": [{"role": "user", "content": "Reply with hello."}],
  "stream": true
}
JSON
```

Run after setting a returned model ID. This request uses funds or quota.

## Windows PowerShell 7: private terminal variables

```powershell
$env:LUMA_CLOUD_API_KEY = Read-Host "Luma Cloud API key" -MaskInput
$env:LUMA_CLOUD_BASE_URL = "https://api.lumaos.cloud/v1"
$env:LUMA_CLOUD_MODEL = "MODEL_ID_FROM_CATALOG"
```



## Windows: list models and make a short request

```powershell
$headers = @{ Authorization = "Bearer $env:LUMA_CLOUD_API_KEY" }
$models = Invoke-RestMethod "$env:LUMA_CLOUD_BASE_URL/models" -Headers $headers
$models.data | Select-Object id

$env:LUMA_CLOUD_MODEL = Read-Host "Model ID from the list above"
$body = @{
  model = $env:LUMA_CLOUD_MODEL
  messages = @(@{ role = "user"; content = "Reply with hello." })
  stream = $false
} | ConvertTo-Json -Depth 5
$result = Invoke-RestMethod "$env:LUMA_CLOUD_BASE_URL/chat/completions" -Method Post -Headers $headers -ContentType "application/json" -Body $body
$result.choices[0].message.content
```

Run the model-list part first, set the selected ID, then run the request part. The request uses funds or quota.

## Responses, when required by your client

```sh
curl --fail-with-body -N "https://api.lumaos.cloud/v1/responses" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "input": "Reply with hello.",
  "stream": true
}
JSON
```

Use a model that supports this protocol. This is an alternative request, not an extra required setup step.

## Verify

- List models with the intended key. This confirms catalog access, not a completed model response.

- Send a short message in the client and wait for the complete response. Check Usage → API Wallet for a Wallet key, or subscription Usage for a subscription key.

- For agent tools, ask the client to list files in a disposable folder without editing or running commands. Confirm that a real tool result returns before enabling broader actions.

## Limits

- Custom API support is a client feature; not every IDE, agent mode or cloud task accepts a third-party provider.

- Chat compatibility does not promise autocomplete, embeddings, image generation, audio, hosted assistants or every agent tool.

- A universal config file would not work across different clients. Use the exact per-client guide when available.

## Troubleshooting

### No custom URL field

Check the guide for your exact app and version. A compatible extension may work even when the IDE's built-in assistant cannot. Do not put a Luma key into an unrelated vendor login field.

### 401 or missing key

Confirm the actual API key is stored in the client. A literal LUMA_CLOUD_API_KEY or ${...} string only resolves where documented. Re-enter the key privately and restart the client if its secret store requires it.

### 404, unknown model or wrong endpoint

Check for duplicated /v1 or /chat/completions in the resulting URL, choose the correct protocol and copy an exact ID from your key's model list.

### 402 or 429

Check the key type, Wallet balance and relevant subscription allowance. For 429 follow Retry-After when present and lower parallel requests; do not repeatedly resend the same request in a tight loop.

### Chat works but tools fail

Check that the client sends tool definitions and that the selected model supports them. Start with one read-only tool. Autocomplete, embeddings and vision may use separate models and credentials.

### Terminal works, GUI does not

Use the app's credential field or documented secret file. Restart the app after configuration changes and check which connection is selected in the current conversation.

## Official client documentation

- [Continue: OpenAI-compatible configuration](https://docs.continue.dev/customize/model-providers/top-level/openai)

- [OpenCode: custom providers](https://opencode.ai/docs/providers/)