Custom provider documentation lacks clarity on endpoint path structure differences #27699
Description
Existing documentation URL(s)
https://developers.cloudflare.com/ai-gateway/configuration/custom-providers/
What changes are you suggesting?
The Cloudflare AI Gateway custom provider documentation shows two different ways to access custom providers but doesn't clearly explain the path structure differences or when to use each approach.
The documentation shows both:
Unified API endpoint: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions with model format custom-{slug}/{model-name}
Provider-specific endpoint: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-{slug}/{provider-path}
However, there's no clear guidance on a few things.
What happens to the path after {provider-path} - I discovered that providers with non-standard API structures (like Z.AI using /api/coding/paas/v4/ instead of /v1/) require trial-and-error to determine the correct base_url configuration; eventually I settled on https://gateway.ai.cloudflare.com/v1/account-id/pi/custom-zaiglm/api/coding/paas/v4 with custom provider base URL set to https://api.z.ai on Cloudflare
The provider's base_url should include the full API path or just the domain - this wasn't clear and led to multiple 404 errors while trying different combinations.
How to map provider-specific endpoints to the actual upstream API - documentation should include concrete examples showing the full URL transformation from Cloudflare gateway to the upstream provider
When to use Unified API vs provider-specific endpoints for custom providers - the distinction isn't explained, leading to confusion about which approach supports custom path structures
This lack of clarity makes it difficult to integrate providers that don't follow standard OpenAI-style path structures. The documentation should include examples showing the full request flow from Cloudflare gateway URL to the upstream provider's actual endpoint, making it clear what gets appended and what doesn't.
Additional information
No response