venice-augment

Venice Augment（文本解析 / 抓取 / 搜索）

为需要获取文档文本、网页或搜索结果的 Agent 工作流提供三个轻量级辅助工具，无需运行自己的解析器、爬虫或搜索账号。文档中将这三项功能都标记为实验性——请求 / 响应格式可能会变化。

端点	输入	输出	价格
POST /augment/text-parser	multipart/form-data file（≤ 25 MB）	{ text, tokens } JSON，或 text/plain	每次成功调用 $0.01
POST /augment/scrape	{ url }	{ url, content, format: "markdown" }	每次成功调用 $0.01
POST /augment/search	{ query, limit?, search_provider? }	{ query, results: [{ title, url, content, date }] }	每次成功调用 $0.01

三项功能都接受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 会以 markdown 格式返回（电子表格会转换为 markdown 表格）。PDF 和文本文件会以纯文本返回。
• tokens 是基于字符数的估算值（ceil(chars / 3.2)），并非模型分词器统计值——可用于粗略估算后续聊天请求的预算。
• 扫描版 / 纯图片 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 → markdown

请求

{ "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"
}

获取方式

直接提供 markdown 的网站会原样返回内容；否则会抓取网页并转换为 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。
• 被屏蔽的网址 — 非 HTTP(S) 协议、包含嵌入式凭据的网址、localhost / 私有 / 保留 IP，以及云元数据主机都会返回 400。解析到或重定向到此类目标的公共主机名会失败并返回 500。
• 无法访问的主机、超时以及没有可提取内容的页面会返回 500 和一条消息（例如 "URL unreachable: …"）。不会向你收费。
• 有些网站会返回部分正文。将其传入模型前，请检查 content 长度。
• 速率限制：每位用户每分钟 20 个请求（超出后返回 429）。计数器会在 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。搜索无匹配结果时会返回 200 和 results: []（仍会收费）。

提供商

提供商	保留策略	结果数	content
brave（默认）	零数据保留 — 提供商不会存储或记录查询。	最多 10 条	摘要及其他附加摘要。
google	匿名化 — 通过 Venice 代理，因此查询不会关联到你的身份；Venice 不会存储或记录查询。	最多 5 条	提取的页面摘要/Markdown（内容更长），并会截断以符合预算。

limit 最高可设为 20，但上游请求对 brave 固定返回 10 条结果，对 google 固定返回 5 条，因此超过这些上限的值不会生效。

提示

• 如需在聊天补全中获取带引用的回答，请改用 /chat/completions，并设置 venice_parameters.enable_web_search + enable_web_citations。参见 venice-chat。
• 对于“搜索 + 阅读”工作流，请将 results[*].url 传入 /augment/scrape — 注意抓取速率限制为每分钟 20 次。
• 速率限制：每位用户每分钟 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	端点速率限制（抓取/搜索：每分钟 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 消息中，然后提问。
• 研究 Agent — 先调用 /augment/search，再对排名靠前的 URL 调用 /augment/scrape，最后将 Markdown 正文发送到 /chat/completions。
• 数据提取 — 使用 text-parser 处理 XLSX 会生成 Markdown 表格，你可以将其传给模型，并设置 response_format: { type: "json_schema", ... }。
• 代码审查 — 直接将源文件发送给 text-parser（无需转换为 PDF），再将文本提供给编码模型。