OpenAI Chat

Chat with OpenAI models using the Responses API.

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.

Category: AI
Tool Name: openai_chat
Version: 1

Appearance: Icon: openai | Color: #10a37f

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.
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.
• 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 }}.

Usage Examples

• Send a prompt to an OpenAI model and get a text response
• Summarize text using OpenAI with a system prompt
• Translate content with a low temperature for consistent output
• Generate product descriptions from input data
• Ask a question for each row in a dataset

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 sends each input item to an OpenAI language model via the Responses API and returns a generated text completion. Use it when your workflow requires text generation, summarization, classification, or reasoning tasks powered by configurable OpenAI models. Each output item contains the completion text in a configurable field name, along with the model identifier and token usage metadata.