> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI providers and model configuration

> Configure AI providers and assign default and fallback models per workspace type for text generation, image understanding, embeddings, and document processing.

## Overview

FlowX supports configuring AI providers at three levels:

* **Organization level**: Add and manage AI providers, set API keys, whitelist specific models
* **Organization level (per workspace type)**: Assign default and fallback models for each AI capability, scoped by workspace type (Sandbox, Staging, Production)
* **Node level**: Override the default model on individual workflow nodes

Organization admins define which providers and models are available, and configure model assignments per workspace type. Workflow designers can optionally override the model on individual AI nodes.

***

## Organization-level: Model providers

Access model providers from **Organization Settings** → **AI Settings** → **Model Providers**.

![Model Providers page in Organization Settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_org_settings.png)

An **OpenAI** provider card is present by default, using a FlowX-managed key. You can switch it to your own key or add additional providers.

### Adding a provider

**1. Navigate to Model Providers**

In FlowX Designer, go to your organization settings and select **Model Providers**.

**2. Add a provider**

Click the **+** button to open the **Provider Details** dialog. Configure:

| Field | Description |
| - | - |
| **Provider** | Select from the provider catalog (e.g., OpenAI) |
| **Base URL** | API endpoint (required). OpenAI offers presets (Global, EU, US) or select **Custom URL** to enter any OpenAI-compatible endpoint. |
| **API Key Source** | Select **Own** to provide your own API key, or **FlowX** to use the FlowX-provided API key |
| **Key** | Your provider API key (required, shown when **Own** is selected) |
| **Organization ID** | Provider organization ID (optional) |

> [!NOTE]
>
> You cannot add the same provider type twice. The system validates against the provider catalog and shows an error if a duplicate is attempted.

**3. Test the connection**

Click **Test Connection** to validate your credentials against the provider API.

* **Success:** "Connection successful. X models discovered."
* **Failure:** Error details are shown (e.g., invalid API key for 401, insufficient permissions for 403).

You cannot save the provider configuration until the connection test succeeds.

**4. Enable models**

After saving, click **Manage** to choose the models this provider offers. For a provider with a discovered model list, **Manage** opens the model whitelisting modal: enable specific models from the list. Only enabled models appear in workspace-type assignments (Sandbox, Staging, Production). For Azure OpenAI and Custom providers, **Manage** opens a list where you add your deployment models by hand instead, see [Manually configured models](#manually-configured-models).

### Custom URL endpoints

When you point the **OpenAI** provider at a **Custom URL**, such as an API gateway or proxy in your own network, FlowX sends every AI capability to that endpoint: text generation, image understanding, embeddings, and document processing. The endpoint must implement these OpenAI API operations, relative to the Base URL:

| Operation | Used for |
| - | - |
| `GET /models` | **Test Connection**. You can't save the provider until this call succeeds. |
| `POST /responses` | Text generation and image understanding (the OpenAI Responses API) |
| `POST /embeddings` | Knowledge base indexing and retrieval |
| `POST /chat/completions` | Document parsing with an AI vision model |

* Include the `/v1` version segment in the Base URL, for example `https://gateway.example.com/v1`.
* The API key is sent as a bearer token (`Authorization: Bearer <key>`). The provider doesn't acquire or refresh OAuth tokens.
* Requests use the standard OpenAI model IDs from the provider's model list, for example `gpt-4.1` or `text-embedding-3-small`. The endpoint must accept these IDs, because you can't add custom model names to the OpenAI provider.

### API Key Source

The **API Key Source** radio buttons control how the provider authenticates:

| Option | Description |
| - | - |
| **Own** | Provide your own API Key. You have full control over the key, Organization ID, and which models are enabled. |
| **FlowX** | Use the FlowX-provided API key. The Key and Organization ID fields are hidden and cannot be edited. |

When editing the OpenAI provider, switch between **Own** and **FlowX** under API Key Source.

### Model whitelisting

The **Models Whitelist** modal (opened from **Manage**) lets you control which discovered models are available downstream. It lists every discovered model as a single checkbox list. Capabilities you may see on a model include:

| Category | Description |
| - | - |
| **Text Generation** | Text responses, summaries, translations, extraction |
| **Code Generation** | Automated code generation for Developer Agents |
| **Embeddings** | Vector representations for knowledge base indexing and RAG |
| **Audio Capabilities** | Audio transcription for the Speech to Text workflow node |

Each model row shows the model name and up to three of its capabilities, or the model ID when the provider reports no capabilities.

* Use **Search** to filter models by name, model ID, or capability
* Use **Select All** / **Deselect All** for bulk actions
* The footer shows **Models enabled: X / Y**
* Click **Save Whitelist** to persist your selection

> [!WARNING]
>
> What happens to the assignments that use a model you disable depends on the deployment:
>
> * **Self-hosted FlowX.AI 6.0:** a default or fallback set to that model in **Defaults & Fallbacks** keeps using it. Reassign them before you disable the model.
> * **SaaS:** an assignment whose model is disabled switches to its fallback model. If the fallback is disabled too, the model resolves as if that assignment didn't exist. An Agentic Harness model slot in the same situation stays empty.
>
> Self-hosted deployments get the SaaS behavior with the next LTS release.

> [!NOTE]
>
> Model whitelisting is not available when using the FlowX-managed key for OpenAI.

### Manually configured models

Azure OpenAI and [Custom](#custom-provider-self-hosted-endpoints) providers have no discovered model list, so **Manage** opens the provider's **Models** modal (**Manually configure deployment models**) instead of the whitelist. You register each model your deployment serves.

The list shows each model's display name, deployment name, context window, capabilities, whether it's a reasoning model, and the capabilities it's the default for. Click **Edit** or the delete icon on a model to change or remove it, and **Add Model** to register a new one:

| Field | Description |
| - | - |
| **Deployment Name** | Required. The deployment or model ID your endpoint expects, for example `gpt-4o-my-deployment`. |
| **Display Name** | Required. The name shown in FlowX, for example `GPT-4o`. |
| **Capabilities** | Required. One or more capabilities the model supports. |
| **Default for Capabilities** | Optional. Makes this model the provider's default for some of its selected capabilities. A capability that another model in the list already claims can't be selected. |
| **Reasoning model** | Turn on for reasoning models. |
| **Context Window** | Optional, for example `128k`. |
| **Dimensions** | Required when **Embeddings** is selected. The number of dimensions of the model's embeddings, a positive whole number, for example `384`. |

### Editing a provider

When editing an existing provider (API key or Organization ID changed):

1. The **Save** button is disabled after any field edit
2. Click **Test Connection** to validate the new credentials
3. On success, **Save** becomes enabled
4. If the newly discovered model list differs from the previous one:
   * New models are added to the whitelist automatically
   * If any previously enabled models are no longer available, a replacement wizard guides you through selecting alternatives
   * Skipping the wizard removes the missing models from all dropdowns where they were used, and the fallback mechanism activates

### Deleting a provider

All providers except the default OpenAI (FlowX-managed) can be deleted. Deleting a provider:

1. Shows a confirmation with the impact: nodes and knowledge bases using this provider's models switch to their fallback model
2. If the fallback model is also from the deleted provider, a warning indicates that all LLM-related activities using those models will fail

### Provider card

Each provider card shows:

* Provider name and icon
* Masked API key (last 4 characters visible, e.g., `••••••••••••1234`)
* Model count: "Models enabled: X / Y"
* Organization ID (if configured)
* Connection status
* Available actions: **Manage**, **Edit**, **Delete**

***

## Defaults & Fallbacks

Access model assignments from **Organization Settings** → **AI Settings** → **Defaults & Fallbacks**.

![Defaults & Fallbacks configuration with workspace-type tabs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/6.x-defaults-and-fallbacks.png)

Organization admins assign a **Default Model** and an optional **Fallback Model** for each AI capability, scoped by **workspace type**. Use the **Sandbox**, **Staging**, and **Production** tabs to configure different model assignments per environment. Select **Use provider default** to inherit the catalog default for that capability.

| Capability | Used for |
| - | - |
| **Text Generation** | Text operations (summarization, translation, extraction), data operations (enrichment, generation, transformation), custom agents, and intent classification |
| **Image Understanding** | AI image nodes — image description and image analysis. Only models with vision capability are shown. |
| **Embeddings** | Knowledge base indexing and context retrieval (RAG). Used by context retrieval nodes in workflows. |
| **Document / OCR** | AI document nodes — document generation, extraction, understanding, and text extraction from documents. |
| **Audio Capabilities** | Speech-to-text transcription. Used by the Speech to Text workflow node. |

The [Developer Agentic Harness](https://docs.flowx.ai/6.x/ai-platform/developer-agentic-harness.md) does not use these assignments. Its models are set on the **Agentic Harness** page under **AI Settings**, in the **Models** tab. See [Configure the harness for your organization](https://docs.flowx.ai/6.x/ai-platform/developer-agentic-harness.md#how-do-i-configure-the-harness-for-my-organization).

Default models from the OpenAI FlowX key are pre-assigned for each capability.

> [!WARNING]
>
> For **Embeddings**, assign OpenAI `text-embedding-3-small` or a local embedding model on a [Custom provider](#custom-provider-self-hosted-endpoints). Embedding models from other providers, such as **Mistral Embed** from the Mistral BYOK provider, can appear in the model list, but Knowledge Base indexing doesn't support them.

### Assigning models

For each capability:

1. Select a **Default model** from org-whitelisted models matching that capability, or use the **provider default**
2. Optionally select a **Fallback model**, used if the default model is unavailable or rate-limited

Assignments are configured per workspace type (Sandbox, Staging, Production). All workspaces of a given type inherit the same model assignments.

> [!WARNING]
>
> If the default and fallback models use the same provider, a warning is displayed. Using different providers for default and fallback improves resilience against provider outages.

> [!NOTE]
>
> When **Use provider default** is selected, the assignment inherits the catalog default model. Changes to the catalog default automatically propagate.

***

## Fallback behavior

When a primary model is unavailable, rate-limited, or disabled at the organization level, the system automatically switches to the configured fallback model. The resolution order is:

1. **Node-level override** (if configured) → its fallback model
2. **Workspace default** → its fallback model
3. **Error** if all options exhausted

| Scenario | Behavior |
| - | - |
| Primary model unavailable | Fallback model is used automatically |
| Node override model not found | Falls back to workspace default model |
| API key expired or revoked | Nodes using this provider's models fail with "API key invalid" in the execution log. Provider shows a warning at the organization level. |
| Both primary and fallback unavailable | The node retries automatically, by default up to 10 times, 30 seconds apart. After the last retry, the workflow continues down the node's failure exit if one is connected; otherwise the run fails. See [AI node retries](https://docs.flowx.ai/6.x/ai-platform/agent-builder/node-types.md#what-happens-after-the-last-retry). |

***

## Per-node model override

Workflow designers can override the default model on individual AI nodes (Custom Agent, Intent Classification Agent, etc.) in the Integration Designer. This allows different nodes in the same workflow to use different models. For example, a fast model for intent classification and a more capable model for complex reasoning.

![Per-node model override in Integration Designer workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/node_level.png)

### How it works

When configuring an AI node, an optional **Model Override** section lets you select a specific model:

| Field | Description |
| - | - |
| **Provider type** | The provider to use (e.g., `OPENAI`) |
| **Model** | The specific model |
| **Fallback provider type** | Optional fallback provider if the primary is unavailable |
| **Fallback model** | Optional fallback model |

The override uses portable identifiers (`providerType` + `modelIdStr`) that resolve at runtime against the organization's available models. Only models enabled in the organization's whitelist can be selected.

When no override is set, the node uses the workspace default model for its capability (text generation, embeddings, etc.).

> [!NOTE]
>
> Per-node model overrides apply to the **text generation** capability only. Other capabilities (image understanding, embeddings, document/OCR) always use the workspace defaults.

***

## Supported providers

FlowX maintains a provider catalog with pre-configured provider types. Each provider type includes display metadata (name, icon) and optional base URL presets.

| Provider | Key mode | Notes |
| - | - | - |
| **OpenAI** | FlowX Managed or BYOK | EU, US, and Global base URL presets |
| **Azure OpenAI** | BYOK | Custom endpoint (your Azure deployment URL); uses an `api-key` header and requires an `api-version` query parameter. East US and West Europe presets |

**Mistral** is also available as a BYOK provider: add it with your own Mistral API key, then enable models from the seeded catalog. Mistral models cover chat, image understanding, embeddings, and document OCR (the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed lines). Mistral Embed isn't supported for Knowledge Base indexing: see [Defaults & Fallbacks](#defaults-&-fallbacks).

### Custom provider (self-hosted endpoints)

The **Custom** provider type connects FlowX to any self-hosted, OpenAI-compatible endpoint, for example a local text-embeddings server or an Ollama instance. It is designed for organizations that need embedding models to run on their own infrastructure so that sensitive content never leaves it.

A Custom provider differs from catalog providers:

* **Free-form Base URL**: point it at any OpenAI-compatible endpoint. No presets.
* **BYOK only**: there is no FlowX-managed key option.
* **No seeded model catalog**: you register models manually, with the model ID, its capability (embeddings), and the embedding dimensions.

Embedding models registered on a Custom provider appear as **local embedding models** in Knowledge Base configuration. A Knowledge Base with **Containing Personal Information** turned on is indexed with a local embedding model instead of the cloud default, so its content is never sent to an external embedding provider. See [Containing personal information](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview.md#containing-personal-information) in the Knowledge Base documentation.

***

## Permissions

| Permission | Description |
| - | - |
| `org_ai_providers_read` | View AI providers and model assignments at organization level |
| `org_ai_providers_edit` | Add, edit, delete providers, manage model whitelists, and configure Defaults & Fallbacks |

***

## Related resources

> [card] [AI in FlowX](https://docs.flowx.ai/6.x/ai-platform/ai-in-flowx.md)
>
> Overview of AI capabilities in the FlowX platform

> [card] [Agent Builder](https://docs.flowx.ai/6.x/ai-platform/agent-builder/overview.md)
>
> Build AI agents that use the configured models

> [card] [Chat-driven workflows](https://docs.flowx.ai/6.x/ai-platform/chat-driven-workflows.md)
>
> Create chat experiences powered by AI models

> [card] [Organization Settings](https://docs.flowx.ai/6.x/docs/saas/organization-settings.md)
>
> Manage organization-level settings


## Related topics

- [AI Platform setup](https://docs.flowx.ai/6.x/setup-guides/ai-platform-setup.md)
- [FlowX.AI 5.7.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/v5.7.0-april-2026.md)
- [Speech to Text setup](https://docs.flowx.ai/6.x/setup-guides/speech-to-text-setup.md)
- [Web Crawler setup](https://docs.flowx.ai/6.x/setup-guides/web-crawler-setup.md)
- [Document Parser setup](https://docs.flowx.ai/6.x/setup-guides/document-parser-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.