Skip to main content
The AI Models page is where workspace admins connect PipesHub to one or more AI providers. Once configured, these models power every AI feature in the platform — answering questions in chat, summarising documents, and running AI agents. You can connect as many providers as you need and switch between them at any time. You need at least one LLMs provider configured before any AI feature in your workspace will work. Embedding models are used for document search and are configured separately.

​
How to navigate to this page

Open the left sidebar → Workspace Settings → AI Models. The page opens on the Providers tab by default. Click the LLM tab to configure language models.
Only workspace admins and owners can access the AI Models settings page.

​
Add your first LLMs model

1

Open AI Models settings

Open the left sidebar → Workspace Settings → AI Models.
2

Go to the LLMs tab

The page opens on the Providers tab. Click the LLMs tab.
3

Find your provider

Browse the provider cards or use the search box to filter by name.
4

Open the configuration panel

Click Configure on the provider card. A configuration panel slides open.
5

Fill in the required fields

Enter the credentials required for your provider (API key, endpoint URL, etc.). See the provider reference below.
6

Set optional fields (if needed)

  • Model Friendly Name — a human-readable label shown in chat (e.g. “My GPT-5”). Optional.
  • Context Length — the model’s context window in tokens, from 1,024 to 20,000,000. Leave it empty and PipesHub assumes 128,000.
  • Multimodal toggle — enable if this model can accept image input. On by default.
  • Reasoning toggle — enable for chain-of-thought / o-series style models. On by default.
7

Save and validate

Click Add Model. PipesHub runs a live health check to validate your credentials.
8

First model becomes the default

If this is the first LLMs model you’ve added, it is automatically set as the default model used by all AI features.

​
Provider reference

The table below lists every supported LLMs provider, the fields you must fill in, and example model name strings.
Azure OpenAI — Deployment Name: This is the name you assigned when deploying the model in Azure AI Studio, not the model ID itself. Azure AI — Endpoint URL format: Use https://<resource>.inference.ai.azure.com/anthropic for Claude models, or https://<resource>.cognitiveservices.azure.com/openai/v1/ for OpenAI, DeepSeek, and other models. OpenAI Compatible: Use this for any provider that speaks the OpenAI API format (e.g. https://api.together.xyz/v1/). Ollama: No API key is required for a local Ollama instance. The endpoint defaults to http://host.docker.internal:11434. Ensure the Ollama server is reachable from the PipesHub Docker network. Amazon Bedrock: If PipesHub is running on an EC2 instance with an appropriate IAM role attached, you can leave the AWS Access Key ID and Secret Access Key blank.

​
Managing configured models

After saving, your model appears under the Configured tab. Each row has the following actions:
  • Edit — update credentials or settings without deleting the configuration.
  • Set as Default — make this model the one used by all AI features by default.
  • Delete — permanently remove the configuration. You will be asked to type the model’s name to confirm.

​
Troubleshooting

If the health check fails when you save a model, the dialog shows the check’s message word for word. The one exception is an embedding model refused because content is indexed with another model; see Changing the embedding model in use.
If the health check fails when saving, double-check:
  • The API key is correct and has not expired.
  • For Azure providers, the endpoint URL matches the correct region and resource.
  • For Ollama, the server is running and the Docker internal hostname resolves correctly.
  • The model name string exactly matches what the provider API expects (check the provider’s documentation for valid model IDs).

​
Health check error messages

These are the messages a chat model’s check returns. Embedding, image, speech and speech-to-text models get most of the same messages; the differences are in Health check messages for other model types. The provider refused the settings (400). The message names the setting to fix:
  • A rejected key: “The API key for <model name> was rejected by <provider>. Check the key in Workspace > AI Models, then try again.”
  • A missing model or a wrong endpoint path: “<provider> couldn’t find the model “<name>” at this endpoint. Check the model name (or deployment name) and the endpoint address in Workspace > AI Models, then try again.”
  • An unreachable endpoint: “Couldn’t reach <provider> at the endpoint in these settings. Check the endpoint address and that PipesHub can connect to it, then try again.”
  • Any other request the provider refused: “<provider> refused these chat model settings. Check the model name and its options (such as reasoning effort or context length), then try again.”
An endpoint this deployment won’t call (400). The health check tests the endpoint before every other check and before sending anything to the provider. It checks the endpoint’s text first, with no lookup:
  • An endpoint that isn’t an http or https URL: “Model endpoint ‘<endpoint>’ must be an http(s) URL.”
  • A link-local or cloud metadata IP address (such as 169.254.169.254), or the name metadata.google.internal: “Model endpoint ‘<endpoint>’ is a link-local or cloud metadata address, which is never allowed.”
  • Only when PIPESHUB_BLOCK_PRIVATE_ADDRESSES is on: a private IP address, localhost, a one-word service name, or a name ending in .internal, .local, .localhost or .svc (for example host.docker.internal): “Model endpoint ‘<endpoint>’ is a private or internal address, which this deployment does not allow (PIPESHUB_BLOCK_PRIVATE_ADDRESSES).”
A name that passes the text check is then looked up. If it resolves to a blocked address, the message says “resolves to”:
  • A link-local, unspecified or cloud metadata address: “Model endpoint ‘<endpoint>’ resolves to a link-local, unspecified or cloud metadata address, which is never allowed.”
  • Only when PIPESHUB_BLOCK_PRIVATE_ADDRESSES is on, a private address: “Model endpoint ‘<endpoint>’ resolves to a private or internal address, which this deployment does not allow (PIPESHUB_BLOCK_PRIVATE_ADDRESSES).”
If the lookup finds nothing, the check also fails with a 400:
  • No address for the name: “Model endpoint ‘<endpoint>’ does not resolve: no address was found for its host name.”
  • A temporary DNS failure: “Model endpoint ‘<endpoint>’ could not be checked: temporary DNS failure. Try again.”
A failed lookup is not refused when PipesHub reaches the endpoint through a proxy set in HTTP_PROXY or HTTPS_PROXY (and not excluded by NO_PROXY), because the name may resolve only on the proxy’s side. The Ollama address the deployment sets in OLLAMA_API_URL is exempt from the private-address check and is not looked up. Other checks made before or instead of asking the provider:
  • No model name (400): “No valid model names found in configuration”
  • A context length outside 1,024 to 20,000,000 tokens (400): “Context length <value> is not a usable window. Set it to the model’s context window in tokens (between 1,024 and 20,000,000), or leave it empty to assume 128,000.”
  • A default reasoning effort that isn’t a valid choice (400): “This model’s default reasoning effort is ‘<value>’, which isn’t a valid choice. Set it to low, medium, high or max, or remove it to use the platform default.”
  • PipesHub has no internet access for a cloud provider (500): “Cannot reach cloud LLM providers from PipesHub. The container may not have outbound internet access. Cloud LLMs and external connectors require container egress; air-gapped installs should use local models (Ollama, LM Studio). See deployment/docker-compose/ADVANCED_DEPLOYMENT.md#container-outbound-connectivity.”
  • The provider took too long (504): “LLM health check timed out. For cloud providers, verify your API key and that PipesHub containers can reach the internet. See deployment/docker-compose/ADVANCED_DEPLOYMENT.md#container-outbound-connectivity.” If the dialog’s own request times out before any response arrives, the dialog shows “Request timed out while validating the model. Cloud providers need outbound internet from the PipesHub container — see deployment/docker-compose/ADVANCED_DEPLOYMENT.md#container-outbound-connectivity.”
The provider answered, but the chat model failed the check (400):
  • The model answered with no text: “Model accepted the request but returned an empty response”
  • With Multimodal on (the default for chat models), the model refused the test image: “Model doesn’t support images/vision.”
  • With Multimodal on, the model took the test image but answered with no text: “Model accepted the image but returned an empty response”
For either image message, turn off Multimodal for this model, or choose a model that can read images. Any other failure (500): “Couldn’t connect to <provider> with these chat model settings. Check the API key, model name and endpoint, then try again.” The details are in the AI service’s logs. An endpoint that fails the endpoint check, including its lookup, never gets this message; it gets one of the endpoint messages.

​
Health check messages for other model types

Embedding, image, speech and speech-to-text models get the same endpoint messages as a chat model, and the same messages for a rejected key, a missing model and an unreachable endpoint. These messages differ by model type: The embedding timeout message in full: “Embedding health check timed out. If this is the first run, the model may still be downloading. Please wait for the download to complete and try again.” With Multimodal on, an embedding model is also asked to embed a test image. These failures return a 400:
  • The model refused the image: “Model cannot embed images.”
  • PipesHub can’t embed images with this provider: “Provider ‘<provider>’ has no image-embedding support in PipesHub, so images would never be indexed for this model.”
  • Image and text vectors differ in size: “Image embeddings are <n>-dimensional but text embeddings are <m>-dimensional; both share one collection.”
For any of these, turn off Multimodal for this model, or choose a model that embeds images. When the test image fails because of the endpoint or API key instead, the message says to check those.

​
Changing the embedding model in use

Adding or editing the embedding model that will be in use (the first one you add, or the one already in use) is also checked against what the vector store already holds. The dialog shows:
  • Content is indexed with another embedding model (400): “This model is embedding your indexed content. Delete the embeddings in Labs first, then change or delete the model and re-embed.”
  • PipesHub can’t read what the vector store holds (503): “Could not verify what the vector store currently holds, so an embedding model change cannot be validated. Check vector store connectivity and retry.”
  • The vector store is empty but couldn’t be rebuilt for the new model (503): “The vector store could not be rebuilt for the new embedding model, so the model was not changed. The empty collection may already have been removed; it is created again on the next upload. Check that the vector store is reachable and try again.”
In every case the model in use stays the same.

​
A chat stops answering

If a chat stops answering after a key expires or a model is removed at the provider, the chat says so and asks users to contact an admin. Update the model on the AI Models settings page, or set another model as the default.

​
Embedding models

Embedding models convert documents and search queries into numerical vectors so PipesHub can find semantically similar content. They power document indexing, semantic search, and retrieval across your workspace. At least one embedding model must be configured before you can index documents or use search. PipesHub ships with BAAI/bge-large-en-v1.5 built-in as the system default — it works out of the box with no configuration required. Connect an external provider only if you need a different model.

​
How to navigate to this page

Open the left sidebar → Workspace Settings → AI Models. Click the Embedding tab.
Only workspace admins and owners can access the AI Models settings page.

​
Add an embedding model

1

Open AI Models settings

Open the left sidebar → Workspace Settings → AI Models.
2

Go to the Embedding tab

Click the Embedding tab in the capability row.
3

Find your provider

Browse the provider cards or use the search box to filter by name.
4

Open the configuration panel

Click Configure on the provider card. A configuration panel slides open.
5

Fill in the required fields

Enter the credentials required for your provider. See the provider reference below.
6

Set optional fields (if needed)

  • Model Friendly Name — a human-readable label for this configuration.
  • Output Dimensions — override the vector size (1–65,536). Leave blank to use the model default. Only supported by select models (e.g. OpenAI text-embedding-3-* series).
  • Multimodal toggle — enable if this model can embed images as well as text (off by default).
7

Save and validate

Click Add Model. PipesHub runs a live health check to validate your credentials.
8

First model becomes the default

If this is the first embedding model you have added, it is automatically set as the default used for all document indexing and search.

​
Embedding provider reference

Azure OpenAI — Deployment Name: This is the name you assigned when deploying the model in Azure, not the model ID itself. Azure AI — Endpoint URL format: https://<resource>.services.ai.azure.com/openai/v1/ OpenAI Compatible: Use this for any provider that speaks the OpenAI embeddings API format. Ollama: No API key required for a local instance. Endpoint defaults to http://host.docker.internal:11434. Sentence Transformers / HuggingFace: Run locally inside PipesHub. No external API or API key needed. Amazon Bedrock: Leave AWS keys blank when running PipesHub on EC2 with an appropriate IAM role. Provider dropdown: Cohere, Amazon (Titan), Other.

​
Managing configured embedding models

After saving, your model appears under the Configured tab. Each row has the following actions:
  • Edit — update credentials or settings without deleting the configuration.
  • Set as Default — make this model the one used for all new document indexing and search.
  • Delete — permanently remove the configuration. You will be asked to type the model’s name to confirm.
While vectors are stored, PipesHub refuses to switch the embedding model in use to a different model or a different vector size. A different model is refused even if its vectors are the same size. The same model from another provider (for example nomic-ai/nomic-embed-text and nomic-embed-text) counts as unchanged: the change is saved and the stored vectors are kept. The embedding model in use is the default one, or the first configured model if none is marked default. With no embedding model configured, the built-in BAAI/bge-large-en-v1.5 embeds your content.The refusal covers adding your first embedding model when content is already embedded with the built-in model, setting another model as default, deleting the model in use, and editing the model in use to change its model name or Output Dimensions. Adding, editing and deleting are refused with: “This model is embedding your indexed content. Delete the embeddings in Labs first, then change or delete the model and re-embed.” Set as Default shows “Failed to set default model”. In every case the model in use stays the same. The first model you add sizes the vector store only when the store is empty.To change or delete the embedding model in use:
  1. Under Labs → Feature flags, turn on Enable Vector Store Rebuild and click Save. The Vector Store section appears in Labs.
  2. In Labs → Vector Store, click Clean up, type DELETE, and click Delete embeddings. The button stays disabled until the word is typed.
  3. Wait for the cleanup to finish. It runs in the background, and until it finishes the old vectors are still stored, so the change in step 4 is refused.
  4. Add, edit, set as default, or delete the embedding model.
  5. In Labs → Vector Store, click Reindex, type REINDEX, and click Start reindex. If the cleanup is still running, the reindex is refused with “A search index cleanup or reindex is already running. Wait for it to finish, then try again.” or “Vector-store cleanup is still dropping the collection”. Wait a little and try again.
Adding, editing or deleting any other embedding model does not touch the vector store.

​
Troubleshooting

If the health check fails when saving, double-check:
  • The API key is correct and has not expired.
  • For Azure providers, the endpoint URL matches the correct region and resource.
  • For Ollama, Sentence Transformers, and HuggingFace, confirm the model name is available locally.
  • The model name exactly matches what the provider API expects (check provider docs for valid IDs).
  • Output Dimensions is only supported by models that expose a dimensions parameter (e.g. OpenAI text-embedding-3-* series). Setting it on unsupported models will cause errors.
Keep your API keys secure. PipesHub stores these credentials securely, but you should never share them publicly or commit them to version control.

​
Image Generation models

Image generation models allow AI agents and workflows in PipesHub to generate images from text prompts. Once configured, these models are available to agents that support image creation tasks. At least one image generation model must be configured before image generation features are available in your workspace. Currently two providers are supported: OpenAI (DALL-E / GPT-Image models) and Gemini (Imagen / Gemini Image models).

​
How to navigate to this page

Open the left sidebar → Workspace Settings → AI Models. Click the Image Generation tab.
Only workspace admins and owners can access the AI Models settings page.

​
Add an image generation model

1

Open AI Models settings

Open the left sidebar → Workspace Settings → AI Models.
2

Go to the Image Generation tab

Click the Image Generation tab in the capability row.
3

Open the configuration panel

Click Configure on the provider card you want to use.
4

Fill in the required fields

Enter your API Key and the Model Name (exact model identifier string). See the provider reference below.
5

Set an optional friendly name

Optionally set a Model Friendly Name — a human-readable label displayed in the UI.
6

Save and validate

Click Add Model. PipesHub runs a live health check to validate your credentials.
7

First model becomes the default

If this is the first image generation model you have added, it is automatically set as the default used when image generation is triggered.

​
Image generation provider reference

OpenAI: Get your API key at platform.openai.com/api-keys. Gemini: Get your API key at aistudio.google.com/app/apikey. Imagen models require a Google Cloud project with the Vertex AI API enabled, or access via Google AI Studio.

​
Managing configured image generation models

After saving, your model appears under the Configured tab. Each row has the following actions:
  • Edit — update credentials or the model name.
  • Set as Default — make this the model used when image generation is triggered.
  • Delete — permanently remove the configuration. You will be asked to type the model’s name to confirm.

​
Troubleshooting

If the health check fails when saving, double-check:
  • The API key is correct and has not expired.
  • The model name exactly matches what the provider API expects (e.g. dall-e-3, not DALL-E-3).
  • For Gemini Imagen models, confirm your API key has access to image generation — not all Google AI Studio keys have Imagen enabled by default.

​
Text to Speech (TTS) models

Text to Speech models convert AI text responses into spoken audio, enabling voice output in AI workflows and agents. Once configured, these models are available wherever PipesHub produces audio output. At least one TTS model must be configured before voice features are available in your workspace. Currently two providers are supported: OpenAI (tts-1, tts-1-hd, gpt-4o-mini-tts) and Gemini (gemini-2.5-flash-preview-tts and related models).

​
How to navigate to this page

Open the left sidebar → Workspace Settings → AI Models. Click the TTS tab.
Only workspace admins and owners can access the AI Models settings page.

​
Add a TTS model

1

Open AI Models settings

Open the left sidebar → Workspace Settings → AI Models.
2

Go to the TTS tab

Click the TTS tab in the capability row.
3

Open the configuration panel

Click Configure on the provider card you want to use.
4

Fill in the required fields

Enter your API Key and the Model Name (exact model identifier string). See the provider reference below.
5

Choose optional settings

  • Voice — select a default voice for audio output.
  • Audio Format — select the output audio format.
  • Model Friendly Name — a custom display label for this configuration.
6

Save and validate

Click Add Model. PipesHub validates your credentials with a live health check.
7

First model becomes the default

If this is the first TTS model you have added, it is automatically set as the default used for all TTS output.

​
TTS provider reference

OpenAI voices: Alloy, Echo, Fable, Onyx, Nova, Shimmer. Get your API key at platform.openai.com/api-keys. OpenAI audio formats: MP3, Opus, AAC, FLAC, WAV. Gemini voices: 30 prebuilt voices named after astronomical objects — Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat. Get your API key at aistudio.google.com/app/apikey. Gemini audio formats: WAV and PCM work without any extra dependencies. MP3, Opus, AAC, and FLAC require ffmpeg installed on the PipesHub backend host.

​
Managing configured TTS models

After saving, your model appears under the Configured tab. Each row has the following actions:
  • Edit — update credentials, voice, or format settings.
  • Set as Default — make this the model used for all TTS output.
  • Delete — permanently remove the configuration. You will be asked to type the model’s name to confirm.

​
Troubleshooting

If the health check fails when saving, double-check:
  • The API key is correct and has not expired.
  • The model name exactly matches what the provider API expects (e.g. tts-1, not TTS-1).
  • For Gemini compressed formats (MP3, Opus, AAC, FLAC), ensure ffmpeg is installed on the machine running the PipesHub backend. WAV and PCM work without any additional dependencies.

​
Speech to Text (STT) models

Speech to Text models transcribe spoken audio into text, enabling voice input in AI workflows and agents. Once configured, these models power voice-driven interactions across your PipesHub workspace. Four providers are supported: OpenAI and Gemini (cloud APIs), Whisper (self-hosted open-source via faster-whisper), and Wispr Flow (hosted specialist transcription service). At least one STT model must be configured before voice input features are available.

​
How to navigate to this page

Open the left sidebar → Workspace Settings → AI Models. Click the STT tab.
Only workspace admins and owners can access the AI Models settings page.

​
Add an STT model

1

Open AI Models settings

Open the left sidebar → Workspace Settings → AI Models.
2

Go to the STT tab

Click the STT tab in the capability row.
3

Open the configuration panel

Click Configure on the provider card you want to use.
4

Fill in the required fields

Enter the required fields for your provider (API Key and Model Name for cloud providers, or select a Model size for Whisper local). See the provider reference below.
5

Adjust optional settings

Configure any optional settings such as language, device, compute type, or app type depending on your provider.
6

Set an optional friendly name

Optionally set a Model Friendly Name — a custom label shown in the UI.
7

Save and validate

Click Add Model. PipesHub validates your configuration with a live health check.
8

First model becomes the default

If this is the first STT model you have added, it is automatically set as the default used for all speech transcription.

​
STT provider reference

OpenAI: Get your API key at platform.openai.com/api-keys. Gemini: Get your API key at aistudio.google.com/app/apikey. Whisper (local): No API key required. Runs on your own infrastructure using faster-whisper. Model weights are downloaded from HuggingFace on first use. Optional: Device (Auto/CPU/CUDA), Compute Type (int8/float16/float32), Model Cache Directory. Wispr Flow: Contact enterprise@wisprflow.ai to obtain an API key. Requires ffmpeg on the backend host. Optional: Default Language, App Type, API Endpoint override.

​
Managing configured STT models

After saving, your model appears under the Configured tab. Each row has the following actions:
  • Edit — update credentials or settings.
  • Set as Default — make this the model used for all speech transcription.
  • Delete — permanently remove the configuration. You will be asked to type the model’s name to confirm.

​
Troubleshooting

If the health check fails when saving, double-check:
  • For OpenAI and Gemini: the API key is correct and has not expired.
  • For Whisper (local): the faster-whisper package is installed on the backend host. On first use, model weights are downloaded — ensure internet access is available.
  • For Wispr Flow: ffmpeg must be installed on the backend host. Confirm your API key is active (contact enterprise@wisprflow.ai if unsure).