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

[kpasechnikov]

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:

1. @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.

2. 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.

3. 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:

• Azure OpenAI Responses API docs
• Vercel AI SDK: Add baseURL and apiVersion to Azure provider (issue #2312)
• Vercel AI SDK: Azure calling wrong URL path (issue #4797)

Plugins

None

OpenCode version

Latest stable (2026-02-17)

Steps to reproduce

1. Deploy a model requiring the Responses API (e.g. gpt-5.2-codex) on an Azure Cognitive Services resource
2. Configure opencode.json with provider azure, pointing at https://<resource>.cognitiveservices.azure.com/openai
3. Set "model": "azure/gpt-5.2-codex" and provide your API key
4. Launch opencode and send any message
5. Observe error: 404 Resource not found — the request URL is /openai/responses without ?api-version=
6. 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

[github-actions]

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.

[mlanza]

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.

[tmeckel]

@mlanza #14494 (comment)

[Igor1788]

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

[rekram1-node]

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

[tmeckel]

@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.