Custom Providers·续

Use the Unified API when your custom provider accepts the OpenAI-compatible /chat/completions request format. This is the simplest option and works well with OpenAI SDKs.

Use the provider-specific endpoint when your custom provider uses a non-standard API path or request format. This gives you full control over both the URL path and the request body sent to the upstream provider.

Via Unified API

The Unified API sends requests to the provider's chat completions endpoint using the OpenAI-compatible format. Specify the model using the format custom-{slug}/{model-name}.

Request using custom provider via Unified APIbash

# Run `wrangler auth token` to get an auth token to replace $CF_AIG_TOKEN for use with the API.
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "cf-aig-authorization: Bearer $CF_AIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-some-provider/model-name",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Via provider-specific endpoint

The provider-specific endpoint gives you full control over the upstream path. Everything after custom-{slug}/ in the URL is appended to the base_url.

Direct provider endpointbash

# Run `wrangler auth token` to get an auth token to replace $CF_AIG_TOKEN for use with the API.
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-some-provider/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "cf-aig-authorization: Bearer $CF_AIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-name",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

If base_url is https://api.myprovider.com, this request is proxied to: https://api.myprovider.com/v1/chat/completions

Examples

The following examples show how to configure base_url and construct request URLs for different types of providers.

Example 1: OpenAI-compatible provider (standard /v1/ path)

Many providers follow the OpenAI convention of hosting their API at {domain}/v1/chat/completions.

Configuration:

• slug: my-openai-compat
• base_url: https://api.example-provider.com

Provider-specific endpoint:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-my-openai-compat/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "example-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

URL mapping:

Since this provider is OpenAI-compatible, you could also use the Unified API:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-my-openai-compat/example-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Example 2: Provider with a non-standard API path

Some providers use API paths that don't follow the /v1/ convention. For example, a provider whose chat endpoint is at https://api.custom-ai.com/api/coding/paas/v4/chat/completions.

Configuration:

• slug: custom-ai
• base_url: https://api.custom-ai.com

Provider-specific endpoint:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-custom-ai/api/coding/paas/v4/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-ai-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

URL mapping:

Note

For providers with non-standard paths, you must use the provider-specific endpoint. The Unified API only supports the /chat/completions path and cannot route to custom API paths.

Example 3: Self-hosted model with a path prefix

If you host your own model behind a reverse proxy or on a platform that adds a path prefix, include only the fixed prefix portion in base_url if all your endpoints share it. Otherwise, keep base_url as just the domain.

Configuration (domain-only base_url):

• slug: internal-llm
• base_url: https://ml.internal.example.com

Provider-specific endpoint:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-internal-llm/serving/models/my-model:predict \
  -H "Authorization: Bearer $INTERNAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{"prompt": "Summarize the following text:"}]
  }'

URL mapping:

Example 4: Provider using OpenAI SDK with a custom base URL

When using the OpenAI SDK to connect to a custom provider through AI Gateway, set the SDK's base_url to the gateway's provider-specific endpoint path (up to and including the API version prefix that your provider expects).

Configuration:

• slug: alt-provider
• base_url: https://api.alt-provider.com

Python (OpenAI SDK):

Using OpenAI SDK with a custom providerpython

from openai import OpenAI

client = OpenAI(
    api_key="your-provider-api-key",
    base_url="https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-alt-provider/v1",
    default_headers={
        "cf-aig-authorization": "Bearer {cf_aig_token}",
    },
)

# The SDK appends /chat/completions to the base_url automatically.
# Final upstream URL: https://api.alt-provider.com/v1/chat/completions
response = client.chat.completions.create(
    model="alt-model-v2",
    messages=[{"role": "user", "content": "Hello!"}],
)

URL mapping:

Common errors

409 Conflict - Duplicate slug

{
    "success": false,
    "errors": [
        {
            "code": 1003,
            "message": "A custom provider with this slug already exists",
            "path": ["body", "slug"]
        }
    ]
}

Each custom provider slug must be unique within your account. Choose a different slug or update the existing provider.

404 Not Found

{
    "success": false,
    "errors": [
        {
            "code": 1004,
            "message": "Custom Provider not found"
        }
    ]
}

The specified provider ID does not exist or you don't have access to it. Verify the provider ID and your authentication credentials.

400 Bad Request - Invalid base_url

{
    "success": false,
    "errors": [
        {
            "code": 1002,
            "message": "base_url must be a valid HTTPS URL starting with https://",
            "path": ["body", "base_url"]
        }
    ]
}

The base_url field must be a valid HTTPS URL. HTTP URLs are not supported for security reasons.

404 when making requests to a custom provider

If you receive a 404 from the upstream provider, the most common cause is an incorrect path mapping. Verify that:

1. Your base_url is set to the provider's root domain (for example, https://api.provider.com) rather than including API path segments.
2. Your request URL includes the full API path after custom-{slug}/. For example, if the upstream endpoint is https://api.provider.com/api/v2/chat, your gateway URL should end in /custom-{slug}/api/v2/chat.
3. There is no duplicate or missing path segment. A common mistake is including /v1 in both base_url and the request path, resulting in the upstream receiving /v1/v1/chat/completions.

Best practices

1. Use descriptive slugs: Choose slugs that clearly identify the provider (e.g., internal-gpt, regional-ai)
2. Document your integrations: Use the curl_example and js_example fields to provide usage examples
3. Enable gradually: Test with enable: false before making the provider active
4. Monitor usage: Use AI Gateway's analytics to track requests to your custom providers
5. Secure your endpoints: Ensure your custom provider's base URL implements proper authentication and authorization
6. Use BYOK: Store provider API keys securely using BYOK instead of including them in every request

Limitations

• Custom providers are account-specific and not shared across Cloudflare accounts
• The base_url must use HTTPS (HTTP is not supported)
• Provider slugs must be unique within each account
• Cache and rate limiting settings apply globally to the provider, not per-model

Related resources

• Get started with AI Gateway
• Configure authentication
• BYOK (Store Keys)
• Dynamic routing
• Caching
• Rate limiting

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-gateway/configuration/custom-providers/#page","headline":"Custom Providers","description":"Create and manage custom AI providers for your account.","url":"https://developers.cloudflare.com/ai-gateway/configuration/custom-providers/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-gateway/configuration/custom-providers/og.png?v=781d59491016c41d","dateModified":"2026-06-15","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Specify model or provider fallbacks in AI Gateway to handle request failures and ensure reliability. title: Fallbacks image: https://developers.cloudflare.com/ai-gateway/configuration/fallbacks/og.png?v=893e5e6d4d3ec48b

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-gateway/llms.txt
Use this file to discover all available pages before exploring further.