OpenAI Tools

Generate and edit images or run background research from Dify workflows, chatflows, and agents.
One OpenAI provider configuration supplies credentials to all tools in this plugin.

Setup

1. Create an API key in the OpenAI Platform.
2. Install the OpenAI tools plugin in Dify and authorize it with the credentials below.
3. Add a tool to your application, configure its model and options, and bind its inputs to workflow variables.
4. Connect image files or research text to your application's output or a subsequent node.

Custom base URLs have trailing slashes removed and appended unless they already end in .
For example, becomes .
Credential validation lists models; successful authorization does not establish access to every model or endpoint.
GPT Image access may require OpenAI organization verification.

Tools

DALL-E 2 and DALL-E 3 remain registered in the plugin, but OpenAI removed both models from its API on May 12, 2026.
Use the GPT Image tools for OpenAI image requests.
See the official deprecation notice.

GPT Image 2 and 2.5

Model selection

Both tools default to .
Choose a GPT Image 2.5 model explicitly in the Model field to use the new models introduced with ChatGPT Images 2.5 on September 8, 2026.

The model selector uses the API model IDs; the snapshot IDs are reference metadata.
The Generate tool sends a text prompt to the Images API, while Edit sends a prompt and image files.
For another editing pass, feed a previous image output into the next Edit call.

Parameters

Custom dimensions must satisfy all of these conditions:

• Width and height are positive multiples of 16, with neither edge above 3840 pixels.
• The aspect ratio is between 1:3 and 3:1.
• The total pixel count is between 655,360 and 8,294,400.

Common sizes include , , and .
Sizes above are experimental.
Transparent backgrounds require PNG or WebP; selecting JPEG with returns a validation error.
Transparent output is supported by both GPT Image 2.5 models and is in preview for GPT Image 2.
For masked edits, use a mask matching the first input image's dimensions, with transparent areas indicating where to edit.
See the image generation guide for input-file requirements and mask behavior.

Example settings for a Generate node:

Outputs and usage

Each generated image is returned as a file with its MIME type.
When OpenAI supplies usage, each file also carries metadata and the tool emits a JSON payload such as:

These token counts are illustrative.
Usage belongs to the entire request, so do not sum the same usage metadata across its image files.
The JSON payload is omitted when the API returns no usage information.

At launch, both GPT Image 2.5 models use the following USD rates per million tokens:

The plugin reports tokens rather than calculating a monetary charge.
GPT Image 2 per-image estimates do not apply to GPT Image 2.5 because token consumption can differ.
Check OpenAI pricing for current rates.

GPT Image 1 tools

GPT Image Generate and GPT Image Edit default to and also offer .
Both accept , , , or sizes; , , , or quality; and 1–10 output images.
Generate additionally exposes background, output format, JPEG/WebP compression, and moderation controls.
Edit accepts reference image files and an optional mask, with output settings determined by the API beyond size and quality.
Both return image files; the separate usage JSON described above is specific to the GPT Image 2 / 2.5 tools.

Deep Research

Deep Research uses the Responses API and always starts tasks in background mode.
Select (the default) or .
The plugin exposes web search and code interpreter, both enabled by default.
Keep web search enabled for OpenAI research requests: it supplies the research source, while code interpreter adds data analysis.
See the official Deep Research guide.

Task lifecycle

1. Call with a research prompt specifying the question, preferred sources, and desired output.
2. Save the returned JSON in a workflow variable or application state.
3. Call with that ID again while the status is or .
4. On , use the tool's text output as the report; handle , , and as terminal statuses.

Each invocation makes one API request; the tool does not automatically poll or wait for a report.
Use with the same ID to request that a running task stop.

Options and outputs

optionally limits tool calls during research.
controls each API request in seconds and defaults to 3600 when unset; it is not a research-task duration limit.
The form also exposes (default ), (default ), and (default ), which are forwarded when supplied and subject to the selected model's API support.

Completed reports are returned as text, with numbered links and a reference list when URL citations are present.
The accompanying JSON contains response metadata rather than the report body: , , , and, when available, , , , , , , , and .
can include web-search actions, code-interpreter activity, and reasoning-summary text.
The top-level field describes the reasoning-summary setting, not a summary of the report.
Failed tasks return JSON with , , and / .
Input validation failures and API request errors may return only a text message, so inspect text output as well as JSON.

Local development

The plugin runner uses Python 3.12.
Install the locked dependencies from the repository root:

Run the OpenAI tool regression checks:

The tests mock API calls and do not generate billable images or research tasks.
Dependency constraints live in pyproject.toml, resolved versions in uv.lock, and plugin release metadata in manifest.yaml.