Dify + Luma Cloud

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.
• Workspace owner or administrator access in Dify. Have the selected model's context and output limits available.

Get an API key and a model ID →

Set up Dify

1. Install the model provider

   Open Integrations → Model Provider and install the official OpenAI-API-compatible provider. In older layouts, Model Provider is under workspace Settings. Choose the model provider, not the similarly named extension that publishes Dify apps as an API.

2. Add the model

   Open the provider card and use Setup or Add Model. Choose model type LLM. Enter the exact catalog ID as Model Name; use a friendly Model display name such as Luma Cloud if desired. The display name does not change the ID sent to the API.

3. Set the connection and protocol

   Enter https://api.lumaos.cloud/v1 as API Base URL and your Luma key as API Key. Keep Completion mode at Chat. If the plugin exposes API Type, select Chat Completions API. If it exposes model name for API endpoint, leave it empty to use Model Name, or enter the same exact catalog ID.

4. Set only the capabilities you need

   Enter the selected model's published context size and an output limit within its allowance. Begin with text, without vision, tools, structured output or provider-specific extra settings. Leave optional sampling overrides unset where possible. Save the model; plugin validation can make a model request.

5. Create a small app test

   In your app, select this model in the LLM node. Set a fixed User message: Reply with hello. Run the node's preview first; if using a Chatflow, connect its text output to an Answer node so the reply reaches chat. Keep the test unpublished until it works.

6. Add the rest of the workflow

   After text succeeds, add one tool or retrieval step at a time. Use a separate embedding provider for knowledge indexing. Review retry and loop limits before sharing or scheduling an app.

Provider plugin

OpenAI-API-compatible

Model type

LLM

Model Name

MODEL_ID_FROM_CATALOG

API Base URL

https://api.lumaos.cloud/v1

API Key

Your Luma Cloud API key

Completion mode

Chat

API Type, when present

Chat Completions API

Model context size

The selected model's published context limit

Reply with hello.

Check the connection

1. Preview the LLM node and check for completed text output, not only a saved provider card.
2. In a Chatflow, confirm that the Answer node displays the LLM output to the user.
3. After the reply, open Dashboard → Usage. Check API Wallet for a wallet key, or subscription usage for a Builder subscription key.

For errors or a request that stops, see troubleshooting. A visible model list alone does not confirm that a chat or editing task can complete.

What to expect

• Providers and their credentials are shared across a Dify workspace. Requests made with this key use its Luma Cloud balance or quota, including other workspace members' app runs.
• The provider plugin supports several model types, but selecting it does not mean Luma Cloud supplies embeddings, reranking, speech or every optional API operation. This guide configures text generation only.
• Agent tools require a model that supports the required tool-call format. A feature toggle cannot add a missing model capability. Test tools separately from chat before publishing an agent.
• Field names and available protocol controls depend on the installed provider plugin version. If the plugin sends an unsupported parameter that it cannot disable, use the API quickstart or another compatible client.

Troubleshooting Dify