OpenAI Module

The core of the OpenAI family: chat completions, the Responses API, embeddings, moderation, model listing, conversations, and containers — plus the shared API key every OpenAI satellite Module uses.

The Module connects to OpenAI on your behalf. Set the API key once in the Module's Environment configuration and every Task in this Module uses it automatically. The same key also powers the six OpenAI satellite Modules — install only the satellites you need and they pick up this Module's Environment configuration without any extra setup.

The OpenAI family

The OpenAI capability set is split across seven focused Modules. This page is the core; the six satellites each cover one topic:

• OpenAI Assistants — multi-turn Assistant threads (with streaming), assistant management, run cancellation, and the function-tool callback loop.
• OpenAI Files & Vector Stores — upload, list, download, and delete files; create and populate vector stores for retrieval.
• OpenAI Images — generate, edit, and vary images.
• OpenAI Audio — text-to-speech, transcription (including speaker-diarized), and audio translation.
• OpenAI Batch & Fine-tuning — bulk inference at a discount and custom fine-tuned models.
• OpenAI Realtime — short-lived Realtime session tokens for direct client connections.

The satellites have no configuration of their own — they all use the API key you set in this Module's Environment configuration.

What you can build

• Chatbots, FAQ agents — OpenAIChatCompletionTask, OpenAIResponseTask.
• Content safety pipelines — OpenAIModerationTask branches "flagged" / "clean" before downstream LLM Tasks run.
• Token-streaming replies — OpenAIChatCompletionStreamTask and OpenAIResponseStreamTask collect the reply chunk by chunk for live UI mirroring.
• Semantic search / classification — OpenAIEmbeddingTask produces a float[] vector you can compare against pre-indexed examples.
• Persistent multi-turn memory — OpenAICreateConversationTask + OpenAIResponseTask keep conversation history on OpenAI's side, no message bookkeeping in your Process.

Quick start

1. In OpenAI Console, API keys → Create new secret key. Copy it once.
2. Open the OpenAI Module's Environment configuration for the Environment you deploy to. Paste the API key into ChatGPT API Key. Optionally fill in OpenAI Organization if your account belongs to more than one org.
3. In the Process Editor, drop a Task and convert it to one of the OpenAI Tasks listed below.
4. Wire the Task's input fields to variables produced by earlier Tasks using {variable} placeholders.
5. Deploy and trigger the workflow.

Done.

Configuration

Configuration is per Environment — each Environment supplies its own credentials. Every OpenAI Module is configured separately: the satellite Modules (Assistants, Files & Vector Stores, Images, Audio, Batch & Fine-tuning, Realtime) each have their own API key field, so you can reuse one key everywhere or give each capability a dedicated key.

ChatGPT API Key

Required. The OpenAI API key used for every call from this Environment. Find it in OpenAI Console → API keys → Create new secret key. Stored encrypted at rest.

OpenAI Organization

Optional. Your OpenAI organization ID (org-…). Required only if your account belongs to more than one organization.

Default Language

UI hint. Does not change which model the API calls.

System Message / Example Prompts

Reserved for future automatic priming of chat sessions. Currently has no effect.

Webhook Signing Secret

Optional. Secret used to verify inbound OpenAI webhooks (batch completion, fine-tuning events). Find it in OpenAI Console → Settings → Webhooks → reveal signing secret. Without it, all webhook calls are rejected.

Tasks

All Tasks in this Module are Generic (all Channels) — they run the same regardless of how the Session was started.

Output fields: type a variable name without braces (for example reply) and pick its type (string, number, true/false, object, date). The Task saves its result there, and any later Task can use it by writing {reply}.

OpenAIChatCompletionTask

Stateless one-shot chat completion. The fastest path from prompt → reply for non-conversational use cases.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-4o-mini	Chat model name, e.g. gpt-4o-mini, gpt-4o, gpt-4.1.
Temperature	string	No	0.7	Sampling temperature 0.0–2.0. Empty → model default.
Top P	string	No	1.0	Nucleus sampling cutoff (0–1). Empty → model default.
Max Output Tokens	string	No	1024	Cap on output tokens. Empty → model default.
Seed	string	No	42	Reproducibility seed. Empty → not set.
Stop Sequences	string	No	END,STOP	Comma-separated list of strings; generation stops when any one is produced.
Frequency Penalty	string	No	0.5	Penalty for repeated tokens (-2.0 to 2.0). Empty → 0.
Presence Penalty	string	No	0.5	Penalty for tokens present so far (-2.0 to 2.0). Empty → 0.
System Prompt	string	No	You are a support bot.	Optional system instructions. Supports {variable} placeholders.
User Message	string	Yes	{userMessage}	User message. Supports {variable} placeholders.
Image Input URL	string	No	{imageUrl}	Optional. URL of an image to include alongside the user message (vision-capable models only).
JSON Schema Name	string	No	ExtractedFields	If set together with JSON Schema, forces structured output that conforms to the schema.
JSON Schema	string	No	{"type":"object"}	Optional JSON Schema (as JSON). When set together with JSON Schema Name, the model must return JSON conforming to it.
Output Variable	string	Yes	reply	Variable name (no braces). Receives the assistant text reply.

Failure modes: ModuleMissingConfiguration, TaskInvalidData (model / output var), ModuleInputEmpty (resolved user message empty), ModuleException (OpenAI rejection).

Example: Set Model = gpt-4o-mini, System Prompt = You are a support bot for a bakery., User Message = {userMessage}, Output Variable = reply. When {userMessage} is "When do you open?", the Task saves the model's answer — e.g. "We open Monday to Saturday at 8:00." — to reply; a later Task sends it with {reply}.

OpenAIChatCompletionStreamTask

Streaming chat completion. The reply is generated chunk by chunk; the Task collects the chunks into the final reply and can also save the ordered chunk list for live UI mirroring or audit.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-4o-mini	Chat model name.
Temperature	string	No	0.7	Sampling temperature 0.0–2.0. Empty → model default.
System Prompt	string	No	You are a support bot.	Optional system instructions. Supports {variable} placeholders.
User Message	string	Yes	{userMessage}	User message. Supports {variable} placeholders.
Output Variable	string	Yes	reply	Variable name (no braces). Receives the final aggregated reply text.
Chunks Output Variable	string	No	chunks	Optional. Receives the list of streamed text pieces (in order).

If the stream ends without a normal finish (network drop, content filter), the Task fails instead of silently saving a partial reply.

Example: Set Model = gpt-4o-mini, User Message = {userMessage}, Output Variable = reply, Chunks Output Variable = chunks. The Task saves the full reply to reply and the ordered pieces (e.g. ["We open", " Monday to", " Saturday at 8:00."]) to chunks.

OpenAIResponseTask

Calls the newer Responses API. Use when you need built-in tools (web search, file search, code interpreter), server-side conversation memory, reasoning models, or image input.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-4o-mini	Model name supported by the Responses API.
Max Output Tokens	string	No	1024	Optional integer cap.
Input	string	Yes	{userMessage}	Text input. Supports {variable} placeholders.
Image Input URL	string	No	{imageUrl}	Optional. URL of an image to include alongside the text (vision-capable models only).
Conversation ID	string	No	{conversationId}	Optional. Server-side conversation ID (from OpenAICreateConversationTask). Reuses prior turns automatically.
Enable Web Search Tool	bool	No	checked	Allow the model to perform web searches before answering. Default off.
Enable Code Interpreter Tool	bool	No	checked	Allow the model to run Python in a sandbox. Default off.
File Search Vector Store IDs	string	No	{vectorStoreId}	Optional. Comma-separated vector store IDs to enable as the file search tool. Create stores with the OpenAI Files & Vector Stores Module.
Output Variable	string	Yes	reply	Variable name (no braces). Receives the response text.
Response ID Output	string	No	responseId	Optional. Variable name (no braces). Receives the response ID for follow-up calls.

Example: Set Model = gpt-4o-mini, Input = {userMessage}, Enable Web Search Tool = on, Output Variable = reply. When {userMessage} is "What's the weather in Milan today?", the model searches the web first and the Task saves the grounded answer to reply.

OpenAIResponseStreamTask

Streaming variant of OpenAIResponseTask. Collects the reply chunk by chunk into the final text and can also save the ordered chunk list.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-4o-mini	Model name supported by the Responses API.
Max Output Tokens	string	No	1024	Optional integer cap.
Input	string	Yes	{userMessage}	Text input. Supports {variable} placeholders.
Conversation ID	string	No	{conversationId}	Optional. Server-side conversation ID (from OpenAICreateConversationTask).
Output Variable	string	Yes	reply	Variable name (no braces). Receives the final aggregated reply text.
Chunks Output Variable	string	No	chunks	Optional. Receives the list of streamed text pieces (in order).

Example: Set Model = gpt-4o-mini, Input = {userMessage}, Conversation ID = {conversationId}, Output Variable = reply. The Task streams the answer, saves the aggregated text to reply, and the conversation on OpenAI's side remembers this turn.

OpenAIEmbeddingTask

Vectorize text into a float[]. Pair with a downstream similarity-search Task or store in your own vector index.

Property	Type	Required	Example	Description
Embedding Model	string	Yes	text-embedding-3-small	One of text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002.
Input Text	string	Yes	{userMessage}	Text to embed. Supports {variable} placeholders.
Dimensions	string	No	1024	Optional truncation. text-embedding-3-large supports 256 / 1024 / 3072; text-embedding-3-small supports 512 / 1536. Empty → model default.
Output Vector Variable	string	Yes	vector	Variable name (no braces). Receives the float[].

Example: Set Embedding Model = text-embedding-3-small, Input Text = {userMessage}, Output Vector Variable = vector. The Task saves a 1536-element float[] to vector, ready for a downstream similarity comparison.

OpenAIModerationTask

This Task is a gateway: it routes the Token down one of two outgoing branches — flagged when the content violates content policy, clean otherwise. Label the two Sequence Flows after it accordingly.

Property	Type	Required	Example	Description
Model	string	Yes	omni-moderation-latest	Default omni-moderation-latest.
Input Text	string	No*	{userMessage}	Text to classify. Supports {variable} placeholders. Either text or an image input is required.
Image Input URL	string	No*	{imageUrl}	Optional. URL of an image to classify (omni-moderation models only). Either text or an image is required.
Score Output Variable	number	No	maxScore	Variable name (no braces). Receives the maximum category score (0–1).

* Provide at least one of Input Text or Image Input URL.

Example: Set Model = omni-moderation-latest, Input Text = {userMessage}, Score Output Variable = maxScore. A hostile message exits via the flagged Sequence Flow with maxScore ≈ 0.97; a harmless one exits via clean with a score near 0.

OpenAIListModelsTask

Lists every model available to this OpenAI account.

Property	Type	Required	Example	Description
Output Variable	object	Yes	models	Variable name (no braces). Receives a list of entries with id, owned_by, created_at.

Example: Set Output Variable = models. The Task saves the account's model list (entries like {id: "gpt-4o-mini", owned_by: "system", …}) to models.

OpenAICreateConversationTask

Creates a new server-side OpenAI Conversation. Pass the returned conversation ID to OpenAIResponseTask to give the model persistent multi-turn memory without managing message history yourself.

Property	Type	Required	Example	Description
Output Variable	string	Yes	conversationId	Variable name (no braces). Receives the conversation ID.

Example: Set Output Variable = conversationId. The Task saves a new ID such as conv_abc123 to conversationId; pass it as {conversationId} to every OpenAIResponseTask in the same Session.

OpenAIDeleteConversationTask

Deletes a server-side OpenAI Conversation by ID.

Property	Type	Required	Example	Description
Conversation ID	string	Yes	{conversationId}	Conversation ID to delete. Supports {variable} placeholders.

Example: Set Conversation ID = {conversationId} as the last step of a Process that created one — the server-side history is removed when the Session ends.

OpenAICreateContainerTask

Creates a Code Interpreter container that can be reused across multiple Assistant or Responses tool invocations. Returns the container ID.

Property	Type	Required	Example	Description
Name	string	Yes	analysis-box	Display name. Supports {variable} placeholders.
Output Variable	string	Yes	containerId	Variable name (no braces). Receives the container ID.

Example: Set Name = analysis-box, Output Variable = containerId. The Task saves the new container's ID to containerId for reuse by later code-interpreter calls.

OpenAIDeleteContainerTask

Deletes a Code Interpreter container by ID.

Property	Type	Required	Example	Description
Container ID	string	Yes	{containerId}	Container ID to delete. Supports {variable} placeholders.

Example: Set Container ID = {containerId} at the end of the Process that created the container, so it doesn't linger on the account.

Common recipes

Block unsafe messages before they reach the model

Moderate every user message first; only clean content is sent to the chat model. Input and Output Tasks come from the Standard Module.

1. InputTask — Output Variable = userMessage.
2. OpenAIModerationTask — Model = omni-moderation-latest, Input Text = {userMessage}. Label the outgoing Sequence Flows flagged and clean.
3. flagged branch: OutputTask — Message = Sorry, I can't help with that.
4. clean branch: OpenAIChatCompletionTask — Model = gpt-4o-mini, User Message = {userMessage}, Output Variable = reply; then OutputTask — Message = {reply}.

Give a chatbot persistent multi-turn memory

Create one server-side conversation per Session, then let OpenAIResponseTask reuse it on every turn — no history bookkeeping in your Process.

1. OpenAICreateConversationTask — Output Variable = conversationId.
2. InputTask (Standard Module) — Output Variable = userMessage.
3. OpenAIResponseTask — Model = gpt-4o-mini, Input = {userMessage}, Conversation ID = {conversationId}, Output Variable = reply.
4. OutputTask — Message = {reply}; loop back to the InputTask for the next turn. The conversation lives on OpenAI's side, so each turn automatically sees the previous ones.

Best practices

1. Start with gpt-4o-mini — it covers most chat and extraction use cases at a fraction of the cost; switch the Model field to a larger model only when quality demands it.
2. Moderate before you generate — put OpenAIModerationTask in front of user-driven prompts so policy-violating content never reaches the chat model.
3. Use JSON Schema for machine-readable replies — when a later Task parses the reply, set JSON Schema Name + JSON Schema on OpenAIChatCompletionTask instead of asking for JSON in the prompt.
4. Prefer Conversations over prompt-stuffing — for multi-turn memory, pass a Conversation ID to OpenAIResponseTask rather than concatenating history into the User Message.

Troubleshooting

ModuleMissingConfiguration: OpenAI API key is not configured for this environment.

Open the OpenAI Module's Environment configuration for the failing Environment and paste the API key from OpenAI Console → API keys. This also fixes the same error raised by any of the OpenAI satellite Modules — they all read this Module's key.

… is not in '{name}' form

The Task's output field contains a value the platform can't map to a variable. Open the Task in the Process Editor, clear the output field, type the variable name again (no braces), pick its type, and save.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required property is missing or an output field is not a valid variable name — details
4001	ModuleException	OpenAI rejected the request or the call failed unexpectedly — details
4008	ModuleMissingConfiguration	The OpenAI API key is not set in this Module's Environment configuration — details
4009	ModuleInputEmpty	A required input resolved to an empty value at runtime — details
4012	ModuleInvalidData	The Session data could not be read or OpenAI's response could not be processed — details

See the Error Code Reference for the full list.

info

Some OpenAI capabilities used by this family (Assistants, vector stores, batches, the Responses API, and some text-to-speech voices) are still marked beta by OpenAI and may change behavior on OpenAI's side.