Azure OpenAI Cognitive Services endpoint: Responses API does not append ?api-version=, cannot use gpt-5.x-codex models

Description

Summary:

When using OpenCode with Azure OpenAI Cognitive Services endpoints (i.e. https://<resource>.cognitiveservices.azure.com/openai), the Responses API (/responses) requests are missing the required ?api-version=... query parameter. This causes all requests to /openai/responses to return 404, even though the same endpoint works with tools like curl.

Impact:

Cannot use models that require the Responses API (e.g. gpt-5.2-codex) on Azure Cognitive Services endpoints.
Azure returns 404 Resource not found when ?api-version= is missing from the request URL.
The same request succeeds via curl when ?api-version=2025-04-01-preview is included manually.

Working curl example:

curl -X POST "https://<resource>.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $AZURE_API_KEY" \
    -d '{
        "messages": [{"role": "user", "content": "hello"}],
        "max_completion_tokens": 16384,
        "model": "gpt-5.2-codex"
    }'

Config attempts and results:

Attempt 1: Standard @ai-sdk/azure with resourceName

{
  "provider": {
    "azure": {
      "npm": "@ai-sdk/azure",
      "options": {
        "apiKey": "<REDACTED>",
        "resourceName": "<REDACTED>",
        "apiVersion": "2025-04-01-preview"
      },
      "models": {
        "gpt-5.2-codex": {
          "name": "GPT 5.2 Codex",
          "provider": { "npm": "@ai-sdk/azure" }
        }
      }
    }
  }
}

Result: SDK constructs URL with .openai.azure.com hostname (wrong — Cognitive Services uses .cognitiveservices.azure.com), and hits /v1/chat/completions instead of /responses. Error: The chatCompletion operation does not work with the specified model, gpt-5.2-codex.

Attempt 2: @ai-sdk/azure with baseURL override

{
  "provider": {
    "azure": {
      "npm": "@ai-sdk/azure",
      "options": {
        "apiKey": "<REDACTED>",
        "baseURL": "https://<resource>.cognitiveservices.azure.com/openai",
        "apiVersion": "2025-04-01-preview"
      },
      "models": {
        "gpt-5.2-codex": {
          "name": "GPT 5.2 Codex",
          "provider": { "npm": "@ai-sdk/azure" }
        }
      }
    }
  }
}

Result: URL hits /openai/responses (correct path) but ?api-version= query parameter is dropped. Error: 404 Resource not found.

Attempt 3: @ai-sdk/openai with api URL including query param

{
  "provider": {
    "azure": {
      "api": "https://<resource>.cognitiveservices.azure.com/openai?api-version=2025-04-01-preview",
      "npm": "@ai-sdk/openai",
      "options": {
        "apiKey": "<REDACTED>",
        "headers": {
          "api-key": "<REDACTED>"
        }
      },
      "models": {
        "gpt-5.2-codex": { "name": "GPT 5.2 Codex" }
      }
    }
  }
}

Result: SDK appends /responses after the query string, producing a malformed URL: https://<resource>.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview/responses. Error: 404.

Attempt 4: @ai-sdk/openai with clean api URL (no query param)

{
  "provider": {
    "openai": {
      "api": "https://<resource>.cognitiveservices.azure.com/openai",
      "npm": "@ai-sdk/openai",
      "options": {
        "apiKey": "<REDACTED>",
        "headers": {
          "api-key": "<REDACTED>"
        }
      },
      "models": {
        "gpt-5.2-codex": { "name": "GPT 5.2 Codex" }
      }
    }
  }
}

Result: URL hits /openai/responses (correct path) but ?api-version= is missing. Error: 404 Resource not found.

Attempt 5: Custom provider ID to bypass Azure custom loader

{
  "provider": {
    "azure-responses": {
      "name": "Azure OpenAI",
      "npm": "@ai-sdk/azure",
      "options": {
        "apiKey": "<REDACTED>",
        "baseURL": "https://<resource>.cognitiveservices.azure.com/openai",
        "apiVersion": "2025-04-01-preview"
      },
      "models": {
        "gpt-5.2-codex": { "name": "GPT 5.2 Codex" }
      }
    }
  }
}

Result: Same as Attempt 2 — ?api-version= is dropped when baseURL is provided. Error: 404 Resource not found.

Root cause analysis:

The issue is an architectural mismatch across three layers:

@ai-sdk/azure URL construction: When using resourceName, the SDK hardcodes the hostname as {resourceName}.openai.azure.com. Cognitive Services endpoints use {resourceName}.cognitiveservices.azure.com instead. When baseURL is provided to bypass this, the SDK stops appending ?api-version= to requests — this is a known limitation.
OpenCode's Azure custom loader (provider.ts L178-191): Correctly calls sdk.responses(modelID) by default, but has no mechanism to handle the Cognitive Services endpoint variant.
OpenCode's getSDK (provider.ts L1041-1117): Passes config options through to createAzure(), but there's no way for users to configure both a custom base hostname AND retain the ?api-version= query parameter behavior.

Note: The bundled @ai-sdk/azure version (2.0.91) is not obsolete — it does support the Responses API. The issue is specifically about how it constructs URLs when baseURL is overridden.

Suggested fix:

Allow OpenCode's Azure provider to accept a full custom base URL while preserving ?api-version= injection (e.g. via a custom fetch wrapper, or by patching URL construction in the Azure loader).
Alternatively, add explicit support for the cognitiveservices.azure.com hostname pattern in the azure-cognitive-services custom loader.

References:

Plugins

None

OpenCode version

Latest stable (2026-02-17)

Steps to reproduce

Deploy a model requiring the Responses API (e.g. gpt-5.2-codex) on an Azure Cognitive Services resource
Configure opencode.json with provider azure, pointing at https://<resource>.cognitiveservices.azure.com/openai
Set "model": "azure/gpt-5.2-codex" and provide your API key
Launch opencode and send any message
Observe error: 404 Resource not found — the request URL is /openai/responses without ?api-version=
Verify the same request works via curl with ?api-version=2025-04-01-preview appended

Screenshot and/or share link

Error from OpenCode logs:

AI_APICallError: Resource not found
url: "https://<resource>.cognitiveservices.azure.com/openai/responses"
statusCode: 404
responseBody: {"error":{"code":"404","message": "Resource not found"}}

Expected URL (works via curl):

https://<resource>.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview

Operating System

Windows 11

Terminal

Windows Terminal

This issue might be related to existing issues. Please check:

Azure OpenAI configuration returns "API version not supported" / "Resource not found" despite valid endpoint #12186: Azure OpenAI configuration returns "API version not supported" / "Resource not found" (similar Cognitive Services endpoint issues)
Azure OpenAI need to change completions -> responses #7180: Azure OpenAI need to change completions -> responses (related to Azure endpoint routing)
Azure OpenAi generated URL is wrong? (/v1/) added in between #1508: Azure OpenAi generated URL is wrong? (/v1/) added in between (URL construction issues with Azure)

These issues share similar root causes around Azure endpoint URL construction and query parameter handling.

I too encountered a terrible amount of friction, trying every conceivable combination of keys and values making incremental progress but eventually getting stuck on a series of "Resource not found" errors. This was all after registering the Azure Cognitive Services (A.K.A. AI Foundry) provider API key, which now appears in my auth.json. I also set the AZURE_OPENAI_API_KEY env var.

In Foundry this was the endpoint for the one model:
https://XXXX.cognitiveservices.azure.com/openai/deployments/XXX_gpt-4.1-mini/chat/completions?api-version=2025-01-01-preview

I initially tried using the Desktop and CLI to update things, but eventually ended up poking at the opencode.json directly. This is the section which ultimately worked, with some redaction:

  ..
  "provider": {
    "foundry": {
      "npm": "@ai-sdk/azure",
      "options": {
        "name": "foundry",
        "apiKey": "{env:AZURE_OPENAI_API_KEY}",
        "baseURL": "https://XXXX.cognitiveservices.azure.com/openai/",
        "apiVersion": "2025-01-01-preview",
        "useDeploymentBasedUrls": true
      },
      "models": {
        "XXX_gpt-4.1-mini": { "name": "gpt-4.1-mini" }
      }
    }
  },
  ..

This was several hours in the making, but I now have a working connection to the model in both the Desktop and CLI.

@mlanza

@mlanza #14494 (comment)

Additional findings + workaround for Claude models via Azure AI Foundry

I ran into the same issue while trying to use gpt-5.3-codex and claude-opus-4-5 deployed on Azure AI Foundry.

Confirmed behavior

All attempts to use the azure provider with cognitiveservices.azure.com endpoint failed exactly as described — the ?api-version= parameter is dropped and the Responses API returns errors. This was confirmed via curl comparison:

# Works via curl
curl -X POST "https://<resource>.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview" \
  -H "api-key: $AZURE_API_KEY" \
  -d '{"model": "gpt-5.3-codex", "input": "hello", "max_output_tokens": 100}'

# Fails in OpenCode — api-version is dropped

Additional finding: `--pure` flag as a diagnostic tool

Running OpenCode with --pure (which disables the @opencode-ai/plugin) changes the error from PermissionDenied to the actual Azure API error, making it much easier to diagnose. Without --pure, the plugin seems to interfere with custom provider configurations.

Workaround for Claude models via Azure AI Foundry

Claude models deployed on Azure AI Foundry use a different endpoint (services.ai.azure.com) and the Anthropic native protocol — not the Azure OpenAI Responses API. This means they work correctly using the anthropic provider with a custom baseURL:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "YOUR_AZURE_KEY",
        "baseURL": "https://<resource>.services.ai.azure.com/anthropic/v1"
      }
    }
  },
  "model": "anthropic/claude-opus-4-5"
}

Confirmed working via curl:

curl -X POST "https://<resource>.services.ai.azure.com/anthropic/v1/messages" \
  -H "x-api-key: $AZURE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "claude-opus-4-5", "max_tokens": 100, "messages": [{"role": "user", "content": "hello"}]}'

This workaround does not solve the gpt-5.x-codex issue since those models require the Responses API, but it may help others using Claude on AI Foundry while the fix is pending.

Environment

OpenCode Desktop (Windows 11) + WSL2
Azure AI Foundry with cognitiveservices.azure.com and services.ai.azure.com endpoints
Models tested: gpt-5.3-codex, claude-opus-4-5, gpt-4o

our azure support is so so bad and it's unacceptable doing a pass this week.

@rekram1-node

@rekram1-node since I'm using my own Azure Foundry provider for OpenCode I never had any issues. Although I must admit that I don't use Anthropic via Azure Foundry because it's simply too expensive. So perhaps I'd face the same issue with Anthropic.

@alex-pathcourse

@alex-pathcourse stop spamming our issues or u will be banned

I too encountered a terrible amount of friction, trying every conceivable combination of keys and values making incremental progress but eventually getting stuck on a series of "Resource not found" errors. This was all after registering the Azure Cognitive Services (A.K.A. AI Foundry) provider API key, which now appears in my auth.json. I also set the AZURE_OPENAI_API_KEY env var.

In Foundry this was the endpoint for the one model: https://XXXX.cognitiveservices.azure.com/openai/deployments/XXX_gpt-4.1-mini/chat/completions?api-version=2025-01-01-preview

I initially tried using the Desktop and CLI to update things, but eventually ended up poking at the opencode.json directly. This is the section which ultimately worked, with some redaction:

..
"provider": {
"foundry": {
"npm": "@ai-sdk/azure",
"options": {
"name": "foundry",
"apiKey": "{env:AZURE_OPENAI_API_KEY}",
"baseURL": "https://XXXX.cognitiveservices.azure.com/openai/",
"apiVersion": "2025-01-01-preview",
"useDeploymentBasedUrls": true
},
"models": {
"XXX_gpt-4.1-mini": { "name": "gpt-4.1-mini" }
}
}
},
..
This was several hours in the making, but I now have a working connection to the model in both the Desktop and CLI.

I followed this and I am using gpt-5.4, no luck, spent hours with opencode and Azure still can't make it work ... anything I could miss? my computer can definitely connect to the Foundry endpoint as the tested program suggested by Foundry can connect.

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

I also ran into this issue with my 5.3-codex model hosted on AI Foundry.

I could copy-paste the comment with proposed fix from my coding agent over here, like the people above did already, but it wouldn't add much to the conversation.

They key point is the ?api-version=... needs to be appended to the URL when invoking the responses api.

@Jandev

@Jandev because Azure Foundry has special requirements we created our own Azure Foundry AI provider. https://github.com/ophiosdev/azure-foundry-provider

It's easy to use in OpenCode. We always use it our OpenCode container.

https://github.com/ophiosdev/opencode-cli-container

@Jandev because Azure Foundry has special requirements we created our own Azure Foundry AI provider. https://github.com/ophiosdev/azure-foundry-provider

It's easy to use in OpenCode. We always use it our OpenCode container.

https://github.com/ophiosdev/opencode-cli-container

Wow, thanks for that!
Added this provider and it's working like a charm now.

For future reference/others, this is what I did.

First, extracted the (useful) code from the docker file of the mentioned repository.

export PROVIDER_DIR=/usr/local/provider

bun install "github:ophiosdev/azure-foundry-provider"
cd node_modules/azure-foundry-provider
bun build --outdir=dist src/index.ts
mv dist "${PROVIDER_DIR}/azure-foundry-provider"

Second, in my opencode.json file added this provider:

  "provider": {
    // all the other stuff...
    "azure-foundry": {
      "name": "Azure Foundry",
      "npm": "file:///usr/local/provider/azure-foundry-provider/index.js",
      "models": {
        "gpt-5.3-codex": {
          "id": "gpt-5.3-codex",
          "name": "Mine - gpt-5.3-codex"
        }
      },
      "options": {
        "apiKey": "[my-api-key]",
        "endpoint": "https://[ai-foundry-resource].cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview",
        "apiMode": "responses",
        "useCompletionUrls": false
      }
    }

@Jandev

@Jandev when you look at the documentation (README.md) of the provider you can mix reponses and chat-completion models with ONE single provider definition. Aside the issues that Azure support was ever not ideal this was another fact that made us to create that provider. Before that you had to define TWO different providers in OpenCode. Even named the same (Display Name) and thus in the model selection in OpenCode this got merged it was always tedious.

Example: https://github.com/ophiosdev/azure-foundry-provider#14-per-model-override-under-provider-options

I read that, indeed. A very nice addition, seeing some models don't work well with responses api or the completions api.

@Jandev

@Jandev and you can use Bearer authentication instead of API-Key authentication. Typically you wouldn't provide models via Azure Foundry in a company using API-Key authentication.

https://github.com/ophiosdev/azure-foundry-provider#24-static-bearer-token
https://github.com/ophiosdev/azure-foundry-provider#25-token-provider-callback

Because we are utilizing @azure/identity the provider seamlessly integrates with the Entra ID and Azure Foundry authentication flow.

Can someone give me a tldr of what sucks for azure rn? We wanna improve the UX but I dont use azure too much myself and it seems like every company has weird restrictions, some people have deployment urls, some cant use responses apis, some use responses api and it is completely fine out of the box, etc

Can someone give me a tldr of what sucks for azure rn? We wanna improve the UX but I dont use azure too much myself and it seems like every company has weird restrictions, some people have deployment urls, some cant use responses apis, some use responses api and it is completely fine out of the box, etc

I think I can come up with a list of issues/things that don't work.
Probably won't be today, but I'll try to get a list this week.

Just seeing this, thanks!

Navigation Menu

Repository navigation

Azure OpenAI Cognitive Services endpoint: Responses API does not append ?api-version=, cannot use gpt-5.x-codex models #13999

Description

Plugins

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Additional findings + workaround for Claude models via Azure AI Foundry

Confirmed behavior

Additional finding: `--pure` flag as a diagnostic tool

Workaround for Claude models via Azure AI Foundry

Environment

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Azure OpenAI Cognitive Services endpoint: Responses API does not append ?api-version=, cannot use gpt-5.x-codex models #13999

Description

Description

Plugins

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Activity

github-actions commented on Feb 17, 2026

mlanza commented on Mar 6, 2026

tmeckel commented on Mar 6, 2026

Igor1788 commented on Apr 25, 2026

Additional findings + workaround for Claude models via Azure AI Foundry

Confirmed behavior

Additional finding: --pure flag as a diagnostic tool

Workaround for Claude models via Azure AI Foundry

Environment

rekram1-node commented on Apr 26, 2026

tmeckel commented on Apr 26, 2026

alex-pathcourse commented on May 11, 2026

rekram1-node commented on May 11, 2026

rickywck commented on Jun 7, 2026

github-actions commented on Aug 7, 2026

Jandev commented on Aug 7, 2026

tmeckel commented on Aug 7, 2026

Jandev commented on Aug 7, 2026

tmeckel commented on Aug 7, 2026

Jandev commented on Aug 7, 2026

tmeckel commented on Aug 7, 2026

rekram1-node commented on Aug 7, 2026

Jandev commented on Aug 10, 2026

rekram1-node commented on Aug 17, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Additional finding: `--pure` flag as a diagnostic tool