← Browser Run / browser-run / quick-actions

/json - Получение структурированных данных с помощью ИИ

/json эндпоинт извлекает структурированные данные со страницы. Ожидаемый результат можно указать с помощью prompt или response_format параметр, который принимает JSON-схему. Эндпоинт возвращает извлечённые данные в формате JSON.

Этот эндпоинт можно использовать двумя способами:

REST API: Создайте пользовательский API Token с Browser Rendering - Edit разрешение.
Workers Bindings: вызывайте конечную точку напрямую из Cloudflare Worker с помощью Workers Bindings. API-токен не требуется.

Подробнее см. в Quick Actions: прежде чем начать.

Конечная точка

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

Обязательные поля

Необходимо указать либо url или html:

url (строка)
html (строка)

И как минимум одно из следующего:

prompt (строка), или
response_format (объект со схемой JSON Schema)

Типичные варианты использования

Извлечение информации о товаре (название, цена, наличие) или списков объявлений (вакансии, аренда)
Нормализация метаданных статьи (заголовок, автор, дата публикации, канонический URL)
Преобразование неструктурированных страниц в типизированный JSON для дальнейшей обработки

Базовое использование

С Prompt и JSON schema

В этом примере данные веб-страницы извлекаются с помощью промпта и JSON-схемы. Промпт направляет процесс извлечения, а 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>;

Только с prompt

В этом примере указан только промпт. Эндпоинт использует его для извлечения данных, но ответ не будет структурирован по 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 schema (без prompt)

В этом случае вы передаете JSON-схему через response_format параметр. Схема определяет структуру извлекаемых данных.

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 это bearer-токен или API-ключ, который позволяет Browser Run обращаться к провайдеру от вашего имени.

В этом примере используется custom_ai параметр, чтобы указать Browser Run использовать модель Claude Sonnet 4 от Anthropic. Промпт просит модель извлечь основной <h1> и <h2> заголовки с целевого URL и возвращает их в виде структурированного объекта 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"
	}
}

Использование пользовательской модели с резервными вариантами

Можно указать несколько моделей для автоматического failover. Browser Run будет пробовать модели по порядку, пока одна из них не сработает. Чтобы добавить failover, укажите дополнительные модели в custom_ai массив.

В этом примере Browser Run сначала обращается к модели Claude Sonnet 4 от Anthropic. Если запрос завершается ошибкой, автоматически выполняется повторная попытка с моделью Meta Llama 3.3 70B из Workers AI, затем GPT-4o от OpenAI.

"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 и одностраничных приложений (SPA) поведение загрузки по умолчанию может давать пустые или неполные результаты. Дело в том, что браузер считает страницу загруженной ещё до того, как JavaScript закончит рендеринг контента.

Проще всего использовать gotoOptions.waitUntil параметр со значением networkidle0 или networkidle2:

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

Для более быстрого отклика опытные пользователи могут использовать waitForSelector чтобы дожидаться появления конкретного элемента вместо ожидания остановки всей сетевой активности. Для этого нужно знать, какой CSS-селектор указывает на загрузку нужного контента. Подробнее см. в Тайм-ауты Quick Actions.

Задайте собственный User-Agent

User-Agent можно изменить на уровне страницы, передав userAgent в качестве параметра верхнего уровня в теле JSON. Это полезно, если целевой сайт показывает разный контент в зависимости от User-Agent.

Устранение неполадок

Если у вас есть вопросы или возникла ошибка, см. Часто задаваемые вопросы и руководство по устранению неполадок Browser Run.