# Cherry Studio + Luma Cloud

Keep Luma Cloud in its own provider entry and choose its models in chat.

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.

- Cherry Studio with custom OpenAI providers.

## Setup

1. **Create a separate provider**
   Open Settings → Model Services → Add. Enter Luma Cloud as the name, select OpenAI as the provider type, and confirm Add. Keep any existing OpenAI provider entry.

2. **Fill in the connection**
   Select the new provider and enter your Luma key in API Key. Set API Address to https://api.lumaos.cloud/v1. Current versions recognize the existing /v1; a final slash is optional. If your version shows endpoint controls, select OpenAI Chat Completions for this guide and check that the URL preview ends in /v1/chat/completions.

3. **Add the models you want**
   Click Manage to fetch the model list, then click + beside a model to add it. For manual entry, use Add and enter the exact catalog ID as Model ID.

4. **Enable and select**
   Enable the provider switch. Return to chat, open a new conversation, and select the model under Luma Cloud in the model picker.

5. **Send a first message**
   Send “Reply with hello.” Use a text message without attachments for the first test.

## Connection fields

- Provider name: Luma Cloud

- Provider Type: OpenAI

- API Address: https://api.lumaos.cloud/v1

- API Key: Your Luma Cloud API key

- Model ID: MODEL_ID_FROM_CATALOG

- Provider switch: Enabled

## Verify

- Wait for a completed reply from the model selected under Luma Cloud.

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

- If the app returns 404, inspect the endpoint preview and confirm that the URL does not contain v1 twice. If the model is missing from chat, check that it was added in Manage and the provider is enabled.

## Limits

- Leave embeddings, image generation and speech on separately configured providers.

- Interface labels can vary by Cherry Studio version. The required values are the OpenAI provider type, API address, key and exact model ID.

- Keep the Luma Cloud credential inside its own provider entry. Changing an existing OpenAI entry would also change the connection used by its saved models.

## 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.

### 404 or the address contains v1 twice

Set API Address to https://api.lumaos.cloud/v1 and inspect the request URL preview if your version shows one. Current versions normalize a final slash and preserve the existing /v1. Do not paste a full /chat/completions path into this field; use the Chat Completions endpoint choice when available.

### The provider is visible, but the model is not

Enable the provider, add the exact model ID to its model list, and choose it under Luma Cloud in a new chat. A display label is not the model ID; Manage and the chat selector are separate steps.

### The selected chat uses the wrong provider

Open the model selector in that conversation and choose the model under Luma Cloud. Existing conversations or assistants can retain their previous selection even after you add a new provider.

### A file, tool or image request fails

Return to a plain text message. Enable extra features only when both the selected model and the Luma API support that operation. The OpenAI provider type alone does not imply every OpenAI feature is available.

### 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

- [Cherry Studio: custom provider](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/pre-basic/providers/zi-ding-yi-fu-wu-shang)

- [Cherry Studio: current API address handling](https://github.com/CherryHQ/cherry-studio/blob/main/src/shared/utils/api/format.ts)

- [Cherry Studio: endpoint URL previews](https://github.com/CherryHQ/cherry-studio/blob/main/src/renderer/pages/settings/ProviderSettings/hooks/providerSetting/buildHostEndpointPreviews.ts)