> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> WebExtrator Web Render & Extract API guide - Ace Data Cloud

`POST https://api.acedata.cloud/webextrator/render`

WebExtrator ウェブレンダリング API は、ヘッドレス Chromium に基づくウェブレンダリングサービスです。URL を指定すると、完全にレンダリングされた HTML（JS 注入の内容を含む）、プレーンテキスト、ページタイトル、最終 URL を返します。

Render は WebExtrator の最も基本的なインターフェースです。**構造化された**抽出結果（記事本文、商品価格、レシピの材料など）が必要な場合は、[`/webextrator/extract`](development_webextrator_extract) を使用してください。これは同じレンダリング基盤の上で、型付き抽出パイプラインを実行します。

## 申請プロセス

WebExtrator サービスを使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API トークンを取得し、保管してください。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。

**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。

> 📘 完全なドキュメント：[WebExtrator サービスページ →](https://platform.acedata.cloud/service/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 を使用します。

### Cookie 構造

```json theme={null}
{
  "name":      "string",
  "value":     "string",
  "domain":    "string",
  "path":      "/",
  "expires":   1735689600,
  "httpOnly":  false,
  "secure":    true,
  "sameSite":  "Lax"
}
```

## 同期レスポンス

```json theme={null}
{
  "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）：

```json theme={null}
{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}
```

結果は `callback_url` に `POST` でプッシュされます（設定されている場合）、または
[`/webextrator/tasks`](development_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 が自動的に1回再試行します。 |

エラー構造：

```json theme={null}
{
  "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

```bash theme={null}
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)

```python theme={null}
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)

```js theme={null}
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);
```

### 非同期 + コールバック

```bash theme={null}
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 します。

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

```bash theme={null}
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` を追加するとさらに速くなります。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.