OpenAI — ModuleX LLM providers

OpenAI is a bring-your-own-key (BYOK) LLM provider in ModuleX. You connect your own OpenAI API key as a credential, and ModuleX uses it to call OpenAI’s GPT, o-series reasoning, and embedding models from your workflows, the Assistant, the AI Composer, and chat. Because OpenAI usage runs through your own key, it is billed by OpenAI directly and consumes no ModuleX credits. This page covers connecting an OpenAI credential, the OpenAI models ModuleX exposes in its catalog, how to select an OpenAI model on each surface, and how BYOK billing works. For the cross-provider picture see LLM providers; for the credential model and OAuth see Credentials & OAuth2.

OpenAI is the integration named openai on the wire (integration_type: "llm_provider"). It exposes one auth schema — api_key — so there is no ModuleX-managed (pooled-key) option for OpenAI. For credit-metered managed models, use ModuleX-managed models instead.

Before you start

An OpenAI API key

Create a secret key at the OpenAI API keys page. It starts with sk- (for example sk-proj-…). ModuleX validates it against the format ^sk-[a-zA-Z0-9\-_]{20,}$.

Owner or admin role

Creating and managing credentials and browsing the integration catalog require the owner or admin role in your organization. The retired member role cannot perform these actions. See Roles & permissions.

Your auth headers

Every API call sends Authorization: Bearer mx_live_… and X-Organization-ID. See Authentication.

An OpenAI billing account

BYOK usage is charged by OpenAI to your OpenAI account, not by ModuleX. Make sure your OpenAI account has billing enabled and sufficient quota.

Connect OpenAI

You connect OpenAI by creating an api_key credential for the openai integration. ModuleX auto-detects the credential type from the body you send: an auth_data object containing api_key is stored as an api_key credential.

Get your OpenAI API key

In the OpenAI dashboard, go to API keys, choose Create new secret key, name it, set its permissions, and copy the value. You only see it once — store it securely until you paste it into ModuleX.

(Optional) validate it before saving

Call POST /credentials/test-temporary to check the key works before persisting it. ModuleX runs OpenAI’s configured test — a minimal POST https://api.openai.com/v1/chat/completions with gpt-5.4-mini and max_tokens: 10 — and reports is_valid.

Create the credential

Call POST /credentials with integration_name: "openai" and auth_data.api_key. Set make_default: true to make it the default OpenAI credential for the organization. ModuleX encrypts the key at rest and never returns it in clear text.

Select OpenAI models

The key is now resolvable for any surface that runs an OpenAI model — workflows, the Assistant, the Composer, and chat. See Select an OpenAI model.

🎬 MEDIA PLACEHOLDER · MX-MEDIA-4060 · [SCREENSHOT] [SCREENSHOT_DESCRIPTION]: The ModuleX app credential dialog for connecting OpenAI with an API key. [SCREENSHOT_DETAILS]: Capture the “Connect OpenAI” credential form in the integrations/credentials area of the ModuleX app. Show the OpenAI logo, the API Key field (masked, placeholder sk-proj-…), the optional Base URL field defaulting to https://api.openai.com/v1, the “Set as default” toggle, and the Test/Save buttons. Light theme, 16:9, crop to the dialog.

Create the credential

POST /credentials returns 201. The type is auto-detected from the body — passing auth_data.api_key yields an api_key credential. See the full credentials reference in Credentials & OAuth2.

integration_name

string

required

Must be openai.

auth_data

object

required

The secret material. For OpenAI, {"api_key": "sk-proj-…"}. The presence of api_key selects the api_key auth type. To target an OpenAI-compatible endpoint, also include base_url (see OpenAI-compatible endpoints).

display_name

string

A human-readable label. Defaults to the integration’s display name (OpenAI) when omitted.

make_default

boolean

default:"false"

Set this credential as the default OpenAI credential for the organization. Only one credential per integration can be the default.

expires_at

string

Optional ISO-8601 datetime after which ModuleX treats the credential as expired.

Response — 201 Created (secret masked):

credential_id

string

The credential’s UUID. Pass this as credential_id to pin a specific OpenAI key on a run.

integration_name

string

openai.

integration_type

string | null

llm_provider.

auth_type

string

api_key.

is_default

boolean

Whether this is the organization’s default OpenAI credential.

last_used_at

string | null

ISO-8601 timestamp of the last resolution, or null if never used.

curl -X POST https://api.modulex.dev/credentials \
  -H "Authorization: Bearer mx_live_xxx" \
  -H "X-Organization-ID: 11111111-1111-1111-1111-111111111111" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_name": "openai",
    "display_name": "Production OpenAI key",
    "make_default": true,
    "auth_data": { "api_key": "sk-proj-abc123" }
  }'

Validate a key before saving

POST /credentials/test-temporary validates auth data before you persist it. ModuleX runs OpenAI’s configured test endpoint (POST https://api.openai.com/v1/chat/completions, model gpt-5.4-mini, max_tokens: 10) and treats HTTP 200 with id, choices, and model present as success.

integration_name

string

required

openai.

auth_type

string

required

api_key.

auth_data

object

required

{"api_key": "sk-proj-…"}. Optionally include base_url.

The response reports is_valid, a human-readable message, tested_at, and a test_method of api_call.

curl -X POST https://api.modulex.dev/credentials/test-temporary \
  -H "Authorization: Bearer mx_live_xxx" \
  -H "X-Organization-ID: 11111111-1111-1111-1111-111111111111" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_name": "openai",
    "auth_type": "api_key",
    "auth_data": { "api_key": "sk-proj-abc123" }
  }'

OpenAI-compatible endpoints

OpenAI’s auth schema includes an optional base_url field, so you can point the same credential at any OpenAI-compatible API (a proxy, gateway, or self-hosted server that speaks the OpenAI wire protocol).

base_url

string

default:"https://api.openai.com/v1"

The API base URL. Only change this for an OpenAI-compatible endpoint. ModuleX validates it against ^https?://.*.

Include base_url inside auth_data when you create the credential. Leave it unset to use OpenAI directly.

cURL

curl -X POST https://api.modulex.dev/credentials \
  -H "Authorization: Bearer mx_live_xxx" \
  -H "X-Organization-ID: 11111111-1111-1111-1111-111111111111" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_name": "openai",
    "display_name": "OpenAI-compatible gateway",
    "auth_data": {
      "api_key": "sk-proxy-abc123",
      "base_url": "https://gateway.example.com/v1"
    }
  }'

The catalog model ids on this page (for example gpt-5.5) map to OpenAI’s own model names via each model’s body_extra.model. A custom base_url must serve those same model names, or the upstream call returns a model-not-found error from your endpoint.

Available models

ModuleX serves OpenAI’s models from its integration catalog. The list below is the catalog as shipped in the backend OpenAI manifest; OpenAI updates models over time, so always treat the live catalog (browse it via the API) as authoritative. Each model carries a standardized id (the value you pass as model_id), pricing in USD per 1M tokens (input and output), a context window (max_input_tokens), an output cap (max_output_tokens), a knowledge cutoff (data_freshness), intelligence and speed scores (1–5), and vision support. Pricing shown is OpenAI’s list price that ModuleX records for analytics — your actual charge comes from OpenAI, not ModuleX.

Chat and reasoning models

`model_id`	Display name	Context (in)	Max output	Input $/1M	Output $/1M	Vision	Cutoff
`gpt-5.5`	GPT 5.5	1,050,000	128,000	$5.00	$30.00	Yes	2025-12-01
`gpt-5.5-pro`	GPT 5.5 Pro	1,050,000	128,000	$30.00	$180.00	Yes	2025-12-01
`gpt-5.4`	GPT 5.4	1,050,000	128,000	$2.50	$15.00	Yes	2025-08-31
`gpt-5.4-pro`	GPT 5.4 Pro	1,050,000	128,000	$30.00	$180.00	Yes	2025-08-31
`gpt-5.4-mini`	GPT 5.4 mini	400,000	128,000	$0.75	$4.50	Yes	2024-05-31
`gpt-5.4-nano`	GPT 5 nano	400,000	128,000	$0.20	$1.25	Yes	2024-08-31
`gpt-5-chat-latest`	GPT 5 chat latest	128,000	16,384	$1.25	$10.00	Yes	2024-09-30
`gpt-5.3-codex`	GPT 5.3 codex	400,000	128,000	$1.75	$14.00	Yes	2025-08-31
`o3-pro`	o3-pro	200,000	100,000	$20.00	$80.00	Yes	2024-06-01
`o3`	o3	200,000	100,000	$2.00	$8.00	Yes	2024-06-01

Embedding models

Embedding models return a vector instead of text (max_output_tokens is 0). Use them to build a knowledge base with OpenAI embeddings, or in a workflow that needs vectors.

`model_id`	Display name	Dimensions	Max input	Input $/1M	Output $/1M
`text-embedding-3-large`	Text Embedding 3 Large	3072	8,191	$0.13	$0.00
`text-embedding-3-small`	Text Embedding 3 Small	1536	8,191	$0.02	$0.00

text-embedding-3-small produces 1536-dimensional vectors, which match ModuleX’s managed vector storage column width. text-embedding-3-large produces 3072-dimensional vectors. Pick the embedding model that matches your vector store’s dimension when you configure a knowledge base. See Managed knowledge and Knowledge & RAG.

Show Full model schema (catalog fields per model)

Every entry in the OpenAI models[] array carries these fields. ModuleX stores them verbatim and returns them on the detail endpoint.

string

The standardized catalog model id you pass as model_id (for example gpt-5.5).

display_name

string

The human-readable model name.

provider

string

The display vendor — OpenAI.

provider_id

string

The routing provider slug — openai. Pass this as provider_id in an llm config.

max_input_tokens

integer

The context-window size in tokens.

max_output_tokens

integer

The maximum tokens the model can return. 0 for embedding models.

body_extra

object

The provider request-body fragment, including the real OpenAI wire model name. For OpenAI the catalog id and body_extra.model are the same.

headers_extra

object

Extra request headers. Empty ({}) for every OpenAI model.

description

string

A usage blurb describing the model’s strengths.

data_freshness

string

The knowledge cutoff date (ISO date). There is no separate knowledge_cutoff field.

intelligence

integer

A quality score, 1–5.

speed

integer

A latency score, 1–5 (higher is faster).

supports_vision

boolean

Whether the model accepts image input.

input_usd_per_1m_tokens

number

OpenAI’s list input price per 1M tokens (flat field, not a nested pricing object).

output_usd_per_1m_tokens

number

OpenAI’s list output price per 1M tokens. 0 for embedding models.

is_embedding

boolean

Present and true only on embedding models.

embedding_dimension

integer

The output vector dimension — present only on embedding models (3072 for large, 1536 for small).

Select an OpenAI model

Across the API and SDKs, you choose a model with an llm configuration object. For OpenAI, every field uses the openai slug:

integration_name

string

required

openai.

provider_id

string

required

openai.

model_id

string

required

A catalog model id from Available models, for example gpt-5.5.

credential_id

string

The id of the OpenAI credential to use. Omit it to let ModuleX resolve a credential: your is_default OpenAI credential, then the most-recent valid one. ModuleX prefers your own keys over managed keys — and OpenAI is BYOK-only, so resolution always lands on a key you connected.

This is the same shape the Assistant and AI Composer accept for their llm field:

llm config

{
  "integration_name": "openai",
  "provider_id": "openai",
  "model_id": "gpt-5.5",
  "credential_id": "c0ffee00-1111-2222-3333-444455556666"
}

In a workflow (LLM node)
In the Assistant
In the AI Composer
In chat

In the LLM node (and the Agent node), set the node’s llm_config to an OpenAI model. ModuleX resolves the standardized model_id to OpenAI’s wire model via the catalog’s body_extra.model, then calls OpenAI with your resolved credential. See Workflow engine & nodes.

Pass the llm object when you start an Assistant chat. The Assistant rebuilds the model from this config on every turn and on resume, so the same llm object must be supplied each time. See Models & settings.

The Composer takes the same llm object to generate and edit your workflow graph. If you omit it, ModuleX falls back to the organization’s configured Composer default model. See AI Composer in the builder.

Deprecation routing applies only to managed models. For managed integrations (modulexai), a model marked deprecated routes to its replacement_id automatically, and unknown ids fall back to the integration default. OpenAI is BYOK (a passthrough integration), so its model_id is used as-is — an unknown id is sent straight to OpenAI and fails there. None of the OpenAI catalog models are currently marked deprecated.

Browse OpenAI in the catalog

The integration catalog is the read-only discovery surface. Use it to fetch OpenAI’s live models, pricing, and auth schema. These catalog endpoints authenticate with a Clerk JWT (the app token), not an mx_live_* API key, and still require X-Organization-ID and the owner/admin role.

provider_name

string

required

openai.

Response — 200 OK, an IntegrationDetail:

name

string

openai.

display_name

string

OpenAI.

integration_type

string

llm_provider.

models

object[]

The OpenAI model list described in Available models.

auth_schemas

object[]

The OpenAI auth schemas. OpenAI ships a single api_key schema with setup_instructions, the api_key and base_url setup_environment_variables, and a test_endpoint.

docs_url

string | null

https://platform.openai.com/docs.

metadata

object | null

The integration’s extra_metadata (status, recommended, timestamps, popularity score).

curl https://api.modulex.dev/integrations/llm-providers/openai \
  -H "Authorization: Bearer <clerk_jwt_token>" \
  -H "X-Organization-ID: 11111111-1111-1111-1111-111111111111"

Show Example detail response (truncated)

{
  "name": "openai",
  "display_name": "OpenAI",
  "description": "OpenAI's GPT models for chat, completion, and embeddings",
  "logo": "modulex:openai-themed",
  "app_url": "https://platform.openai.com",
  "docs_url": "https://platform.openai.com/docs",
  "categories": ["AI & LLM Providers", "ai", "chat", "completion"],
  "integration_type": "llm_provider",
  "version": "1.0.0",
  "auth_schemas": [
    {
      "auth_type": "api_key",
      "display_name": "API Key Authentication",
      "description": "Connect using OpenAI API Key",
      "setup_environment_variables": [
        { "name": "api_key", "required": true, "sensitive": true },
        { "name": "base_url", "required": false, "default": "https://api.openai.com/v1" }
      ],
      "test_endpoint": { "url": "https://api.openai.com/v1/chat/completions", "method": "POST" }
    }
  ],
  "models": [
    {
      "id": "gpt-5.5",
      "display_name": "GPT 5.5",
      "provider": "OpenAI",
      "provider_id": "openai",
      "max_input_tokens": 1050000,
      "max_output_tokens": 128000,
      "supports_vision": true,
      "input_usd_per_1m_tokens": 5.0,
      "output_usd_per_1m_tokens": 30.0
    }
  ],
  "metadata": { "status": "active", "recommended": true, "popularity_score": 92 }
}

ModuleX maintains a backend-only llm_max_tokens resolver that caps output tokens per scenario (for example chat vs workflow node). Those values are never returned by any catalog API response — do not rely on the catalog max_output_tokens as the effective per-scenario output cap.

BYOK billing

OpenAI is bring-your-own-key. Usage on your OpenAI credential is billed by OpenAI to your OpenAI account and is not metered in ModuleX credits.

No ModuleX credit charge

BYOK calls — OpenAI included — carry no ModuleX credit gate. There is no markup, and these calls do not draw down your plan allowance or wallet.

No billing-gate denials

Because there is no credit gate on BYOK calls, OpenAI usage does not produce the 402/403/429 DenialEnvelope that managed usage can. See Usage gating & limits.

Billed by OpenAI

Token costs accrue on your OpenAI account at OpenAI’s rates. Set spend limits and monitor usage in the OpenAI dashboard.

Analytics only

ModuleX records token counts and the catalog list price for OpenAI usage for analytics, so you can see consumption per workflow or run — but no credits are deducted.

Want credit-metered, no-key-required models instead? Use ModuleX-managed models (the modulexai provider), which run on ModuleX-provisioned keys and bill in credits — gated by your plan. There is no managed (pooled-key) path for openai; OpenAI is always BYOK. See Credits & metering.

Rate limits, quotas, and model availability for BYOK calls are governed by your OpenAI account, not by ModuleX. A 429 or quota error from OpenAI surfaces as an upstream error on the run, distinct from ModuleX’s own rate limiting.

Managing the credential

Day-to-day operations use the standard credentials API. For OpenAI specifically:

Rotate a key. Secrets are immutable through PUT /credentials/{id} (that route updates only display_name and metadata). To rotate, create a new OpenAI credential with the new key and delete the old one — there is no rotate endpoint.
Set the default. POST /credentials/{id}/set-default makes one OpenAI credential the organization default, used when no credential_id is supplied.
Test a saved key. POST /credentials/{id}/test re-runs OpenAI’s test endpoint against the stored key.
Delete. DELETE /credentials/{id} removes it and returns 204. Runs that relied on it will fail credential resolution until another valid OpenAI credential exists.

See Managing credentials for the app workflow and Credentials & OAuth2 for the complete API.

Where to go next

LLM providers

Compare OpenAI with the other model providers, managed and BYOK.

ModuleX-managed models

The credit-metered, no-key-required default provider.

Credentials & OAuth2

The full credential model, resolution precedence, and credentials API.

LLM node

Call an OpenAI model from a workflow with prompts, variables, and structured output.

​Before you start

An OpenAI API key

Owner or admin role

Your auth headers

An OpenAI billing account

​Connect OpenAI

​Create the credential

​Validate a key before saving

​OpenAI-compatible endpoints

​Available models

​Chat and reasoning models

​Embedding models

​Select an OpenAI model

​Browse OpenAI in the catalog

​BYOK billing

No ModuleX credit charge

No billing-gate denials

Billed by OpenAI

Analytics only

​Managing the credential

​Where to go next

LLM providers

ModuleX-managed models

Credentials & OAuth2

LLM node

Before you start

Connect OpenAI

Create the credential

Validate a key before saving

OpenAI-compatible endpoints

Available models

Chat and reasoning models

Embedding models

Select an OpenAI model

Browse OpenAI in the catalog

BYOK billing

Managing the credential

Where to go next