Choosing a model for chat

The model is the language model that powers a chat — it reads your message, decides which tools to call, and writes the reply. ModuleX lets you choose that model per chat, and your organization decides which models are on the menu in the first place. This page covers the three things worth knowing: how to pick a model, the difference between ModuleX-managed models and bringing your own key (BYOK), and why your list of models can differ from a teammate’s.

Choosing a model here changes the model for the Assistant — the chat that uses your connected tools to get work done. For the full provider reference (OpenAI, Anthropic, Google Gemini, xAI Grok, and ModuleX-managed), see LLM providers.

Pick a model

Every chat runs on one model at a time. You pick it from the model selector next to the message box before you send, and you can switch models between turns in the same chat.

Open the model selector

In a chat, open the model selector beside the composer. It lists the models your organization has turned on, grouped by provider.

Choose a model

Pick the model you want. Each entry shows its display name and provider so you can tell a ModuleX-managed model apart from one connected with your own key.

Send your message

Send as usual. The model you chose handles this turn. If you do nothing, the chat uses your organization’s default model.

Switch any time

Change the model and send again to use a different model for the next turn. Your choice is a per-session override — it does not change the organization default.

Three layers decide which model runs

You rarely have to think about this, but it explains why a chat behaves the way it does. ModuleX resolves the model for a turn from three layers, most specific first:

Your session choice

The model you picked in the selector for this chat. It wins when it is set, and it lasts for the session only.

Organization default

The model your organization saved as the default. It is used whenever you have not picked one.

The run's model

Once a turn starts, it stays on the model it began with — including when a paused chat resumes. Changing the selector affects the next turn, not the one already running.

In practice: pick a model and it is used; leave it alone and the organization default is used; a turn already in flight keeps its own model to the end.

Managed models vs your own key (BYOK)

Models come from two kinds of sources, and the difference shows up on your bill.

ModuleX-managed models

The default. The model runs through ModuleX-provisioned providers, so there is nothing to connect — it works out of the box. Usage is metered in credits. On the wire these models belong to the modulexai provider.

Bring your own key (BYOK)

Connect your own provider account — OpenAI, Anthropic, Google Gemini, or xAI Grok — and ModuleX calls the model with your key. The provider bills you directly, with no ModuleX markup.

How they compare

	ModuleX-managed	BYOK
Setup	None — available by default	Connect a provider credential first
Billing	Metered in ModuleX credits	Billed by the provider, no ModuleX markup
Counts toward your credit balance	Yes	No — BYOK usage is not credited
Provider on the wire	`modulexai`	The provider you connected, for example `openai`
Best for	Getting started fast and a single bill	Existing provider contracts and direct cost control

BYOK usage is not credited — it is billed directly by your provider and appears in ModuleX analytics for visibility only. ModuleX-managed usage is the only kind that draws down your credit balance. For what a credit is and exactly what consumes one, see Credits & metering.

To use a BYOK model you first connect that provider’s account as a credential. Start at LLM providers, then follow Authentication & credentials. Once connected, the model appears in your chat selector. The default managed option is documented at ModuleX-managed models.

Per-organization availability

The selector does not show every model that exists — it shows the models your organization has turned on. Two people in different organizations, or even in the same one at different times, can see different lists.

Who controls the list

Model availability is an organization-level setting managed by an organization owner or admin. They choose which models are visible to the organization and which model is the saved default. Other roles use whatever the owner or admin has enabled. (The legacy member role has been retired — only owner and admin exist. See Roles & permissions.)

Active vs inactive models

ModuleX keeps two groups per organization: active models, which appear in the selector, and inactive models, which are hidden. Owners and admins move models between the two. A model you connected with your own key still has to be active to appear.

Why your list can differ

Your list reflects your current organization’s choices. Switch organizations and the selector — along with the default model — changes to match. A BYOK model also only appears once the matching provider credential exists in that organization.

Deprecated models

A model can be marked deprecated by its provider. When that happens ModuleX points to a successor model so you can move over. Prefer the current model when you see a deprecation note.

Setting a model from the API

Most people pick a model in the app. If you drive a chat over the API, you pass the model in the llm object when you send a turn. Omit llm and the chat falls back to your organization’s default model. The llm object has four fields: integration_name, provider_id, and model_id are required, and credential_id is optional (used to point at a specific BYOK credential). Authenticate with Authorization: Bearer mx_live_… and X-Organization-ID, the same as every ModuleX request.

curl -X POST https://api.modulex.dev/assistant/chat \
  -H "Authorization: Bearer mx_live_8f2c4a1e9b7d6f3a0c5e2d1b" \
  -H "X-Organization-ID: org_3a7f9c2e1d4b" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize my open GitHub issues",
    "llm": {
      "integration_name": "openai",
      "provider_id": "openai",
      "model_id": "gpt-4o"
    }
  }'

from modulex import ModuleX

client = ModuleX(
    api_key="mx_live_8f2c4a1e9b7d6f3a0c5e2d1b",
    organization_id="org_3a7f9c2e1d4b",
)

response = client.assistant.chat(
    message="Summarize my open GitHub issues",
    llm={
        "integration_name": "openai",
        "provider_id": "openai",
        "model_id": "gpt-4o",
    },
)

import { ModuleX } from "@modulex/sdk";

const client = new ModuleX({
  apiKey: "mx_live_8f2c4a1e9b7d6f3a0c5e2d1b",
  organizationId: "org_3a7f9c2e1d4b",
});

const response = await client.assistant.chat({
  message: "Summarize my open GitHub issues",
  llm: {
    integration_name: "openai",
    provider_id: "openai",
    model_id: "gpt-4o",
  },
});

The Assistant chat endpoints require an owner or admin role in the organization. A request from a non-admin is rejected. To answer a paused chat that is waiting on you (human-in-the-loop), you pass the same llm object again on resume so the model can be rebuilt — see Human-in-the-loop.

Sending a chat turn is gated by billing on the run surface. If your plan’s credits are exhausted, your wallet cannot cover overage, or you hit a rate limit, the request is rejected with a 402, 403, or 429 carrying a flat denial body — for example {code, layer, key, current, limit, reason}. BYOK usage still counts as a turn for rate limiting even though it is not credited. See Usage gating & limits and Errors & status codes.

What to pick

Just getting started

Use a ModuleX-managed model and skip setup. Usage is metered in credits and there is nothing to connect.

You have a provider account

Connect your own key (BYOK) to use your existing provider and be billed directly, with no ModuleX markup.

You manage the organization

As an owner or admin, choose which models your team can use and set the default model for everyone.

You want the cost details

See exactly what a credit is and what managed model usage consumes.

LLM providers

The full provider reference — managed and BYOK — and the models each one offers.

Assistant models & settings

Choose the model and configure how the Assistant behaves.

Chat overview

The chat surface for talking to the Assistant, running workflows, and querying knowledge.

Credits & the billing model

How managed usage is metered and where the billing gate applies.

App overview

Chat

Knowledge

Collaboration

Builder

Nodes

Execution

Co-editing

Assistant Chat

Choosing a model for chat

Pick a model

Three layers decide which model runs

Your session choice

Organization default

The run's model

Managed models vs your own key (BYOK)

ModuleX-managed models

Bring your own key (BYOK)

How they compare

Per-organization availability

Setting a model from the API

What to pick

Just getting started

You have a provider account

You manage the organization

You want the cost details

LLM providers

Assistant models & settings

Chat overview

Credits & the billing model

​Pick a model

​Three layers decide which model runs

Your session choice

Organization default

The run's model

​Managed models vs your own key (BYOK)

ModuleX-managed models

Bring your own key (BYOK)

​How they compare

​Per-organization availability

​Setting a model from the API

​What to pick

Just getting started

You have a provider account

You manage the organization

You want the cost details

​Related pages

LLM providers

Assistant models & settings

Chat overview

Credits & the billing model

Pick a model

Three layers decide which model runs

Managed models vs your own key (BYOK)

How they compare

Per-organization availability

Setting a model from the API

What to pick

Related pages