カスタムプロバイダー

カスタムプロバイダー（Custom Providers）を使うと、AI Gateway が標準で対応していない AI プロバイダーを接続できます。HTTPS API エンドポイントを持つ任意の AI プロバイダーに対して、AI Gateway のオブザーバビリティ、キャッシュ、レート制限などの機能を使えます。

• 社内の AI モデル: 組織内でセルフホストしている AI モデルに接続します
• 地域固有のプロバイダー: 特定の地域向けの AI プロバイダーを統合します
• 専用モデル: 標準プロバイダーでは使えない、分野特化の AI サービスを使います
• カスタムエンドポイント: 自前の AI インフラへリクエストをルーティングします

• AI Gateway を利用できる有効な Cloudflare アカウント
• カスタム AI プロバイダーの有効な API キー
• プロバイダー API の HTTPS ベース URL

カスタムプロバイダーの作成、読み取り、更新、削除の API エンドポイントには認証が必要です。適切な権限を持つ Cloudflare API トークンを作成してください。

API トークンを作成する手順は次のとおりです。

1. Cloudflare ダッシュボードの API tokens ページ ↗ を開きます
2. Create Token を選択します
3. Custom Token を選び、次の権限を追加します:
   • AI Gateway - Edit
4. Continue to summary を選び、続けて Create Token を選択します
5. トークンをコピーします。Authorization: Bearer $CLOUDFLARE_API_TOKEN ヘッダーで使います

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true
  }'

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": null,
    "curl_example": null,
    "js_example": null,
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?enable=true" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?search=custom" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "success": true,
  "result": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Custom Provider",
      "slug": "some-provider",
      "base_url": "https://api.myprovider.com",
      "enable": true,
      "created_at": 1700000000,
      "modified_at": 1700000000
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "total_count": 1,
    "total_pages": 1
  }
}

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": "https://docs.myprovider.com",
    "curl_example": "curl -X POST https://api.myprovider.com/v1/chat ...",
    "js_example": "fetch('https://api.myprovider.com/v1/chat', {...})",
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Provider Name",
    "enable": true,
    "description": "Updated description"
  }'

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enable": true}'

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_url": "https://api.newprovider.com"}'

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Custom Provider",
    "slug": "some-provider"
  }
}

カスタムプロバイダーを作成したら、Unified API または プロバイダー固有エンドポイント のいずれかで、AI Gateway 経由にリクエストをルーティングできます。どちらの方法でも、slug の先頭に custom- を付ける必要があります。

AI Gateway がカスタムプロバイダー向けのリクエストを受け取ると、設定済みの base_url と、ゲートウェイ URL の custom-{slug}/ 以降のパスを組み合わせて、アップストリーム URL を組み立てます。

base_url にはプロバイダー API のルートドメインだけ（または固定プレフィックス付きのドメイン）を入れてください。/v1/chat/completions のような API 固有のパスセグメントは、base_url ではなくリクエスト URL に置きます。

計算式は次のとおりです。

Gateway URL:   https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-{slug}/{provider-path}
Upstream URL:  {base_url}/{provider-path}

リクエスト URL の custom-{slug}/ 以降は、そのまま base_url に付加されて最終的なアップストリーム URL になります。つまり {provider-path} には、複数のパスセグメント、クエリパラメーター、プロバイダーが必要とする任意のパス構造を含められます。

カスタムプロバイダーが OpenAI 互換の /chat/completions 形式を受け付ける場合は Unified API を使います。いちばん簡単で、OpenAI SDK とも相性がよいです。

非標準の API パスやリクエスト形式の場合は プロバイダー固有エンドポイント を使います。アップストリームへ送る URL パスとリクエスト本文の両方を自由に制御できます。

Unified API は、OpenAI 互換形式でプロバイダーの chat completions エンドポイントへリクエストを送ります。モデルは custom-{slug}/{model-name} 形式で指定します。

# 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!"}]
  }'

プロバイダー固有エンドポイントでは、アップストリームパスを自由に指定できます。URL の custom-{slug}/ 以降は base_url に付加されます。

# 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!"}]
  }'

base_url が https://api.myprovider.com の場合、このリクエストは https://api.myprovider.com/v1/chat/completions へプロキシされます。

次の例は、プロバイダーの種類ごとに base_url の設定とリクエスト URL の組み立て方を示します。

多くのプロバイダーは、OpenAI の慣例に従い {domain}/v1/chat/completions で API を提供します。

設定:

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

プロバイダー固有エンドポイント:

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 の対応:

このプロバイダーは OpenAI 互換なので、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!"}]
  }'

/v1/ の慣例に従わない API パスを使うプロバイダーもあります。たとえば、チャットエンドポイントが https://api.custom-ai.com/api/coding/paas/v4/chat/completions にある場合です。

設定:

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

プロバイダー固有エンドポイント:

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 の対応:

リバースプロキシの背後や、パスプレフィックスを付けるプラットフォーム上で自前モデルをホストしている場合、すべてのエンドポイントが共有する固定プレフィックスだけを base_url に含めます。そうでなければ、base_url はドメインだけにします。

設定（ドメインのみの base_url）:

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

プロバイダー固有エンドポイント:

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 の対応:

OpenAI SDK で AI Gateway 経由のカスタムプロバイダーに接続する場合、SDK の base_url をゲートウェイのプロバイダー固有エンドポイントパスに設定します（プロバイダーが期待する API バージョンプレフィックスまで含めます）。

設定:

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

Python（OpenAI SDK）:

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 の対応:

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

各カスタムプロバイダーの slug は、アカウント内で一意である必要があります。別の slug を選ぶか、既存のプロバイダーを更新してください。

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

指定したプロバイダー ID が存在しないか、アクセス権がありません。プロバイダー ID と認証情報を確認してください。

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

base_url は有効な HTTPS URL である必要があります。セキュリティ上の理由で、HTTP URL は使えません。

アップストリームプロバイダーから 404 が返る場合、いちばん多い原因はパス対応の誤りです。次を確認してください。

1. base_url はプロバイダーの ルートドメイン（例: https://api.provider.com）になっており、API パスセグメントは含めていないこと。
2. リクエスト URL の custom-{slug}/ 以降に API パス全体 が含まれていること。たとえばアップストリームが https://api.provider.com/api/v2/chat なら、ゲートウェイ URL の末尾は /custom-{slug}/api/v2/chat になります。
3. パスセグメントの重複や欠落がないこと。よくある誤りは、base_url とリクエストパスの両方に /v1 を入れてしまい、アップストリームが /v1/v1/chat/completions を受け取ることです。

1. わかりやすい slug を使う: プロバイダーが分かる slug を選びます（例: internal-gpt、regional-ai）
2. 連携内容を記録する: curl_example と js_example フィールドで利用例を残します
3. 段階的に有効化する: 本番で有効にする前に、enable: false でテストします
4. 利用状況を監視する: AI Gateway の分析で、カスタムプロバイダーへのリクエストを追跡します
5. エンドポイントを保護する: カスタムプロバイダーのベース URL で、適切な認証と認可を実装します
6. BYOK を使う: リクエストごとにキーを含めず、BYOK でプロバイダー API キーを安全に保存します

• カスタムプロバイダーはアカウント固有で、Cloudflare アカウント間では共有されません
• base_url は HTTPS である必要があります（HTTP は使えません）
• プロバイダー slug は各アカウント内で一意である必要があります
• キャッシュとレート制限の設定はプロバイダー全体に適用され、モデル単位ではありません

• AI Gateway をはじめる
• 認証を設定する
• BYOK（キーの保存）
• 動的ルーティング
• キャッシュ
• レート制限