OpenAI Module

The core of the OpenAI family: chat completions, the Responses API, embeddings, moderation, model listing, conversations, and containers.

The Module connects to OpenAI on your behalf. Set the API key in this Module's Environment configuration and every Task in this Module uses it automatically. The six OpenAI satellite Modules are configured separately each has its own API key field in its own Environment configuration, so you can paste the same key into each or give each capability a dedicated key.

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 Agents agents that call your Process: each function a branch, typed parameters, conversation memory (replaces OpenAI Assistants, shut down by OpenAI on 26 August 2026).
• 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.

Each Module in the family is configured separately every satellite has its own required API key in its own Environment configuration. You can paste the same key into each Module or give each capability a dedicated key.

What you can build

• Chatbots, FAQ agents OpenAIChatCompletionTask, OpenAIResponseTask.
• Content safety pipelines OpenAIModerationTask branches "flagged" / "clean" before downstream LLM Tasks run.
• Classify or extract a whole list in one step OpenAIBulkChatCompletionTask runs one completion per row (several at a time) and returns the answers as records, in list order.
• 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 OpenAI 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 (Agents, 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.

OpenAI 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 securely.

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.

Batch and fine-tuning events are verified with the Webhook Signing Secret of the OpenAI Batch & Fine-tuning Module when it has one, and with this secret otherwise. A webhook resumes the Session waiting on the resource named in the event's data.id (the batch or job ID); an event without data.id is accepted and ignored.

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-6-luna	Chat model name, e.g. gpt-6-luna (default), gpt-5.6-terra, gpt-6-sol. The reasoning models (gpt-5.5 and later) take no temperature, top p, penalties or stop sequences: the Task then sends the request without them, with a warning. A model OpenAI has retired runs on its named replacement, with a warning.
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).
Files	file field	No	ref-session:{email.attachments}	Optional. Files the model reads with the message: ref-session:{email.attachments} (every attachment of an email), ref-session:{email.attachments.0}, ref-storage:invoice.pdf. PDFs (scanned ones too) are sent as documents, images as images, inline with the request. Up to 10 files, 20 MB each, 32 MB in total. Combine with JSON Schema to extract structured data in one step.
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, or an empty file), ModuleInvalidInput (Files: unknown variable, too many files, a file or the total too large), ModuleInputNotInSession (a file is gone), ModuleException (OpenAI rejection).

Example: read an invoice PDF from an email. Set User Message = Extract the invoice data., Files = ref-session:{email.attachments}, JSON Schema Name = Invoice, JSON Schema = {"type":"object","properties":{"number":{"type":"string"},"total":{"type":"number"}},"required":["number","total"],"additionalProperties":false}, Output Variable = invoice. The model reads every attachment (scanned PDFs included) and the Task saves e.g. {"number":"F-42","total":12.0} to invoice.

Example: Set Model = gpt-6-luna, 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}.

OpenAIBulkChatCompletionTask

One chat completion per row of a list, several rows at a time, inside one step. Use it to classify or extract fields from 20–500 records (support cases, emails, spreadsheet rows) without a loop in the Process and without waiting hours for the Batch API. The answers come back in the order of the list.

Property	Type	Required	Example	Description
Rows	string	Yes	{cases}	The variable holding the list, one model call per row: the rows of Query file (Variables get: All rows), the records of Query records, or a JSON array. At most 500 rows.
Each row as	string	No	{row}	The name a row takes while its prompt is built, so the messages read {row.subject}. Default {row}. Records of Query records keep their values under fields: {row.fields.subject}.
Rows at a time	number	No	5	Rows sent to OpenAI at the same time, 1–10 (default 5). Lower it if your OpenAI account hits its rate limit.
System Prompt	string	No	You classify FedEx cases.	The same instructions for every row. Supports {variable} and {row.…} placeholders.
User Message	string	Yes	Subject: {row.subject}	The message sent for each row. A row whose message comes out empty fails without a call.
Model, Temperature, Max Output Tokens				As in OpenAIChatCompletionTask, applied to every row. A reasoning model that refuses temperature runs without it, with one warning.
JSON Schema Name, JSON Schema	string	No	Case	Structured output for one row's answer. With both set, every answer is stored as a record, not as text.
Copy from the row	string	No	caseNumber	Fields of the row copied into each record answer (a nested field fields.caseNumber is copied as caseNumber), so the answers can be saved or matched without asking the model to repeat them.
Store the result in	string	Yes	{result}	Receives the result described below.
Seconds per call	number	No	120	Advanced. How long one model call may take (1–600, default 120). Waiting out a rate limit does not count.

The result holds total, ok, failed, answers (the answers of the rows that worked, in list order), items: one entry per row with index (from 0), ok, answer, error and rateLimited, and rateLimited / rateLimitedRows: how many rows OpenAI's rate limit kept from an answer, and those input rows as they were. With a JSON schema, {result.answers} is a list of records that Add rows (Source = Variable) appends as it is, and {result.items.3.answer.scenario} reads one field.

A row that fails (OpenAI refuses it, it times out, or its answer is not valid JSON under a schema) is recorded in items with its error and the other rows go on; the step logs a warning per failed row (the first 10) and takes its error exit only when no row got an answer. OpenAI server errors (5xx) are retried with backoff by the OpenAI client before a row counts as failed. The whole step's calls stop after 15 minutes; rows not started by then are recorded as not run.

Rate limits. OpenAI limits each account by requests and tokens per minute, per model (see OpenAI → Settings → Limits). When a call gets a 429 rate limit, the Task pauses every row for as long as OpenAI asks (its retry-after or x-ratelimit-reset-* headers, at most 60 seconds at a time; 1, 2, 4… seconds when it doesn't say), then tries that row again, up to 8 times. A row still refused after that (or when the 15 minutes run out during a pause) is marked rateLimited and listed in {result.rateLimitedRows}: send that list to a second Bulk chat completion (later, or with fewer Rows at a time) to finish the job. The run log says how often the limit was hit and how long the rows paused. A 429 for an exhausted quota (insufficient_quota: no credit left) is not waited for: the rows not yet sent fail at once with that reason, and are not marked rateLimited.

Failure modes: ModuleMissingConfiguration, TaskInvalidData (model, user message, rows not one {variable} or not a list, more than 500 rows, rows at a time or seconds per call out of range, JSON schema not valid JSON, result variable), ModuleInputEmpty (the rows variable has no value), ModuleException (no row got an answer).

Example: classify support cases. Rows = {cases}, System Prompt = Classify the FedEx support case. The text may be in English, French or Italian., User Message = Subject: {row.subject} + new line + Description: {row.description}, JSON Schema Name = Case, JSON Schema = {"type":"object","properties":{"awb":{"type":"string"},"email":{"type":"string"},"scenario":{"type":"string","enum":["lack-of-tracking","clearance","customer-unreachable","address-correction","delivery-reattempt","return-to-shipper","non-receipt","other"]}},"required":["awb","email","scenario"],"additionalProperties":false}, Copy from the row = caseNumber, Store the result in = {result}. A following Add rows with Source = Variable and {result.answers} writes one line per case with caseNumber, awb, email and scenario.

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-6-luna	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-6-luna, 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, image or file (PDF) input, or JSON-schema structured output.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-6-luna	Model name supported by the Responses API.
Max Output Tokens	string	No	1024	Optional integer cap.
Instructions	string	No	Answer in two sentences.	Optional system / developer instructions: how the model should behave. Supports {variable} placeholders.
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).
Files	file field	No	ref-session:{email.attachments}	Optional. Files the model reads with the input (ref-session:{…}, ref-storage:…): PDFs (scanned too) as input_file, images as images, inline. Up to 10 files, 20 MB each, 32 MB in total.
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.
Container ID	string	No	{containerId}	Shown with Code interpreter. Optional. A container made by OpenAICreateContainerTask, so files and state carry over between steps. Empty: OpenAI creates a fresh container for the call.
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.
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 (sent as the Responses API text.format).
Output Variable	string	Yes	reply	Variable name (no braces). Receives the response text (the JSON text when a schema is set).
Response ID Output	string	No	responseId	Optional. Variable name (no braces). Receives the response ID (resp_…), for your logs or to find the call in the OpenAI dashboard.

Example: Set Model = gpt-6-luna, 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.

When OpenAI ends the stream with a failure (response.failed), an incomplete answer (response.incomplete, for example the Max Output Tokens cap was reached) or a stream error, the Task takes the error exit and the session log gives OpenAI's reason.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-6-luna	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).
Response ID Output	string	No	responseId	Optional. Receives the response ID (resp_…), also when the response failed.

Example: Set Model = gpt-6-luna, 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, a choice that follows the model: text-embedding-3-large offers 256 / 1024 / 3072, text-embedding-3-small 512 / 1536, text-embedding-ada-002 only its default. Model default when empty.
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 Responses calls (set it as Container ID on OpenAIResponseTask). 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-6-luna, 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-6-luna, 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-6-luna 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 or OpenAIResponseTask 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. If the error comes from one of the OpenAI satellite Modules, open that Module's own Environment configuration instead each Module in the family has its own API key field.

… 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
4010	ModuleInputNotInSession	A file named in Files could not be read (it is gone) details
4011	ModuleInvalidInput	Files names an unknown variable, too many files, or a file / total over the size limit 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 (vector stores, batches, conversations, and some text-to-speech voices) are still marked beta by OpenAI and may change behavior on OpenAI's side.