/json - AI で構造化データを取得する · Cloudflare Browser Run ドキュメント

/json エンドポイントは、Web ページから構造化データを抽出します。期待する出力は、prompt または JSON スキーマを受け取る response_format パラメーターで指定できます。エンドポイントは抽出したデータを JSON 形式で返します。

このエンドポイントは、次の 2 通りの方法で使えます。

REST API: Browser Rendering - Edit 権限を持つカスタム API トークンを作成します。
Workers Bindings: Workers Bindings を使い、Cloudflare Worker から直接エンドポイントを呼び出します。API トークンは不要です。

詳細は Quick Actions: 始める前にを参照してください。

エンドポイント

https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json

必須フィールド

url または html のいずれかを指定してください。

url (string)
html (string)

さらに、次のうち少なくとも 1 つが必要です。

prompt (string)、または
response_format（JSON Schema を持つオブジェクト）

よくある用途

商品情報（タイトル、価格、在庫）や一覧（求人、賃貸）の抽出
記事メタデータ（タイトル、著者、公開日、正規 URL）の正規化
非構造化ページを、下流パイプライン向けの型付き JSON へ変換

基本的な使い方

プロンプトと JSON スキーマを使う

この例では、プロンプトと JSON スキーマの両方を渡して Web ページのデータを取得します。プロンプトは抽出の指針になり、JSON スキーマは出力の期待構造を定義します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
  "url": "https://developers.cloudflare.com/",
  "prompt": "Get me the list of AI products",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "link": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ]
            }
          }
        }
      }
  }
}'

{
	"success": true,
	"result": {
		"products": [
			{
				"name": "Build a RAG app",
				"link": "https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/"
			},
			{
				"name": "Workers AI",
				"link": "https://developers.cloudflare.com/workers-ai/"
			},
			{
				"name": "Vectorize",
				"link": "https://developers.cloudflare.com/vectorize/"
			},
			{
				"name": "AI Gateway",
				"link": "https://developers.cloudflare.com/ai-gateway/"
			},
			{
				"name": "AI Playground",
				"link": "https://playground.ai.cloudflare.com/"
			}
		]
	}
}

TypeScript SDK を使う例は次のとおりです。

import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"], // This is the default and can be omitted
});

const json = await client.browserRendering.json.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://developers.cloudflare.com/",
	prompt: "Get me the list of AI products",
	response_format: {
		type: "json_schema",
		json_schema: {
			type: "object",
			properties: {
				products: {
					type: "array",
					items: {
						type: "object",
						properties: {
							name: {
								type: "string",
							},
							link: {
								type: "string",
							},
						},
						required: ["name"],
					},
				},
			},
		},
	},
});
console.log(json);

interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("json", {
			url: "https://developers.cloudflare.com/",
			prompt: "Get me the list of AI products",
			response_format: {
				type: "json_schema",
				json_schema: {
					type: "object",
					properties: {
						products: {
							type: "array",
							items: {
								type: "object",
								properties: {
									name: { type: "string" },
									link: { type: "string" },
								},
								required: ["name"],
							},
						},
					},
				},
			},
		});
	},
} satisfies ExportedHandler<Env>;

プロンプトのみを使う

この例では、プロンプトだけを渡します。エンドポイントはプロンプトに沿ってデータを抽出しますが、レスポンスは JSON スキーマに従った構造にはなりません。特定の形式が不要な、単純な抽出に向いています。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
    "url": "https://developers.cloudflare.com/",
    "prompt": "get me the list of AI products"
  }'

{
	"success": true,
	"result": {
		"AI Products": [
			"Build a RAG app",
			"Workers AI",
			"Vectorize",
			"AI Gateway",
			"AI Playground"
		]
	}
}

JSON スキーマのみを使う（プロンプトなし）

この場合は、response_format パラメーターで JSON スキーマを渡します。スキーマが、抽出データの構造を定義します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
	"url": "https://developers.cloudflare.com/",
	"response_format": {
		"type": "json_schema",
		"json_schema": {
			"type": "object",
			"properties": {
			"products": {
				"type": "array",
				"items": {
				"type": "object",
				"properties": {
					"name": {
					"type": "string"
					},
					"link": {
					"type": "string"
					}
				},
				"required": [
					"name"
				]
				}
			}
			}
		}
    }
  }'

{
	"success": true,
	"result": {
		"products": [
			{
				"name": "Workers",
				"link": "https://developers.cloudflare.com/workers/"
			},
			{
				"name": "Pages",
				"link": "https://developers.cloudflare.com/pages/"
			},
			{
				"name": "R2",
				"link": "https://developers.cloudflare.com/r2/"
			},
			{
				"name": "Images",
				"link": "https://developers.cloudflare.com/images/"
			},
			{
				"name": "Stream",
				"link": "https://developers.cloudflare.com/stream/"
			},
			{
				"name": "Build a RAG app",
				"link": "https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/"
			},
			{
				"name": "Workers AI",
				"link": "https://developers.cloudflare.com/workers-ai/"
			},
			{
				"name": "Vectorize",
				"link": "https://developers.cloudflare.com/vectorize/"
			},
			{
				"name": "AI Gateway",
				"link": "https://developers.cloudflare.com/ai-gateway/"
			},
			{
				"name": "AI Playground",
				"link": "https://playground.ai.cloudflare.com/"
			},
			{
				"name": "Access",
				"link": "https://developers.cloudflare.com/cloudflare-one/access-controls/policies/"
			},
			{
				"name": "Tunnel",
				"link": "https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/"
			},
			{
				"name": "Gateway",
				"link": "https://developers.cloudflare.com/cloudflare-one/traffic-policies/"
			},
			{
				"name": "Browser Isolation",
				"link": "https://developers.cloudflare.com/cloudflare-one/remote-browser-isolation/"
			},
			{
				"name": "Replace your VPN",
				"link": "https://developers.cloudflare.com/learning-paths/replace-vpn/concepts/"
			}
		]
	}
}

高度な使い方

カスタムモデルを使う（BYO API Key）

Browser Run は、認証情報を自分で渡すカスタムモデルを使えます。custom_ai 配列にモデルを列挙します。

model は <provider>/<model_name> の形式にしてください。プロバイダーは、対応プロバイダーのいずれかである必要があります。
authorization は、Browser Run が代理でプロバイダーを呼び出すためのベアラートークンまたは API キーです。

この例では、custom_ai パラメーターで Anthropic の Claude Sonnet 4 モデルを使うよう Browser Run に指示します。プロンプトは、対象 URL から主な <h1> と <h2> 見出しを抽出し、構造化 JSON オブジェクトで返すよう求めます。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
  "url": "http://demoto.xyz/headings",
  "prompt": "Get the heading from the page in the form of an object like h1, h2. If there are many headings of the same kind then grab the first one.",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "type": "object",
      "properties": {
        "h1": {
          "type": "string"
        },
        "h2": {
          "type": "string"
        }
      },
      "required": [
        "h1"
      ]
    }
  },
  "custom_ai": [
    {
      "model": "anthropic/claude-sonnet-4-20250514",
      "authorization": "Bearer <ANTHROPIC_API_KEY>"
    }
  ]
}'

{
	"success": true,
	"result": {
		"h1": "Heading 1",
		"h2": "Heading 2"
	}
}

フォールバック付きのカスタムモデルを使う

自動フェイルオーバーのために、複数のモデルを指定できます。Browser Run は成功するまで、列挙した順にモデルを試します。フェイルオーバーを追加するには、custom_ai 配列にモデルを追加します。

この例では、Browser Run はまず Anthropic の Claude Sonnet 4 モデルを呼び出します。そのリクエストがエラーを返すと、Workers AI の Meta Llama 3.3 70B、次に OpenAI の GPT-4o へ自動で再試行します。

"custom_ai": [
  {
    "model": "anthropic/claude-sonnet-4-20250514",
    "authorization": "Bearer <ANTHROPIC_API_KEY>"
  },
  {
    "model": "workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "authorization": "Bearer <CLOUDFLARE_AUTH_TOKEN>"
  },
{
    "model": "openai/gpt-4o",
    "authorization": "Bearer <OPENAI_API_KEY>"
  }
]

トラブルシューティング

JSON 抽出が null または空の結果を返す

/json エンドポイントが null または空の結果を返す場合は、次を試してください。

明確なプロンプトを渡す — 抽出するデータと、ページ上の出現箇所を具体的に指定します（例: 「メインの商品セクションから商品名、価格、説明を抽出する」）。
レスポンススキーマを定義する — response_format と JSON スキーマで、期待する出力構造を強制します。
カスタムモデルを使う — 既定の Workers AI モデルで望む結果が得られない場合は、custom_ai パラメーターで別のモデルを指定します。詳細はカスタムモデルを使う（BYO API Key）を参照してください。

JavaScript が多いページの扱い

JavaScript が多いページや Single Page Application（SPA）では、デフォルトのページ読み込み動作だと、空または不完全な結果が返ることがあります。ブラウザーが、JavaScript によるコンテンツ描画が終わる前にページ読み込み完了とみなすためです。

いちばん簡単な対処は、gotoOptions.waitUntil パラメータを networkidle0 または networkidle2 に設定することです。

{
	"url": "https://example.com",
	"gotoOptions": {
		"waitUntil": "networkidle0"
	}
}

より速い応答が必要な場合、上級者はネットワーク活動がすべて止まるのを待つのではなく、waitForSelector で特定の要素を待てます。必要なコンテンツが読み込まれたことを示す CSS セレクターを把握している必要があります。詳細は Quick Actions のタイムアウトを参照してください。

カスタム User-Agent を設定する

JSON 本文のトップレベルパラメーターとして userAgent を渡すと、ページ単位で User-Agent を変更できます。対象サイトが User-Agent に応じて別のコンテンツを返す場合に便利です。

トラブルシューティング

質問がある場合やエラーが発生した場合は、Browser Run の FAQ とトラブルシューティングガイドを参照してください。