OpenAI Chat

Overview

OpenAI Chat uses the Responses API (POST /responses) to generate text completions from OpenAI language models. Supports configurable model selection, system prompts, temperature, top-p, frequency/presence penalties, and max output tokens. Each input item receives a separate completion. The response text is placed in a configurable field name in the output JSON, along with model and usage metadata.

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires OpenAI credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Model	options	No	(current default)	The OpenAI model to use for chat completion. Always uses the latest version (auto-updated).
				Options: the OpenAI chat models available to your workspace — pick one from the dropdown.
System Prompt	string	No	You are a helpful assistant.	System instructions that set the behavior and persona of the model. Defaults to a generic helpful-assistant prompt — override per workflow as needed. Supports expressions.
User Message	string	Yes	—	The user message or prompt to send. If empty, falls back to item.json.message or item.json.prompt. Supports expressions.
Attachment File ID	string	No	—	Optional OpenAI file ID (file-…) returned by openai_file_upload. When provided, the file is referenced by ID and attached as a content block on the user message — no re-upload, no binary input needed. Falls back to item.json.attachmentFileId if empty. Supports expressions like {{ $json.fileId }} from an upstream openai_file_upload node.
Attachment Type	options	No	document	How the model should interpret the attached file. Only used when Attachment File ID is set.
				Options: document (PDF / text / code / CSV / structured file), image (jpg / png / gif / webp)
Options	collection	No	{}	Optional model-tuning settings — add only the fields you need.
— Temperature	number	No	1	Sampling temperature (0-2). Lower values make output more focused and deterministic.
— Max Output Tokens	number	No	4096	Maximum number of tokens the model can generate in the response.
— Top P	number	No	1	Nucleus sampling: only consider tokens with top_p cumulative probability (0-1).
— Frequency Penalty	number	No	0	Penalize tokens based on how frequently they appear in the text so far (-2 to 2).
— Presence Penalty	number	No	0	Penalize tokens based on whether they have appeared in the text so far (-2 to 2).
— Response Field Name	string	No	response	Field name in the output JSON where the response text will be placed.
Include Input	boolean	No	false	Whether to include the original input item fields in the output alongside the response.
Web Search	boolean	No	false	Enable OpenAI’s built-in web search. When on, the model may search the web before answering and returns cited sources in the sources output field.
Search Context Size	options	No	medium	How much web search context to give the model. Only used when Web Search is on. (shown when Web Search is on)
				Options: low (fastest, cheapest, fewer sources), medium (balanced default), high (more sources and detail, slower)
Search User Location	collection	No	{}	Optional approximate user location that biases search results. Leave empty for no localization. (shown when Web Search is on)
— Country	string	No	—	Two-letter ISO 3166-1 alpha-2 country code.
— City	string	No	—	Free-text city name.
— Region	string	No	—	Free-text region or state name.
— Timezone	string	No	—	IANA timezone identifier.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item. The reply text lands on the field named by Response Field Name (response by default), with model and usage beside it. The rest of the input item JSON is dropped unless Include Input is on; binary data on the input item is forwarded unchanged.

{
  "response": "The generated reply text",
  "model": "the model that produced the reply",
  "usage": { "input_tokens": 128, "output_tokens": 256 }
}

• usage is the token accounting returned by the API for that call.
• sources is always present: an array of cited results when Web Search is on, and an empty array when it is off. Each entry carries url and title, plus snippet when OpenAI supplies citation offsets.
• Turning on Include Input merges the original item fields into the same object, so make sure your response field name does not collide with an incoming field.

Reference the result downstream by expression, e.g. {{ $json.response }}.

Example Configuration

Ask a question with the default model and system prompt:

{
  "type": "openai_chat",
  "parameters": {
    "userMessage": "Explain what a Bloom filter is in two sentences."
  }
}

Classify each item deterministically and keep the original fields:

{
  "type": "openai_chat",
  "parameters": {
    "systemPrompt": "Classify the sentiment of the text as POSITIVE, NEGATIVE, or NEUTRAL. Reply with one word only.",
    "userMessage": "{{ $json.review }}",
    "includeInput": true,
    "maxConcurrency": 20,
    "options": {
      "temperature": 0,
      "maxOutputTokens": 8,
      "responseFieldName": "sentiment"
    }
  }
}

Ask about a file uploaded by an upstream OpenAI File Upload node:

{
  "type": "openai_chat",
  "parameters": {
    "userMessage": "Summarize the key terms in this contract.",
    "attachmentFileId": "{{ $json.fileId }}",
    "attachmentType": "document",
    "options": {
      "temperature": 0.2,
      "responseFieldName": "contractSummary"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

OpenAI Chat generates text completions from OpenAI language models using the Responses API. This tool is ideal for tasks requiring text generation, summarization, classification, or reasoning, offering configurable model selection for diverse needs. It produces output items containing the completion text in a specified field, along with model and token usage metadata.