WebExtrator Webページレンダリング API 統合ガイド

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

申請手順

WebExtrator サービスページを使用するには、まず Ace Data Cloud コンソールで API Token を取得し、控えておいてください。

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

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

認証

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

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

リクエストパラメータ

フィールド	型	必須	デフォルト	説明
`url`	string	✅	—	レンダリングするページの URL。`http(s)://` である必要があります。
`user_agent`	string	❌	内蔵 UA プールによるローテーション	カスタム User-Agent。
`timeout`	integer	❌	`30`	1回のナビゲーションのタイムアウト（正の整数秒）。
`wait_until`	enum	❌	`load`	読み込み完了イベント：`load` / `domcontentloaded` / `networkidle` / `commit`。
`delay`	integer	❌	`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`	integer	❌	`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 で能動的に照会できます。

コールバック構造

プラットフォームは同期モードと完全に同じ envelope を 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 は自動的に1回再試行する。

エラー構造：

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: Invalid 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 は従来の静的ページに適しています。
キャッシュ Key は async を無視します。 同じ URL の同期リクエストと非同期リクエストは同じキャッシュエントリにヒットするため、任意に切り替えても無効にはなりません。
キャッシュ Key は bypass_cache と cache_ttl_seconds を無視します。 この2つは操作スイッチであり、レスポンス内容には影響しません。
cookies と headers はキャッシュを分割します。 この2つをカスタマイズすると、同じ組み合わせであっても初回はヒットしません。
重い SPA はデフォルトの30秒を超えることがよくあります。 timeout: 60、wait_until: "domcontentloaded"、delay: 4 を推奨します。さらに wait_for_selector を組み合わせて、本当に関心のある要素を待機してください。
block_resources はレイテンシを下げる最速の方法です。 デフォルトで画像 / フォント / メディアはすでにブロックされています；抽出が CSS レイアウトに依存しない場合は、stylesheet を追加するとさらに速くなります。

はじめに

AIチャット

AI画像

AI動画

AIオーディオ

ウェブ＆データ

CAPTCHA

アイデンティティ

Coding

その他のガイド

WebExtrator Webページレンダリング API 統合ガイド

申請手順

認証

リクエストパラメータ

同期レスポンス

非同期レスポンス

コールバック構造

エラーレスポンス

例

cURL

Python (requests)

Node.js (fetch)

非同期 + コールバック

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

ヒントと注意点

​申請手順

​認証

​リクエストパラメータ

​Cookie 構造

​同期レスポンス

​非同期レスポンス

​コールバック構造

​エラーレスポンス

​例

​cURL

​Python (requests)

​Node.js (fetch)

​非同期 + コールバック

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

​ヒントと注意点

申請手順

認証

リクエストパラメータ

Cookie 構造

同期レスポンス

非同期レスポンス

コールバック構造

エラーレスポンス

例

cURL

Python (requests)

Node.js (fetch)

非同期 + コールバック

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

ヒントと注意点