WebExtrator ウェブレンダリング API 統合ガイド

POST https://api.acedata.cloud/webextrator/render WebExtrator ウェブレンダリング API は、ヘッドレス Chromium に基づくウェブレンダリングサービスです。URL を指定すると、完全にレンダリングされた HTML（JS 注入の内容を含む）、プレーンテキスト、ページタイトル、最終 URL を返します。 Render は WebExtrator の最も基本的なインターフェースです。構造化された抽出結果（記事本文、商品価格、レシピの材料など）が必要な場合は、/webextrator/extract を使用してください。これは同じレンダリング基盤の上で、型付き抽出パイプラインを実行します。

申請プロセス

WebExtrator サービスページを使用するには、まず Ace Data Cloud コンソールで API トークンを取得し、バックアップとして保管してください。

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。 1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、コンソールで共通残高をチャージできます。

📘 完全なドキュメント：WebExtrator サービスページ →

認証

すべての WebExtrator インターフェースは、標準の Bearer トークン認証を使用します：

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

リクエストパラメータ

フィールド	タイプ	必須	デフォルト	説明
`url`	string	✅	—	レンダリングするページの URL、必ず `http(s)://` である必要があります。
`user_agent`	string	❌	内蔵 UA プールのローテーション	カスタム User-Agent。
`timeout`	number	❌	`30`	単一ナビゲーションのタイムアウト（秒）。
`wait_until`	enum	❌	`networkidle`	ロード完了イベント：`load` / `domcontentloaded` / `networkidle` / `commit`。
`delay`	number	❌	`0`	`wait_until` トリガー後の追加待機秒数（SPA の二次レンダリングに使用）。
`wait_for_selector`	string	❌	—	この CSS セレクタが出現するのを待ちます。`networkidle` よりも安定しています。
`block_resources`	string[]	❌	`["image","font","media"]`	ブロックするリソースタイプ、オプション：`image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`。
`headers`	object	❌	—	追加の HTTP リクエストヘッダー（例：`{"Accept-Language": "en-US"}`）。
`cookies`	array	❌	—	ナビゲーション前に注入される Cookie、構造は以下の通り。
`callback_url`	string	❌	—	非同期モードでのコールバックアドレス、プラットフォームはタスク完了時にこのアドレスに結果を `POST` します。
`bypass_cache`	boolean	❌	`false`	Redis キャッシュの読み取りをスキップします（ただし、今回の結果はキャッシュに書き戻されます）。
`cache_ttl_seconds`	number	❌	`3600`	今回書き込むキャッシュの TTL をカスタマイズします。`0` を指定すると、今回のレスポンスはキャッシュされません。
`async`	boolean	❌	`false`	`true` に設定すると、すぐに `task_id` を返し、結果は `callback_url` または Tasks API で取得します。

プラットフォームの契約はすべて snake_case を使用します。内部レンダリングサービスは camelCase をサポートしていますが、外部呼び出しはすべて snake_case を使用します。

{
  "name":      "string",
  "value":     "string",
  "domain":    "string",
  "path":      "/",
  "expires":   1735689600,
  "httpOnly":  false,
  "secure":    true,
  "sameSite":  "Lax"
}

同期レスポンス

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717801.234,
  "elapsed": 1.111,
  "data": {
    "kind": "render",
    "url": "https://example.com",
    "finalUrl": "https://example.com/",
    "title": "Example Domain",
    "status": 200,
    "html": "<!DOCTYPE html><html>...</html>",
    "text": "Example Domain\nThis domain is for use in illustrative examples...",
    "userAgent": "Mozilla/5.0 ...",
    "elapsedMs": 1108
  }
}

フィールド	タイプ	説明
`data.kind`	string	固定 `"render"`。
`data.url`	string	提出した URL。
`data.finalUrl`	string	リダイレクト後の最終 URL。
`data.title`	string	レンダリング後の `document.title`。
`data.status`	number \| null	メインナビゲーションの HTTP ステータスコード。
`data.html`	string	完全なレンダリング後の HTML。
`data.text`	string	`document.body.innerText` のスナップショット（よりクリーンな本文が必要な場合は Extract を使用してください）。
`data.userAgent`	string	実際に使用された UA。
`data.elapsedMs`	number	ブラウザレンダリングにかかった時間。
`data.cached`	boolean?	キャッシュにヒットした場合は `true`。
`data.cacheStoredAt`	number?	キャッシュエントリが最初に書き込まれた Unix ミリ秒タイムスタンプ。

非同期レスポンス

async=true（または callback_url を提供）時に即座に返されます（HTTP 200）：

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

結果は callback_url に POST でプッシュされます（設定されている場合）、または /webextrator/tasks で積極的にクエリできます。

コールバック構造

プラットフォームは callback_url に同期モードと完全に同じエンベロープを POST します。 Content-Type: application/json。任意の 2xx を返すと確認されたと見なされます；5xx は指数バックオフで約 5 分間再試行されます。

エラーレスポンス

HTTP	`error.code`	含义
400	`bad_request`	リクエストボディが Zod 検証に失敗しました（`url` が欠落、タイプが不正など）。
401	`unauthorized`	無効または欠落している `Authorization: Bearer …`。
402	(x402)	プラットフォームの残高が不足しており、x402 支払い要求 envelope を返します。
408	`timeout`	ナビゲーションが `timeout` を超えました。
429	`queue_busy`	同期キューが混雑しています。再試行するか、`async=true` を使用してください。
500	`internal_error`	サーバー側で未処理の例外が発生しました（ブラウザのクラッシュなど）、Worker が自動的に再試行します。

エラー構造：

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: 無効な url" }
}

サンプル

cURL

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "wait_until": "networkidle",
    "block_resources": ["image", "media", "font"]
  }'

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/render",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "wait_until": "networkidle",
        "block_resources": ["image", "media", "font"],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["title"], data["status"], len(data["html"]))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/render', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    wait_until: 'networkidle',
    block_resources: ['image', 'media', 'font'],
  }),
});
const { data } = await res.json();
console.log(data.title, data.status, data.html.length);

非同期 + コールバック

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async": true,
    "callback_url": "https://your-app.example.com/hooks/webextrator"
  }'

即座に { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 } を返します；タスクが完了すると、プラットフォームはあなたの callback_url に完全な結果を POST します。

キャッシュを強制的にバイパス

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "bypass_cache": true
  }'

ヒントと落とし穴

wait_until の選択は非常に重要です。 networkidle は最も安定していますが最も遅い；domcontentloaded は速いですが非同期で注入された内容を見逃す可能性があります；load は従来の静的ページに適しています。
キャッシュキーは async を無視します。 同じ URL の同期と非同期リクエストは同じキャッシュエントリにヒットし、自由に切り替えても無効になりません。
キャッシュキーは bypass_cache と cache_ttl_seconds を無視します。 これらは操作スイッチであり、応答内容には影響しません。
cookies と headers はバケットキャッシュを分けます。 これらをカスタマイズすると、最初の同じ組み合わせのヒットが失敗します。
重い SPA はデフォルトの 30 秒を超えることがよくあります。 timeout: 60、wait_until: "domcontentloaded"、delay: 4 を推奨し、さらに wait_for_selector で本当に関心のある要素を待ちます。
block_resources は遅延を減らす最も早い方法です。 デフォルトで画像 / フォント / メディアはブロックされています； CSS レイアウトに依存しない抽出を行う場合、stylesheet を追加するとさらに速くなります。

はじめに

AIチャット

AI画像

AI動画

AIオーディオ

ウェブ＆データ

CAPTCHA

アイデンティティ

プロキシ

上級

WebExtrator ウェブレンダリング API 統合ガイド

申請プロセス

認証

リクエストパラメータ

同期レスポンス

非同期レスポンス

コールバック構造

エラーレスポンス

サンプル

cURL

Python (requests)

Node.js (fetch)

非同期 + コールバック

キャッシュを強制的にバイパス

ヒントと落とし穴

​申請プロセス

​認証

​リクエストパラメータ

​Cookie 構造

​同期レスポンス

​非同期レスポンス

​コールバック構造

​エラーレスポンス

​サンプル

​cURL

​Python (requests)

​Node.js (fetch)

​非同期 + コールバック

​キャッシュを強制的にバイパス

​ヒントと落とし穴

申請プロセス

認証

リクエストパラメータ

Cookie 構造

同期レスポンス

非同期レスポンス

コールバック構造

エラーレスポンス

サンプル

cURL

Python (requests)

Node.js (fetch)

非同期 + コールバック

キャッシュを強制的にバイパス

ヒントと落とし穴