octen-search

Octen Search

Octen の検索スキルです。リアルタイムのウェブ検索と広範検索（複数クエリ）を利用できます（下記の広範検索を参照）。画像検索と動画検索は、それぞれ別のocten-image-searchスキルとocten-video-searchスキルで利用できます。

API キーが必要です：https://octen.ai で取得してください

設定方法：export OCTEN_API_KEY=your-api-key

API キーの設定

検索する前に、OCTEN_API_KEY が設定されていることを確認してください。未設定の場合、またはいずれかの呼び出しで 401 が返された場合は、そこで停止し、むやみに再試行しないでください。ユーザーにキーが必要であることを伝え、https://octen.ai で取得するよう案内し、使用するエージェント向けの設定をサポートしてください（下記参照）。設定が完了したら続行してください。

該当するエージェント／ランタイムにキーを設定します。

• Claude Code — ~/.claude/settings.json に { "env": { "OCTEN_API_KEY": "your-key" } } を追加します（一時的なシェルの export は保持されません）
• Cursor / Hermes / 汎用シェル — ~/.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 を追加します

エージェントごとの詳しい手順は、READMEを参照してください。

クイックスタート（cURL）

基本検索

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{"query": "latest AI research 2026", "count": 5}'

ハイライトと時間フィルタリングを使用

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "summary judgment",
    "count": 10,
    "time_basis": "published",
    "start_time": "2025-01-01T00:00:00Z",
    "end_time": "2026-01-01T00:00:00Z",
    "highlight": {"enable": true, "max_tokens": 300}
  }'

ドメインフィルタリングを使用

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "climate change policy",
    "count": 5,
    "include_domains": ["nature.com", "science.org"],
    "exclude_domains": ["spam.com"]
  }'

言語フィルタリングを使用

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "climate change 2026",
    "count": 5,
    "language": ["ja", "zh"]
  }'

全文コンテンツを取得

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "latest WHO guidance on influenza vaccination",
    "count": 5,
    "full_content": {"enable": true, "max_tokens": 1000}
  }'

エンドポイント

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

認証：X-Api-Key: <API_KEY> ヘッダー

Content-Type：application/json

パラメーター

パラメーター	型	必須	デフォルト	説明
query	string	はい	-	検索クエリ（最大 500 文字）
topic	string	いいえ	general	検索分野：general または news
count	integer	いいえ	5	結果数（1～100）
include_domains	string[]	いいえ	-	これらのドメインの結果のみを含めます（最大 1200 ドメイン、各最大 60 文字）
exclude_domains	string[]	いいえ	-	これらのドメインの結果を除外します（最大 1200 ドメイン、各最大 60 文字）
include_text	string[]	いいえ	-	結果ページのテキストに含まれている必要がある文字列（最大 5 項目、各最大 30 文字）
exclude_text	string[]	いいえ	-	結果ページのテキストに含まれていてはならない文字列（最大 5 項目、各最大 30 文字）
language	string[]	いいえ	[]	ISO 639-1 コードで指定した言語に結果を絞り込みます（例：["en", "ja"]）。対応言語：ar、de、en、es、fr、hi、id、it、ja、ko、nl、pl、pt、ru、th、tr、vi、zh。空の場合、言語フィルターは適用されません。https://localizely.com/iso-639-1-list/ を参照してください
time_basis	string	いいえ	auto	フィルタリングに使用する時間フィールド：auto、published、crawled
start_time	string	いいえ	-	開始時刻フィルター。ISO 8601 形式（例：2025-01-01T00:00:00Z）
end_time	string	いいえ	-	終了時刻フィルター。ISO 8601 形式（start_time より後である必要があります）
highlight	object	いいえ	{"enable": true}	ハイライトのオプション（下記参照）
format	string	いいえ	text	ハイライトの出力形式：text または markdown
safesearch	string	いいえ	strict	アダルトコンテンツのフィルター：off または strict
full_content	object	いいえ	{"enable": false}	全文コンテンツのオプション（下記参照）
include_images	boolean	いいえ	false	結果ごとにページのカバー画像と本文内の画像を返します（「レスポンスフィールド」を参照）。画像を検索する場合は、代わりに octen-image-search スキルを使用してください

ハイライトのオプション

フィールド	型	デフォルト	説明
enable	boolean	true	各結果でクエリに関連するハイライトを返します
max_tokens	integer	512	ハイライトあたりの最大トークン数（100～20000）

全文コンテンツのオプション

フィールド	型	デフォルト	説明
enable	boolean	false	各結果のページコンテンツ全体を未加工のまま返します
max_tokens	integer	2048	結果あたりの最大トークン数（100～100000）

レスポンス形式

レスポンスフィールド

フィールド	型	説明
code	integer	ステータスコード。0 = 成功
msg	string	人が読める形式のステータスメッセージ
request_id	string	一意のリクエスト識別子
data.query	string	元のクエリ
data.results[]	array	検索結果の一覧
data.results[].title	string	ページタイトル
data.results[].url	string	ページの URL
data.results[].highlight	string?	クエリに関連する抜粋（highlight.enable が true の場合）
data.results[].full_content	string?	ページの全文（full_content.enable が true の場合）
data.results[].authors	string?	ウェブサイト名または著者
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, description}（include_images が true で、ページに画像がある場合）
data.results[].images[]	array?	ページ本文内の画像を、表示順に {url, description} として格納（include_images が true の場合）
meta.usage.num_search_queries	integer	実行された検索クエリの数
meta.usage.full_content_tokens	integer	full_content で返されたトークンの合計数
meta.latency	number	レスポンス時間（ミリ秒）
meta.warning	string?	警告メッセージ（ある場合）

JSON の例

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "latest WHO guidance on influenza vaccination",
    "results": [
      {
        "title": "Influenza (Seasonal) - World Health Organization (WHO)",
        "url": "https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal)",
        "highlight": "WHO recommends annual vaccination for high-risk groups\n\n...\n\nSeasonal influenza vaccination policies vary by region...",
        "authors": "World Health Organization",
        "time_published": "2024-10-15T00:00:00Z",
        "time_last_crawled": "2026-01-20T02:12:34Z"
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1,
      "full_content_tokens": 0
    },
    "latency": 237,
    "warning": null
  }
}

広範検索

広範検索では、クエリをさまざまな観点から複数の関連サブクエリに展開して並行検索し、結果をサブクエリごとにグループ化して返します（グループ間で重複排除はされません）。回答全体の根拠としてすぐに利用できます。

次の場合に使用します：単一の /search では関連するサブトピックを十分に網羅できない場合：

• 複数の情報源にわたる比較（価格、製品、ベンダー）
• 調査／詳細なリサーチ
• 複数の側面を持つ多角的な質問

焦点を絞った検索には、通常の /search を使用してください。

元のクエリをそのまま渡してください。Octen がサブクエリを生成するため、質問を書き換えたり、複数の呼び出しに事前分割したりしないでください。対象範囲を広げるには、max_queries を増やします（デフォルトは 5、調査／リサーチでは最大 30、検索を絞る場合は少なめに設定します）。

エンドポイント

POST https://api.octen.ai/broad-search

例

curl -s -X POST "https://api.octen.ai/broad-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "compare cloud GPU pricing across major providers",
    "max_queries": 5,
    "search_options": {"count": 10, "highlight": {"enable": true}}
  }'

パラメーター

パラメーター	型	必須	デフォルト	説明
query	string	はい	-	元の検索クエリ（最大 500 文字）
max_queries	integer	いいえ	5	生成するサブクエリ数の上限（1～30）。調査／リサーチでは 30 に近づけ、検索を絞る場合は少なめに設定します
search_options	object	いいえ	-	各サブクエリに適用するオプション。パラメーター表と同じフィールドおよびデフォルト値（topic、count、include_domains、language、時間フィルター、highlight、full_content、include_images など）

レスポンス

Search と同じエンベロープ（code、msg、request_id、meta）です。data には次の内容が含まれます。

フィールド	型	説明
data.query	string	元のクエリ
data.queries[]	string[]	生成されたサブクエリ
data.search_results[]	array	サブクエリごとに 1 つの結果グループ
data.search_results[].query	string	このグループのサブクエリ
data.search_results[].results[]	array	そのサブクエリの結果（Search の data.results[] と同じ形式）
data.search_results[].latency	integer	そのサブクエリのレイテンシー（ミリ秒）

エラーコード

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

セキュリティ

• API キーは、HTTPS 経由でハードコードされたエンドポイント https://api.octen.ai/search にのみ送信されます
• 認証には標準の X-Api-Key ヘッダーを使用します
• 環境変数がほかのエンドポイントや外部サービスに送信されることはありません

注意事項

• ハイライトはデフォルトで有効です。無効にするには "highlight": {"enable": false} を設定してください
• 全文コンテンツはデフォルトで無効です。有効にすると、RAG／グラウンディング用のページの生テキストを取得できます
• 信頼できるソースに結果を絞り込むには、include_domains ／ exclude_domains を使用してください
• language（ISO 639-1 コード。例：["ja", "zh"]）を使用すると、結果を言語で絞り込めます。Broad Search では、トップレベルではなく search_options の中に設定してください
• 公開時刻またはクロール時刻で結果を絞り込むには、time_basis とともに start_time ／ end_time を使用してください
• format: "markdown" はハイライトを Markdown 形式で返し、format: "text" はプレーンテキストで返します