Why Dify's OpenAI Responses API setting matters after an upgrade
Dify 1.16.0 changed the default API type for new OpenAI configurations from Chat Completions to Responses. Existing configurations do not change with it. A saved custom key keeps the Chat Completions default it was created with, so a team that upgraded and saw nothing break may still have an OpenAI-backed app pointed at the older interface. The failure tends to appear later, when someone selects a newer GPT model for an app or workflow that was built on an older one. Dify's release notes say that users with a custom key saved under the old default should switch to Responses, especially for GPT-5.6 or later models. Teams should read the Dify releases page for the upgrade notes of each version they run, not only the version they are moving to.
This matters most for platform teams that run several OpenAI-backed apps across workspaces and did not create every key themselves. You need this page if you upgraded a self-hosted Dify to 1.16.0 or later, if any saved OpenAI key predates that upgrade, or if a team has asked to move an app to a newer GPT model. It is also relevant when apps were built against Chat Completions behavior and may depend on fields that the Responses interface handles differently. Confirm which API type each saved key uses before you change any model, because the setting belongs to the saved credential, not to the individual app.
The check is inexpensive compared with a production incident in a customer-facing workflow. Inventory each OpenAI provider configuration in every workspace, record its API type, and test one representative app on a newer model in a non-production environment before you switch. Keep a backup before the change, as Dify's upgrade guidance recommends for any change of this kind. Where an app fails after the switch, treat the result as a compatibility finding for that app and test it again, rather than assuming the setting alone resolves every problem.
Which API type fits which OpenAI model and configuration
Many teams saved an OpenAI API key in Dify before the default changed. If that key was created with the earlier default, Dify keeps the Chat Completions API type after an upgrade, because the setting was stored with the credential rather than recalculated from the new default. Nothing fails loudly on upgrade, so the first symptom is often an application that stops responding when someone selects a newer model.
- Identify the saved state: Open the OpenAI provider settings in the workspace and note which API type the saved custom key uses.
- Confirm the Dify version: Check the running version against the Dify 1.16.0 release notes to confirm the default change applies to your upgrade path.
- List dependent apps: Find every app and workflow that selects an OpenAI model through this key, since they all share its configuration.
- Keep a copy of the old setting: Record the current configuration before editing so you can revert if an application depends on Chat Completions behavior.
- Test in a non-production workspace first: Switch the type on a copy of the key and run representative prompts before applying it to production.
Before changing a production key, confirm which API type each dependent app expects and rerun its test cases afterward.
The Dify release notes single out GPT-5.6 or later models as the main reason to switch a key to Responses. Teams running these models through Dify should treat the Responses type as the expected configuration for them rather than an optional tuning step. Model availability is controlled by your OpenAI account and region, not by Dify alone, so the model list you see depends on what your organization has enabled.
- Match the model to the type: For GPT-5.6 or later models, plan to configure the key with Responses and verify the model appears and responds.
- Check account enablement: Confirm in your own OpenAI account that the target model is available to the project that owns the key.
- Check Dify version support: Confirm that your installed Dify version lists the model in the OpenAI plugin before relying on it.
- Review parameters: Recheck temperature, token limits and tool settings in each app, since behavior can differ between API types.
- Keep older models on a separate key if needed: Where some apps must stay on Chat Completions, use a separate credential instead of mixing types on one key.
Confirm model support in your OpenAI account and Dify version before you change the type for any production app.
Chat Completions remains the configuration many existing apps were built and tested against. If your applications rely on its request and response shape, or if a model you use is not yet working through Responses in your version, keeping Chat Completions for that key may be the lower-risk choice. The decision should follow from tested behavior in your own apps rather than from habit.
- Keep stable apps unchanged: Apps in production that work today do not need a type change just because a newer default exists.
- Isolate by credential: Use distinct keys for apps that stay on Chat Completions and apps that move to Responses, so the two can be managed separately.
- Document the reason: Record which apps and models depend on Chat Completions and why, so future upgrades do not switch them silently.
- Re-evaluate on upgrade: Review this list each time you upgrade Dify, using the release notes for the target version.
- Plan the eventual move: Schedule a test cycle before any model you use is retired or changed by its provider.
Before leaving a key on Chat Completions, confirm in your own environment that the models it serves still respond as expected.
Switching the API type is a configuration change with downstream effects on every app that uses the key. Treat it like any other credential change: scope it, test it, record it and be ready to roll back. Dify's app management documentation and export features help here, because app configuration and model parameters can be reviewed before and after the change, although third-party API keys are not included in exports.
- Inventory consumers: List each app, workflow and API integration that references the key or the model it serves.
- Test representative cases: Run prompts that cover normal inputs, tool calls and long contexts, and compare outputs before and after.
- Check error handling: Confirm how each app reports a failed model call, so an incompatibility shows up in monitoring.
- Plan rollback: Keep the previous configuration recorded so you can restore it quickly.
- Take a backup first: Follow the upgrade guidance to back up before changing configuration that affects many apps.
Ask your Dify administrator and application owners to sign off on the test results before the switch reaches production.
How to switch a saved OpenAI configuration to Responses
This sequence moves a saved OpenAI provider configuration from the Chat Completions API type to Responses, so apps that use newer GPT models can call them without failing. It ends with a confirmed model list and a successful test run on the affected app.
Back up the Dify instance first
The platform team takes a backup of the metadata database and the file storage before changing any provider settings, following the backup approach in your Dify deployment runbook. Dify's Docker Compose upgrade guidance recommends a backup before every upgrade, and the same caution applies to a configuration change. Done means the team can name the backup location and has confirmed it can be restored in a non-production environment.
Identify the running Dify version
The operator confirms the deployed Dify version from the console or the image tag in the Compose file. The default API type change for new OpenAI configurations landed in Dify 1.16.0, so a version at or above that release is the first condition for this fix. Done means the team has written down the exact version and knows whether any saved OpenAI key predates the upgrade. Confirm the version in your own environment against the Dify releases page before deciding.
Open the OpenAI provider configuration
An administrator with permission to manage model providers signs in to the workspace, opens the model provider settings, and selects the OpenAI entry. Note the saved key's name and the API type currently shown, since a key saved under the older default keeps Chat Completions until someone changes it. Done means the configuration panel displays the stored key status and the current API type without an error banner.
Change the API type to Responses
In the OpenAI configuration, the administrator changes the API type from Chat Completions to Responses and leaves the key unchanged unless the key itself is being rotated. Dify 1.16.0 release notes say users who saved a custom key under the old default should switch, especially for GPT-5.6 or later models. Done means the field reads Responses before saving, and no other provider settings were changed in the same edit.
Save and confirm the model list loads
The administrator saves the configuration and waits for the provider to refresh its model list. A successful save shows the OpenAI models the key can access, including the target model, without a validation error. If the list is empty or shows an authentication message, the key or the account's model access is the likely cause, so check the key with the provider before changing anything else. Done means the target model appears in the model selector.
Test the affected app with the target model
The app owner opens the app that uses the newer model, selects the target model in its model settings, and sends a short test prompt that matches a typical request. The output should return without a provider error in the debug or preview panel, and the app's logs should show a completed call. Done means the owner has recorded the test prompt, the model name, and the result, and has checked any workflow nodes that also call OpenAI.
Check other saved OpenAI keys after the upgrade
Before closing the change, the operator reviews every OpenAI key saved in the instance, including keys for development, staging and production, and any custom model keys. Each one saved under the old default should be checked for its API type and tested against the models it serves. Done means a short inventory lists each key, its API type, and the test result, and the list is stored with the change record.
Protecting OpenAI keys and changes during the switch
Changing the API type touches a stored credential, the settings that protect it, and the record of who changed what. The four controls below keep the switch contained and give the next upgrade a clear starting point.
Store the OpenAI key only in Dify's provider settings
Enter the OpenAI key through the model provider settings so Dify stores it encrypted in its database, rather than in a .env file, a workflow variable or an exported DSL. Confirm that your DSL exports leave out third-party API keys, then check that no team has pasted the key into prompts, notes or tickets. Keep one key per environment so a leaked development key cannot reach production traffic.
Restrict who can edit provider configurations
Changing the API type or replacing a key is a production change, so limit provider edits to a small group of workspace administrators. Review workspace member roles before the switch and remove editor access that is no longer needed. Ask whether your Dify edition gives you role separation beyond the Community workspace model, since that determines how narrow the group can be.
Plan around SECRET_KEY before touching encryption settings
SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, and changing it after deployment logs out all users. Do not rotate it as part of the API type switch. Back up the environment file and the database before any change, and confirm that the key you rely on is stored in your secrets system, not only on one host.
Verify SSRF and outbound paths after the change
The OpenAI call leaves your network through the outbound path Dify uses. Confirm that SSRF_PROXY settings still route requests as intended after the upgrade, and that the Responses endpoint is reachable from the API container. Record the egress destination you approved so a reviewer can see that the switch did not open a new route to an external service.
Record the change in the upgrade log
Write down the date, the Dify version, the provider and key label (never the key value), the old and new API type, and the name of the person who made the change. Note which custom keys you reviewed and which apps you tested with GPT-5.6 or later models. This record lets an auditor or a future upgrade team trace why a provider behaves as it does.
Test each app before closing the change
Run a saved test prompt through every app that uses the OpenAI provider, including workflows that call it from a knowledge base or agent step. Check that errors do not appear in the logs and that outputs match the approved baseline. Keep the test results with the upgrade record so the switch can be shown to be complete.
How to check existing custom keys after a Dify upgrade
How do I find every OpenAI custom key saved in my Dify instance?
Start by listing every workspace on the instance, then open the model provider settings in each one and record each saved OpenAI credential. Include keys that were added as custom models, because those are easy to miss when you only look at the default provider card. Keep the list in your change record with the workspace name, the credential label, and the date it was last edited. Dify Community is limited to a single workspace, so on that edition the list is shorter, but the same check applies to the one workspace you run.
Why does the API type on a saved OpenAI key matter after an upgrade?
Dify 1.16.0 changed the OpenAI plugin's default API type for new configurations from Chat Completions to Responses. A key saved earlier with the old default keeps Chat Completions, and that setting does not change when you upgrade. Newer GPT models, especially GPT-5.6 or later according to the Dify 1.16.0 release notes, are the ones most likely to fail under the old setting. Record the API type for each key so you know which ones need to be switched to Responses and retested.
How do I confirm which apps depend on each OpenAI model?
Open each app in each workspace and note the model name and provider it uses, including the reasoning model, any tool or agent nodes, and workflow nodes that call an LLM directly. Apps and workflows can point to a key through a model setting that is easy to overlook, so check the workflow canvas, not only the app overview. Export the app as a DSL file when you need a repeatable record, but remember that exports omit third-party API keys, so the credential mapping must be documented separately.
What should I retest after switching a key to the Responses API type?
Retest each app that uses the key with a fixed set of prompts that cover the behaviors your users rely on, such as plain answers, structured output, tool calls and long inputs. Run the same prompts before and after the change and compare outputs and error messages. Include workflows that run on a schedule or through the service API, because those may not be exercised in the console. Keep the prompt set and results with the change record so the next upgrade can reuse it.
How often do Dify minor releases arrive, and how should that shape my review?
According to the Dify releases page on GitHub, minor releases arrive roughly monthly. Dify 1.16.0 was released on July 17, 2026, 1.17.0 on August 25, 2026, and 1.17.1 on September 10, 2026. Plan the key review as a recurring step tied to each minor release, not a one-time task. Read the release notes for changes to model providers, default settings and security behavior before you schedule the upgrade window.
What do I back up and check before every Dify upgrade?
The Dify Docker Compose documentation recommends a backup before every upgrade, and it asks you to follow the upgrade guide for the target version on the GitHub Releases page. Back up the PostgreSQL database, the file storage used for uploads and knowledge base files, and your .env file. After the upgrade, compare your .env with .env.example for new variables and set any that the release requires. Confirm the exact backup scope for your deployment with your own runbook, since storage layout depends on how you configured it.
Can my own team run this review, or do we need a partner?
Your team can run this review if it has someone who can read the Dify console, the release notes and the Compose configuration, and if it has test prompts that reflect real use. The work is mostly inventory, mapping and regression testing, so the effort scales with the number of workspaces, keys and apps. A partner adds value when many workspaces or regulated workflows are involved, or when you want a written scope and a repeatable routine. DeployOpen plans and runs this kind of upgrade review as a fixed-scope engagement or a retainer, and it can prepare the evidence your change process needs.
Should I rotate keys or change them when I switch the API type?
Switching the API type does not require a new key in most cases, but you should confirm that with the credential form and your provider account before you edit production. Rotation is a separate decision driven by your key management policy and any exposure concern. If you do rotate, update every app and workflow that references the credential, then retest, because a rotated key may still carry the old API type setting. Keep rotation and API type changes in separate change records so a failure is easy to trace.
Limits to confirm in your own environment
The Responses API switch is not a universal fix, and its outcome depends on several moving parts in your deployment. Each card below names one thing to verify, so you can confirm the behavior against the Dify release notes and OpenAI documentation before you change production configurations.
Your Dify version
The default change for new OpenAI configurations arrived in Dify 1.16.0, so an instance on an earlier release may behave differently from the notes you read. Check the version your api and worker containers actually run, not only the tag in your compose file. Then read the release notes for that exact version, and for any later patch, before you decide whether a saved custom key needs changing. Record the version in your change ticket so the decision can be reproduced.
Models your OpenAI account can call
Access to newer GPT models depends on your organization, project, tier and region, not on Dify. Test each model you plan to use with a key from the same project and endpoint your Dify instance will use, because a model listed in a catalog may still be unavailable to your account. Confirm which API surfaces each model supports in OpenAI's current documentation, since a model may support one endpoint and not the other.
Tools and structured outputs
Responses and Chat Completions handle tool calls, function schemas and structured output formats differently. A workflow that depends on a specific tool call pattern or JSON output shape can change behavior after a switch, even when the basic chat reply looks correct. Run each workflow with its real tools and output parsers, and compare results and error handling before and after the change.
Gateways and other providers in front
If requests pass through a proxy, an AI gateway or a compatible endpoint before reaching OpenAI, that layer may not support the Responses API or may translate requests in its own way. Confirm which endpoint path your gateway forwards, and whether it rewrites headers or model names. Also check whether apps use other providers, since a workspace default change can affect them too.
Saved keys and existing apps
Keys saved under the old default keep their original API type, so an upgrade alone may not change them. Inventory every saved OpenAI configuration across workspaces, note which apps use each one, and record the API type before editing anything. Export affected apps as DSL files first, because DSL exports do not include third-party API keys and you will need to re-enter or confirm them.
Questions teams ask before fixing the OpenAI API type
How much effort does switching the OpenAI API type take?
For a single saved key and a handful of apps, the change itself is small: open the OpenAI provider settings, switch the API type from Chat Completions to Responses, and test each app that depends on that key. Effort grows with the number of saved keys, the number of apps that call them, and how many environments must be retested. Most of the time goes into finding which keys were saved under the old default and confirming that each app still returns correct output after the switch. Ask a partner to estimate the effort from a written inventory of keys, apps and environments rather than from the change itself.
Can our own team fix the OpenAI API type without a partner?
Yes, if one engineer can access the Dify console with admin rights, can see the model provider settings, and has a test plan for each app. The switch is a configuration change in the console, not a code change. A partner adds value when many workspaces, custom keys or regulated change control are involved, because they can produce the inventory, the test evidence and the rollback notes in one pass. Your team should decide early which of those documents it must keep for internal review.
What does the team need to provide before the work starts?
The team needs console access for the Dify instance, a list of workspaces and the people who manage model providers, and a named owner for approving changes. It should also provide a list of apps that call OpenAI models, the models each app uses, and a set of test prompts with expected outputs. Access to a non-production Dify instance matters because it lets you test the switch before production. Confirm these items with your partner and your change board before the scope is signed.
What is a one-time task and what recurs after an upgrade?
The first review of saved OpenAI keys is one-time work, along with the test plan and the record of which keys changed. Recurring work appears after upgrades. Dify 1.16.0 changed the default API type for new OpenAI configurations, so each upgrade past that release should include a check that existing custom keys still use the intended type. Dify's upgrade guidance recommends a backup before every upgrade and a review of .env.example for new variables. Ask a partner whether the upgrade checks are included in a fixed scope or offered as a retainer.
Which factors make this work take longer?
The main drivers are:
- The number of saved OpenAI keys, including custom keys created under the old default.
- The number of apps and workflows that call each key, and whether any app runs in production.
- The depth of testing, from a smoke test of one prompt to regression tests for each app's outputs.
- The number of environments, such as development, staging and production, and whether each has its own keys.
Each driver multiplies the test and sign-off work, so a written inventory is the most useful input for an accurate quote.
What should we ask a partner to include in a written scope?
Ask the partner to state the following in writing:
- The inventory method and the list of keys, apps and environments in scope.
- The test cases for each app, the pass criteria, and who signs off.
- The change steps, the rollback steps, and the backup taken before the change.
- Whether upgrade checks for later Dify releases are included, and for how long.
- Who makes which changes, and what the client must provide.
A fixed scope with these items makes the quote comparable and the handover clear.
Does changing the API type expose keys or data?
The API type setting changes how Dify calls the OpenAI service, and it does not by itself change where keys are stored. Keys remain in the Dify instance you run, so the main security questions are who can view or edit provider settings and whether the secret key and backups are protected. Dify's environment reference explains that its secret key encrypts stored OAuth credentials, so changing it later logs out users and affects stored data. Confirm your key storage and access controls with your security team before the change, and keep the test results for your records.
Where can we read the official steps before deciding?
Start with the Dify 1.16.0 release notes on the GitHub releases page, which explain the change to the OpenAI plugin's default API type for new configurations. Then read the Dify FAQs and app management documentation to confirm how to edit saved provider settings in your version. Check your own version number before reading the notes, because later releases may change the console. If the steps differ in your instance, confirm them with your partner or with Dify support before making changes.
How DeployOpen scopes and supports Dify OpenAI configuration work
DeployOpen is a Chainscore Labs company that plans, implements and supports self-hosted Dify inside your own cloud accounts, data centers or air-gapped networks. For a change like the OpenAI API type switch, that means the work covers your real saved configurations, not a generic setting change. A typical engagement starts with an inventory of which OpenAI provider entries, custom model keys and workflow nodes exist in each workspace, which apps depend on them, and which Dify version each environment runs. The output is a written scope that names the workspaces, the models in use and the verification steps, agreed before any change is made to a production instance.
Most of this work is fixed-scope, so the quote follows from that written scope rather than from an open-ended hourly estimate. The main cost drivers are the number of workspaces and saved keys to review, how many apps need retesting after the switch, whether non-production environments are included, and how much change control your organization requires. Ask any partner, including DeployOpen, to state which of these are included, what evidence they produce for your change records, and what happens if a check finds a configuration that needs more work. Confirm your own internal review and approval steps too, since those add time that no vendor can estimate for you.
Dify upgrades arrive about monthly, so a one-time fix is rarely enough. DeployOpen can run ongoing upgrade checks as a retainer, covering release notes review, .env.example comparison, provider configuration checks and regression tests of key workflows before each version reaches production. Retainers are useful when your team does not have an owner for model provider configuration. Confirm with any provider exactly which release channels, environments and response times are covered, and whether the retainer includes testing against the model endpoints you actually use.
