Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

カスタムプロバイダー

最終更新 Markdown で表示Agent セットアップ

概要

カスタムプロバイダー(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 ヘッダーで使います

カスタムプロバイダーを作成する

API で新しいカスタムプロバイダーを作成する手順は次のとおりです。

  1. アカウント ID と Account Tag を取得します。

  2. POST リクエストを送信して、新しいカスタムプロバイダーを作成します。

カスタムプロバイダーを作成するbash
# 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
  }'

必須フィールド:

  • name (string): プロバイダーの表示名
  • slug (string): 一意の識別子(英数字とハイフン)。アカウント内で一意である必要があります。
  • base_url (string): プロバイダー API エンドポイントの HTTPS URL。https:// で始まる必要があります。

任意フィールド:

  • description (string): プロバイダーの説明
  • link (string): プロバイダーのドキュメント URL
  • enable (boolean): プロバイダーを有効にするかどうか(デフォルト: false)
  • beta (boolean): ベータ機能としてマークする(デフォルト: false)
  • curl_example (string): プロバイダー利用時の cURL コマンド例
  • js_example (string): プロバイダー利用時の JavaScript コード例

レスポンス:

{
  "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
  }
}

ダッシュボードで新しいカスタムプロバイダーを作成する手順は次のとおりです。

  1. Cloudflare ダッシュボード ↗ にログインし、アカウントを選択します。
  2. Compute & AI > AI Gateway > Custom Providers ↗ を開きます。
  3. Add Custom Provider を選択します。
  4. 次の情報を入力します:
    • Provider Name: プロバイダーの表示名
    • Provider Slug: 一意の識別子(英数字とハイフン)
    • Base URL: プロバイダー API エンドポイントの HTTPS URL(例: https://api.myprovider.com/v1)
  5. Save を選択して、カスタムプロバイダーを作成します。

カスタムプロバイダーを一覧する

任意のフィルターとページネーションを付けて、すべてのカスタムプロバイダーを取得します。

すべてのプロバイダーを一覧するbash
# 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"

クエリパラメーター:

  • page (number): ページ番号(デフォルト: 1)
  • per_page (number): 1 ページあたりの件数(デフォルト: 20、最大: 100)
  • enable (boolean): 有効状態で絞り込む
  • beta (boolean): ベータ状態で絞り込む
  • search (string): id、name、slug フィールドを検索する
  • order_by (string): ソート対象と方向(デフォルト: "name ASC")

例:

有効なプロバイダーだけを一覧します:

# 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
  }
}

カスタムプロバイダーをすべて確認する手順は次のとおりです。

  1. Cloudflare ダッシュボード ↗ にログインし、アカウントを選択します。
  2. Compute & AI > AI Gateway > Custom Providers ↗ を開きます。
  3. 名前、slug、ベース URL、状態とともに、すべてのカスタムプロバイダーが一覧されます。

特定のカスタムプロバイダーを取得する

ID を指定して、特定のカスタムプロバイダーの詳細を取得します。

ID でプロバイダーを取得するbash
# 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
  }
}

カスタムプロバイダーを更新する

既存のカスタムプロバイダーを更新します。すべてのフィールドは任意です。変更したいフィールドだけを含めてください。

プロバイダーを更新するbash
# 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"
  }'

更新できるフィールド:

  • name (string): プロバイダーの表示名
  • slug (string): プロバイダーの識別子
  • base_url (string): API エンドポイント URL(HTTPS である必要があります)
  • description (string): プロバイダーの説明
  • link (string): ドキュメント URL
  • enable (boolean): 有効状態
  • beta (boolean): ベータフラグ
  • curl_example (string): cURL コマンド例
  • js_example (string): JavaScript コード例

例:

プロバイダーを有効にします:

# 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}'

プロバイダー URL を更新します:

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

既存のカスタムプロバイダーを更新する手順は次のとおりです。

  1. Cloudflare ダッシュボード ↗ にログインし、アカウントを選択します。
  2. Compute & AI > AI Gateway > Custom Providers ↗ を開きます。
  3. 更新したいカスタムプロバイダーを見つけ、Edit を選択します。
  4. 変更したいフィールド(名前、slug、ベース URL など)を更新します。
  5. Save を選択して変更を適用します。

カスタムプロバイダーを削除する

カスタムプロバイダーを削除します。

プロバイダーを削除するbash
# 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"
  }
}

カスタムプロバイダーを削除する手順は次のとおりです。

  1. Cloudflare ダッシュボード ↗ にログインし、アカウントを選択します。
  2. Compute & AI > AI Gateway > Custom Providers ↗ を開きます。
  3. 削除したいカスタムプロバイダーを見つけ、Delete を選択します。
  4. 確認を求められたら、削除を確定します。

AI Gateway でカスタムプロバイダーを使う

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

URL ルーティングの仕組み

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} には、複数のパスセグメント、クエリパラメーター、プロバイダーが必要とする任意のパス構造を含められます。

Unified API とプロバイダー固有エンドポイントの選び方

Unified API (/compat) プロバイダー固有エンドポイント
向いている用途 OpenAI 互換 API を持つプロバイダー 任意の API 構造を持つプロバイダー
リクエスト形式 OpenAI の /chat/completions スキーマに従う必要があります プロバイダー固有のリクエスト形式を使います
パスの制御 /compat/chat/completions に固定 アップストリームパスを自由に指定できます
プロバイダーの指定方法 model フィールド: custom-{slug}/{model-name} URL パス: /custom-{slug}/{path}

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

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

Unified API 経由

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

Unified API 経由でカスタムプロバイダーにリクエストするbash
# 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 に付加されます。

プロバイダー固有エンドポイントbash
# 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 の組み立て方を示します。

例 1: OpenAI 互換プロバイダー(標準の /v1/ パス)

多くのプロバイダーは、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 の対応:

構成要素 値
Gateway URL https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-my-openai-compat/v1/chat/completions
base_url https://api.example-provider.com
プロバイダーパス /v1/chat/completions
アップストリーム URL https://api.example-provider.com/v1/chat/completions

このプロバイダーは 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!"}]
  }'

例 2: 非標準の API パスを使うプロバイダー

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

構成要素 値
Gateway URL https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-custom-ai/api/coding/paas/v4/chat/completions
base_url https://api.custom-ai.com
プロバイダーパス /api/coding/paas/v4/chat/completions
アップストリーム URL https://api.custom-ai.com/api/coding/paas/v4/chat/completions

例 3: パスプレフィックス付きのセルフホストモデル

リバースプロキシの背後や、パスプレフィックスを付けるプラットフォーム上で自前モデルをホストしている場合、すべてのエンドポイントが共有する固定プレフィックスだけを 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 の対応:

構成要素 値
Gateway URL https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-internal-llm/serving/models/my-model:predict
base_url https://ml.internal.example.com
プロバイダーパス /serving/models/my-model:predict
アップストリーム URL https://ml.internal.example.com/serving/models/my-model:predict

例 4: カスタムベース URL で OpenAI SDK を使うプロバイダー

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

設定:

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

Python(OpenAI SDK):

OpenAI SDK でカスタムプロバイダーを使うpython
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 の対応:

構成要素 値
SDK の base_url https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-alt-provider/v1
SDK が付加 /chat/completions
ゲートウェイ URL 全体 https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-alt-provider/v1/chat/completions
プロバイダーの base_url https://api.alt-provider.com
プロバイダーパス /v1/chat/completions
アップストリーム URL https://api.alt-provider.com/v1/chat/completions

よくあるエラー

409 Conflict - 重複した slug

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

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

404 Not Found

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

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

400 Bad Request - 無効な base_url

{
	"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 になる

アップストリームプロバイダーから 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 は各アカウント内で一意である必要があります
  • キャッシュとレート制限の設定はプロバイダー全体に適用され、モデル単位ではありません

関連リソース

役に立ちましたか?