venice-augment

Venice Augment（テキスト解析／スクレイピング／検索）

独自のパーサー、クローラー、検索アカウントを使わずに、ドキュメントのテキスト、Web ページ、検索結果を必要とするエージェントのパイプライン向けの、軽量なヘルパーを3つ提供します。ドキュメントでは、3つすべてが実験的とされています。リクエスト／レスポンスの形式は変更される場合があります。

エンドポイント	入力	出力	料金
POST /augment/text-parser	multipart/form-data の file（≤ 25 MB）	{ text, tokens } の JSON、または text/plain	成功した呼び出し1回につき $0.01
POST /augment/scrape	{ url }	{ url, content, format: "markdown" }	成功した呼び出し1回につき $0.01
POST /augment/search	{ query, limit?, search_provider? }	{ query, results: [{ title, url, content, date }] }	成功した呼び出し1回につき $0.01

3つすべてで、Bearer API キーまたはx402 ウォレット（SIGN-IN-WITH-X ヘッダー）を使用できます。詳しくは venice-auth を参照してください。処理の実行前に残高が確認され、料金は 200 レスポンスが返された後にのみ請求されます。（OpenAPI の x-payment-info には、汎用的な動的価格帯として $0.001–$10.00 が表示されていますが、実際の料金表での請求額は $0.01 です。）

POST /augment/text-parser — ドキュメントからテキストを抽出

リクエスト

常に multipart/form-data を使用します。

フィールド	説明
file	必須。最大 25 MB（超過すると → 413）。
response_format	json（デフォルト）または text。

受け付けるファイル形式（MIME タイプで判定します。MIME タイプが認識されない場合は、application/octet-stream などの場合にファイル名の拡張子で判定します）。

• 構造化ドキュメント： PDF、EPUB、DOCX、PPTX、XLSX、XLS。旧形式の .doc と .ppt は受け付けられません。
• テキスト／データ： 任意の text/* MIME タイプに加え、Markdown、CSV/TSV、JSON/JSONL、YAML、TOML、XML、HTML、RTF、LaTeX、ログなど。
• ソースコード： .py、.ts、.js、.go、.rs、.c、.cpp、.java、.sh、.ps1、.sql などに加え、拡張子のない Dockerfile／Makefile（テキスト／データ／コードの拡張子を合計約140種類認識します）。

それ以外の形式は → 400 Unsupported file type になります。

curl -X POST https://api.venice.ai/api/v1/augment/text-parser \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "file=@./contract.pdf" \
  -F "response_format=json"

レスポンス

response_format=json：

{
  "text": "…extracted text…",
  "tokens": 3821
}

response_format=text — 抽出されたテキストをそのまま本文として返します（Content-Type: text/plain）。

ヒント

• DOCX、PPTX、XLSX/XLS、EPUB はマークダウン形式で返されます（スプレッドシートはマークダウンの表になります）。PDF とテキストファイルはプレーンテキストで返されます。
• tokens は文字数を基にした推定値（ceil(chars / 3.2)）であり、モデルのトークナイザーによるカウントではありません。後続のチャットリクエストの大まかな予算見積もりに使用してください。
• スキャンされた PDF や画像のみの PDF は OCR されません。抽出できる内容がない場合は、400 "No text content could be extracted from the file." が返されます。代わりに、ページ画像を /chat/completions 経由でビジョンモデルに渡してください。
• パスワードで保護された PDF は 400 "The PDF file is password-protected…"、空または破損した PDF は 400 "The PDF file is empty or invalid." になります。
• ドキュメントはメモリ上で処理され、レスポンス後に内容は保持されません。（リクエスト ID やエラートレースなどの運用メタデータは記録される場合があります。これは内容を保持しないことを保証するものであり、ログが一切記録されないことを保証するものではありません。）

POST /augment/scrape — URL → マークダウン

リクエスト

{ "url": "https://example.com/article" }

url は有効な絶対 http:// または https:// URL である必要があります。

curl -X POST https://api.venice.ai/api/v1/augment/scrape \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

レスポンス

{
  "url": "https://example.com",
  "content": "# Example Domain\n\nThis domain is for use in …",
  "format": "markdown"
}

取得方法

マークダウンを直接配信するサイトでは、その内容がそのまま返されます。それ以外の場合は、ページを取得してマークダウンに変換します。リダイレクトは追跡されますが、転送先がプライベート／内部の対象の場合、リクエストは失敗します（以下を参照）。X／Reddit のブロックリストは、リダイレクト先ではなく、送信した URL に対して確認されます。

ヒント

• ブロックされるサイト — x.com、twitter.com（www. / mobile. を含む）、reddit.com（www. / old. / new. を含む）は、ただちに 400 で拒否されます。これらのサイトには、/chat/completions の enable_x_search または enable_web_search を使用してください。詳細は venice-chat を参照してください。
• ブロックされる URL — HTTP(S) 以外のスキーム、認証情報が埋め込まれた URL、localhost / プライベート / 予約済み IP、クラウドメタデータのホストは 400 を返します。こうした宛先に解決またはリダイレクトされる公開ホスト名は 500 になります。
• 到達できないホスト、タイムアウト、抽出可能なコンテンツがないページは、メッセージ（例："URL unreachable: …"）とともに 500 を返します。課金されません。
• 一部のサイトは本文の一部のみを返します。モデルに渡す前に content の長さを確認してください。
• レート制限：ユーザーあたり 1 分間に 20 リクエスト（超過すると 429）。カウンターは URL の検証前に動作するため、拒否された URL もカウントされます。

POST /augment/search — ウェブ検索

リクエスト

フィールド	備考
query	必須。1～400 文字。これを超えると切り捨てではなく 拒否（400）されます。
limit	整数 1～20。デフォルトは 10 です。以下の上限を参照してください。
search_provider	"brave"（デフォルト）または "google"。

curl -X POST https://api.venice.ai/api/v1/augment/search \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "venice ai api pricing",
    "limit": 5,
    "search_provider": "brave"
  }'

レスポンス

{
  "query": "venice ai api pricing",
  "results": [
    {
      "title": "Pricing — Venice.ai",
      "url": "https://venice.ai/pricing",
      "content": "Venice offers per-token pricing …",
      "date": "2026-04-10"
    }
  ]
}

• date はプロバイダーが返す値であり、空文字列の場合もあります。固定形式を前提にしないでください。
• スニペットのない結果は除外されるため、limit より少ない件数になることがあります。検索結果がない場合は results: [] を含む 200 が返されます（課金は発生します）。

プロバイダー

プロバイダー	データ保持	結果数	content
brave（デフォルト）	ゼロデータ保持 — プロバイダーによってクエリが保存または記録されることはありません。	最大 10 件	スニペットと追加のスニペット。
google	匿名化 — Venice 経由でプロキシされるため、クエリにユーザーの身元は関連付けられません。Venice はクエリを保存または記録しません。	最大 5 件	抽出されたページの要約／Markdown（より長い内容）を、上限に合わせて切り詰めます。

limit は最大 20 まで指定できますが、上流へのリクエストは brave では 10 件、google では 5 件に固定されているため、これらの上限を超える値を指定しても効果はありません。

ヒント

• チャット補完内で引用付きの回答を得るには、代わりに venice_parameters.enable_web_search と enable_web_citations を指定して /chat/completions を使用してください。詳細は venice-chat を参照してください。
• 「検索＋読み込み」のパイプラインでは、results[*].url を /augment/scrape に渡してください。スクレイピングの上限は 1 分間に 20 回です。
• レート制限：ユーザーあたり 1 分間に 20 リクエスト（超過すると 429）。本文の検証に失敗したリクエストもカウントされます。

エラー

ステータス	原因
400	ファイルがない、未対応のファイル形式、抽出可能なテキストがない、パスワード保護または無効な PDF、無効またはブロックされた URL（X、Reddit、プライベート／内部）、空または 400 文字を超えるクエリ、範囲外の limit、スクレイピング／検索で Content-Type が JSON 以外（"'Content-Type' must be 'application/json'"）。本文：{ error }、またはスキーマの検証に失敗した場合は { error: "Invalid request parameters", details, issues }。
401	API キーまたは SIWX 署名が無効です。
402	残高不足、またはキーの USD／DIEM 使用上限に達しています。Bearer の場合は "Insufficient USD or Diem balance…"、x402 の場合は支払い要求の本文と PAYMENT-REQUIRED ヘッダーが返されます。認証情報がまったくないリクエストも 402 を返します（x402 の検出チャレンジ）。
403	アカウントの API アクセスが無効になっています（"API access has been disabled for this account…"）。
413	テキストパーサーに渡された 25 MB を超えるファイル（PAYLOAD_TOO_LARGE）。
429	エンドポイントごとのレート制限（スクレイピング／検索：1 分間に 20 回）、または失敗リクエストのリミッター。ジッターを加えて待機してください。
500	スクレイピングの取得失敗、検索プロバイダーの失敗（"Search provider failed to return results…"）、または解析の失敗（"Failed to parse document"）。課金されません。安全に再試行できます。

本文の形式と再試行方法については、venice-errors を参照してください。

レスポンスヘッダー

• X-Balance-Remaining — x402 の呼び出し元向け仕様には記載されていますが、現在サーバーでは設定されていません。代わりに GET /x402/balance/{walletAddress} をポーリングしてください。
• x-ratelimit-limit-requests / x-ratelimit-remaining-requests / x-ratelimit-reset-requests — スクレイピングと検索に使用します。
• Content-Encoding — Accept-Encoding: gzip, br を送信した場合に設定されます。

パターン

• ドキュメントの質問応答 — PDF を /augment/text-parser にアップロードし、text を /chat/completions のメッセージに入れて質問します。
• リサーチエージェント — /augment/search → 上位の URL に対して /augment/scrape → マークダウン本文を使って /chat/completions を実行します。
• データ抽出 — XLSX を text-parser に渡すとマークダウンの表が生成されます。これを response_format: { type: "json_schema", ... } とともにモデルに渡せます。
• コードレビュー — ソースファイルをそのまま text-parser に送信し（PDF に変換する必要はありません）、テキストをコーディングモデルに渡します。