octen-extract

Octen Extract

1 つ以上の URL を、LLM が扱いやすいクリーンなコンテンツに変換します。ページ本文に加え、各結果には カテゴリ と ページ構造のラベルが含まれます。また、query を渡すと、ページ全体ではなく クエリに関連するハイライトが返されます。

API キーが必要です：https://octen.ai で取得できます。設定するには、export OCTEN_API_KEY=your-api-key を実行します。

API キーの設定

抽出を始める前に、OCTEN_API_KEY が設定されていることを確認してください。401 が返された場合は処理を中断し、キーが必要であること（https://octen.ai）をユーザーに伝えて設定を案内してから、続行してください。 他の Octen スキルと同様に、該当するエージェント用にキーを設定します。

• Claude Code — ~/.claude/settings.json に { "env": { "OCTEN_API_KEY": "your-key" } } を追加します
• Cursor / 汎用シェル — ~/.zshrc または ~/.bashrc で export OCTEN_API_KEY="your-key" を実行します
• Codex — ~/.codex/config.toml の [shell_environment_policy] に set = { OCTEN_API_KEY = "your-key" } を設定します
• OpenClaw — ~/.openclaw/.env に OCTEN_API_KEY=your-key を追加します

エンドポイント

POST https://api.octen.ai/extract

認証：X-Api-Key: <API_KEY> ヘッダー · Content-Type：application/json

クイックスタート（cURL）

一括抽出（全文）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://example.com", "https://octen.ai"],
    "format": "markdown"
  }'

クエリに基づくハイライト（全文の代わり）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://en.wikipedia.org/wiki/Python_(programming_language)"],
    "query": "async programming"
  }'

難易度の高いサイト（上級モード）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://www.reddit.com/r/LocalLLaMA/"],
    "mode": "advanced",
    "timeout": 60
  }'

混在する一括処理、難易度不明（自動モード）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://example.com", "https://octen.ai", "https://news.ycombinator.com/item?id=1"],
    "mode": "auto",
    "timeout": 60
  }'

ページリンク（外部参照を優先）

curl -s -X POST "https://api.octen.ai/extract" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "urls": ["https://octen.ai"],
    "include_links": {"scope": "prefer_external", "max_links": 50}
  }'

パラメーター

パラメーター	型	必須	デフォルト	説明
urls	string[]	はい	-	1 回の一括処理で取得する 1～20 個の URL
mode	string	いいえ	standard（省略時）	standard、advanced、または auto。モードの選択を参照してください
query	string	いいえ	-	設定すると、各結果でクエリに関連する highlights が返され、full_content は省略されます（最大 500 文字）
max_age_seconds	integer	いいえ	86400	この経過時間以内のキャッシュ結果を受け入れます（最小 300）。これより古いキャッシュ済みバージョンは再取得されます
format	string	いいえ	markdown	コンテンツ形式：markdown または text
timeout	integer	いいえ	30	URL ごとの取得時間上限（秒）（1～60）
include_images	boolean	いいえ	false	ページで見つかった画像リソースを含めます（ページにカバー画像がある場合は cover_image も返します）
include_videos	boolean	いいえ	false	ページで見つかった動画 URL を含めます
include_audio	boolean	いいえ	false	ページで見つかった音声 URL を含めます
include_links	object	いいえ	-	サイトのページを見つけたり、外部参照をたどったりする場合に使用します。ページのリンクを返します：{scope, max_links}。scope：prefer_internal（デフォルト。同一サイトのリンクを優先）または prefer_external（他の登録済みドメインを優先）。各グループ内ではページ上の順序が維持されます。max_links：1～1000（デフォルト 200。範囲外の場合は 400 が返され、値は上限・下限に丸められません）。{} を指定すると両方のデフォルトが使用されます

モードの選択

モードを選択します。省略した場合は standard です。

• standard（デフォルト）：最も高速で低コストです。ニュース、ブログ、ドキュメント、製品ページ、静的サイトなど、ボット対策のない一般的で構成の整ったページに適しています。ログインが必要なサイト、JavaScript を多用するサイト、ボット対策のあるサイトでは、status: "success" と報告されても、コンテンツが空だったり、ページの骨組みだけが返されたりすることがあります。
• advanced：成功率が最も高く、より強力なボット対策機能を備えた実際のブラウザーでページをレンダリングします。処理は遅く、料金は 2.5 倍です。ボット対策／WAF で保護されたサイト、JavaScript を多用する SPA、ソーシャルサイト（Reddit、X、LinkedIn）、学術サイト（ResearchGate）、動的に読み込まれるコンテンツなど、取得が難しいとわかっているサイトに使用します。
• auto：URL ごとにモードを判断します。standard で十分な場合は standard を使用し、取得が難しい URL にのみ advanced を使用します。各 URL の料金は、実際に使用されたモードに基づきます。どの URL の取得が難しいか判断できない場合に、モードが混在するバッチで使用します。取得が難しい URL が大半の場合、料金はすべてを advanced にした場合に近づきます。

シナリオ	mode
ニュース／ブログ／ドキュメント／製品ページ（一般的なサイト）	standard（または省略）
取得が難しいとわかっているサイト（Reddit／X／LinkedIn／ResearchGate／ボット対策／SPA）	advanced
モードが混在するバッチで、どれが取得困難かわからない場合	auto
コスト重視で、一般的なサイトが大半の場合	standard
品質優先で、取得が難しいサイトが大半の場合	advanced

目安：すべて一般的なサイトなら standard（または省略）、取得が難しいとわかっているサイトなら advanced、混在している場合や判断できない場合は auto を使用します。

リカバリー：standard の結果が失敗した場合、またはコンテンツが空／骨組みだけで返された場合（page_structure.primary が "No Main Content"、または本文があるはずのページでコンテンツが非常に短い場合）は、該当する URL のみ "mode": "advanced" で再試行します。

タイムアウト：advanced と auto は処理に時間がかかるため、timeout を大きくしてください（例：60）。

レスポンス形式

フィールド	型	説明
request_id	string	一意のリクエスト ID
data.results[]	array	URL ごとに 1 件の結果
data.results[].url	string	URL
data.results[].status	string	success または failed
data.results[].resolved_mode	string?	standard または advanced — この URL に実際に使用されたモードです。成功時に存在し、失敗時は存在しません。リクエストしたモードと異なる場合があります（auto は URL ごとにモードを選択し、advanced が standard に切り替わることがあります）
data.results[].error_message	string?	失敗理由（status が failed の場合）
data.results[].title	string?	ページタイトル
data.results[].full_content	string?	ページの整形済みコンテンツ（query がない場合）
data.results[].highlights	string[]?	クエリに関連する抜粋（query が設定されている場合）
data.results[].category	object?	{primary, secondary} — ページの内容
data.results[].page_structure	object?	{primary, secondary} — ページの種類
data.results[].time_published	string?	公開時刻、ISO 8601
data.results[].time_last_crawled	string?	最終クロール時刻、ISO 8601
data.results[].favicon	string?	ページのファビコン URL — 利用可能な場合はデフォルトで返されます
data.results[].cover_image	object?	{url} — ページのカバー画像（include_images が true で、ページに画像がある場合）
data.results[].images / videos / audio	object[]?	[{url}] — ページで見つかったメディア（一致する include_* が true の場合）
data.results[].links	object[]?	[{url, anchor_text, is_external}] — ページのリンク（成功時に include_links が設定され、リンクが見つかった場合）
meta.usage.total_urls	integer	リクエストされた URL 数
meta.usage.successful_urls	integer	取得に成功した URL 数
meta.usage.successful_by_mode	object	{standard_urls, advanced_urls} — モードごとの取得に成功した URL 数。実際の請求額は resolved_mode の合計ではなく、この数値に基づきます
meta.warning	string	例："1 URL(s) failed and were not billed"。報告事項がない場合は空文字列

meta はトップレベルにあり（data の兄弟要素）、data.meta ではありません。

エラーコード

HTTP ステータス	説明
400	パラメーターがないか、無効です
401	API キーが無効か、指定されていません
403	残高が不足しています
429	レート制限に達しました
500	内部サーバーエラー

注意事項

• 部分的な成功を標準でサポートしています：失敗した URL は status: "failed" と error_message を伴って返されます。同じバッチ内のほかの URL は引き続き成功します。結果ごとの status を必ず確認してください。
• RAG／グラウンディング用に焦点を絞った highlights が必要な場合にのみ query を渡してください。ページ全体をクリーンアップした内容を取得する場合は省略します。
• 料金：standard は成功した URL 1,000 件あたり $1、advanced は 1,000 件あたり $2.5 です。失敗した URL は課金されません。
• category と page_structure を使うと、本文全体を読まずにページを振り分けたり、フィルタリングしたりできます（例：インデックス／操作ページを除外し、コンテンツページを残す）。