# Open WebUI + Luma Cloud

Chat with Luma Cloud through an OpenAI-compatible connection.

API connection: Chat Completions. 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

- Create a named key in Dashboard → API. Use API Wallet credit, or an eligible Builder subscription key.

- Copy an exact model ID from the catalog returned for this key. Replace MODEL_ID_FROM_CATALOG wherever it appears below.

- Use a separate named key for this app. Paste it only into the app's credential field; keep it out of chat prompts, screenshots, shared configuration and workflow exports.

- Administrator access to your own or a trusted Open WebUI installation.

## Setup

1. **Open connection settings**
   Open Settings → Admin → Connections. In Manage OpenAI API Connections, click + Add Connection. Keep your existing connections.

2. **Fill in the connection**
   Paste https://api.lumaos.cloud/v1 into URL and your Luma key into API Key. Under Advanced, leave Provider at Default.

3. **Limit the model list if needed**
   To show only selected models, enter each exact catalog ID in Model IDs and click +. Leave this list empty to use automatic discovery.

4. **Save and select**
   Click Save and make sure the connection is enabled. Open a new chat, then choose your Luma model in the model selector.

5. **Send your first message**
   Type “Reply with hello.” Start with text only; add files or tools after the basic connection works.

## Connection fields

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

- API Key: Your Luma Cloud API key

- Provider: Default

- Model IDs: Optional filter: MODEL_ID_FROM_CATALOG

- Connection: Enabled

## Verify

- Wait for a completed text reply. Verify Connection checks the model list; it does not send your test message.

- After the reply, open Dashboard → Usage. Check API Wallet for a wallet key, or subscription usage for a Builder subscription key.

- If background titles or suggestions fail, check that their configured model is available to this same key.

## Limits

- An administrator connection may be available to other users of that installation. Configure access before saving a personal key.

- This setup is for text chat. Document embeddings, image generation, speech and browser-direct connections need their own compatible setup; they are not enabled by adding this connection.

- Tools and background tasks can make additional model requests. Test one tool at a time after text chat succeeds, with a model that supports tool calling.

## Troubleshooting

### 401 or an invalid-key message

Confirm that the saved credential contains a Luma Cloud API key, without surrounding quotes, spaces or a Bearer prefix. Check that this key is still active in Dashboard → API. A dashboard password or another provider's key will not work.

### The connection saves, but no model appears

Enable the connection and reload the chat model selector. If you added a Model IDs filter, check the exact ID against the catalog for this key. An allowlist narrows discovery; it does not grant access to a model.

### 404 or connection check fails

Use https://api.lumaos.cloud/v1 as the connection URL, without /chat/completions. The app adds the API path. Check connectivity from the Open WebUI server or container, which may have different network access from your browser.

### Chat works, but titles, search or uploads fail

Check the model selected for background tasks. Turn off the failing extra feature and repeat a plain text chat. A chat connection does not configure an embedding model, document retrieval or an image-generation service.

### 429, a balance warning or an interrupted run

Read the error and check the usage associated with this key. A wallet key uses API Wallet funds; a Builder subscription key uses its eligible subscription quota. Pause retries, wait for the indicated reset or retry time, and reduce parallel requests. After a timeout, check the existing result before running a costly job again.

## Official client documentation

- [Open WebUI: OpenAI-compatible connections](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/)