exa-contents

Exa Contents

API キーが必要です：https://dashboard.exa.ai/api-keys で取得してください。

ヘッダー：x-api-key: $EXA_API_KEY

エージェントがすでに URL を把握しており、新たな検索を実行せずに、LLM 向けに整形されたコンテンツを抽出したい場合は、POST https://api.exa.ai/contents を使用します。まず、コンテンツモードを 1 つ選択してください。エージェントのコンテキストを簡潔にするには highlights、ページの幅広いコンテキストを取得するには text、Exa 側で圧縮するには summary を使用します。

クイックスタート（cURL）

基本的なテキスト抽出

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://example.com"],
    "text": true
  }'

鮮度を指定したハイライト

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://arxiv.org/abs/2307.06435"],
    "highlights": {
      "query": "methodology and results"
    },
    "maxAgeHours": 24,
    "livecrawlTimeout": 12000
  }'

エンドポイント

POST https://api.exa.ai/contents

認証：x-api-key: <API_KEY> ヘッダーを使用します。Exa は Authorization: Bearer <API_KEY> も受け付けますが、一貫性を保つため、cURL の例では x-api-key を優先してください。

このエンドポイントは、URL が既知の場合のコンテンツ抽出に使用します。エージェントが先に情報の発見や順位付けを行う必要がある場合は、POST /search を使用してください。

パラメーター

リクエストの主要パラメーター

パラメーター	型	必須	デフォルト	説明
urls	string[]	はい	-	コンテンツを抽出する URL です。既知の URL に使用します。
text	boolean または object	いいえ	-	ページ全体のテキストを Markdown 形式で返します。オブジェクト形式では、maxCharacters、includeHtmlTags、verbosity、includeSections、excludeSections を指定できます。
highlights	boolean または object	いいえ	-	重要な抜粋を返します。カスタムの焦点が必要でない限り、エージェントのワークフローでは true を推奨します。
summary	boolean または object	いいえ	-	ページごとの LLM による要約を返します。呼び出し元が Exa 側での圧縮や構造化抽出を必要とする場合に使用します。
maxAgeHours	integer	いいえ	-	鮮度を制御します。0 は常にライブクロールを実行し、-1 はキャッシュのみを使用します。省略すると、デフォルトのキャッシュ優先動作となり、必要に応じてクロールにフォールバックします。
livecrawlTimeout	integer	いいえ	10000	ライブクロールのタイムアウト時間（ミリ秒）です。鮮度が重要なほとんどの呼び出しでは、10000 から 15000 を使用してください。
subpages	integer	いいえ	0	各 URL からクロールするリンク先のサブページ数です。
subpageTarget	string または string[]	いいえ	-	["api", "reference", "pricing"] のように、優先するサブページを指定するための用語です。
extras.links	integer	いいえ	0	各ページから抽出するリンクの数です。
extras.imageLinks	integer	いいえ	0	各ページから抽出する画像 URL の数です。
compliance	string	いいえ	-	アカウントで有効化されている場合に使用できる、hipaa などのエンタープライズ専用コンプライアンスモードです。

Text オブジェクトのオプション

パラメーター	型	デフォルト	説明
maxCharacters	integer	-	返されるテキストの文字数制限です。tokensNum の代わりに使用してください。
includeHtmlTags	boolean	false	出力に HTML タグを保持します。
verbosity	string	compact	compact、standard、full のいずれかです。セクションを認識した最新情報の抽出と maxAgeHours: 0 を組み合わせてください。
includeSections	string[]	-	選択したセクションのみを含めます。指定できる値は header、navigation、banner、body、sidebar、footer、metadata です。
excludeSections	string[]	-	同じセクション一覧から選択したセクションを除外します。

Highlights オブジェクトのオプション

最高品質のデフォルト設定として、highlights: true を推奨します。カスタムの焦点や予算が必要な場合に限り、オブジェクト形式を使用してください。

パラメーター	型	デフォルト	説明
query	string	-	返す抜粋を指定するためのカスタムクエリです。
maxCharacters	integer	-	URL ごとのハイライトの文字数を制限します。呼び出し元に厳格な予算がある場合を除き、省略してください。

Summary オブジェクトのオプション

パラメーター	型	デフォルト	説明
query	string	-	要約用のカスタムクエリです。
schema	object	-	ページごとの要約を構造化するための JSON Schema です。

コンテンツモード

/contents では、text、highlights、summary はリクエストのトップレベルフィールドです。

モード	最適な用途	備考
text	詳細な分析とページ全体の広範なコンテキスト	ペイロードのサイズを制限するには、maxCharacters を使用してください。
highlights	エージェントのワークフローと事実の検索	デフォルトでは最もトークン効率が高いモードです。抜粋はソースページに基づいています。
summary	要約やページごとの構造化された情報抽出	ページごとに Exa 側での統合が追加されます。

呼び出し元が同じページを複数の見方で本当に必要とする場合を除き、複数のモードをリクエストしないでください。

鮮度とクロール

鮮度を制御する標準的な方法として、maxAgeHours を使用してください。

値	動作
省略	キャッシュ優先のデフォルト動作を使用し、必要に応じてクロールにフォールバックします。
正の整数	キャッシュが N 時間未満であればキャッシュを使用し、それ以外の場合はライブクロールします。
0	常にライブクロールします。鮮度は最も高くなりますが、レイテンシーも高くなります。
-1	キャッシュのみを使用します。最速ですが、キャッシュされたコンテンツがない場合は失敗します。

ライブクロールが所定の時間を超えてブロックしないようにするには、livecrawlTimeout を設定してください。

サブページと追加情報

リンク先のページが重要な場合は、subpages と subpageTarget を使用してください。

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://docs.example.com"],
    "text": {
      "maxCharacters": 5000
    },
    "subpages": 10,
    "subpageTarget": ["api", "reference", "guide"],
    "extras": {
      "links": 10,
      "imageLinks": 5
    }
  }'

まず subpages を 5 から 10 程度に設定し、呼び出し元がサイト全体をより広くカバーする必要がある場合にのみ増やしてください。

レスポンスフィールドとステータス

HTTP ステータスが 200 の場合でも、statuses を確認してください。同じリクエスト内で、ある URL の処理が成功して別の URL の処理が失敗することがあります。

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://example.com", "https://failed-url.example.com"],
    "highlights": true
  }' | jq '{results, statuses}'

フィールド	型	説明
requestId	string	一意のリクエスト識別子です。
results	array	抽出されたコンテンツの結果オブジェクトです。
results[].title	string	ページタイトルです。
results[].url	string	ページ URL です。
results[].publishedDate	string or null	利用可能な場合は、推定公開日です。
results[].author	string or null	利用可能な場合は、著者です。
results[].text	string	text がリクエストされた場合に返されます。
results[].highlights	string[]	highlights がリクエストされた場合に返されます。
results[].highlightScores	number[]	ハイライトの類似度スコアです。
results[].summary	string	summary がリクエストされた場合に返されます。
results[].subpages	array	サブページのクロールから得られた、入れ子になった結果オブジェクトです。
results[].extras.links	string[]	リクエストされた場合に抽出されたリンクです。
statuses	array	URL ごとの成功またはエラーの状態です。このフィールドは必ず確認してください。
statuses[].id	string	リクエストされた URL です。
statuses[].status	string	success または error です。
statuses[].error.tag	string	失敗した URL のエラー種別です。
statuses[].error.httpStatusCode	integer or null	URL ごとの失敗に関連付けられた HTTP コードです。
costDollars.total	number	返される場合は、リクエストの合計コストです。

URL ごとによく発生するエラータグには、CRAWL_NOT_FOUND、CRAWL_TIMEOUT、CRAWL_LIVECRAWL_TIMEOUT、SOURCE_NOT_AVAILABLE、UNSUPPORTED_URL、CRAWL_UNKNOWN_ERROR があります。

重大な注意点

• /contents では、text、highlights、summary をトップレベルに指定してください。
• 抽出オプションを contents オブジェクトで囲まないでください。この入れ子構造は /search 用です。
• HTTP 200 でもすべての URL の処理が成功したとは限りません。statuses を確認してください。
• stream: true を送信しないでください。/contents はストリーミングエンドポイントではありません。
• tokensNum を送信しないでください。抽出テキストの上限には text.maxCharacters を使用してください。
• 新しいリクエストでは、useAutoprompt、numSentences、highlightsPerUrl、または古い livecrawl の文字列値を使用しないでください。
• 鮮度の制御には maxAgeHours を優先し、クロールのレイテンシーが問題となる場合は livecrawlTimeout と併用してください。
• subpages を使用する場合は subpageTarget も指定してください。指定しない場合、サブページの選択はベストエフォートになります。
• デフォルトでは、highlights、text、summary のいずれか 1 つを選択してください。各ページを複数の見方で本当に必要とする場合にのみ、複数のモードを組み合わせてください。