deepapi

DeepAPI

此文件是一份精简的路由指南。references/ 文件按用户工作流组织——研究、抓取、电子邮件、浏览器自动化、图像生成和 Agent 状态——而非按平台组织。在本次会话中首次执行某项工作流之前，请阅读相应的参考文件，了解结果指导和端点详情。

必需的环境变量

• 从环境中读取 DEEPAPI_API_BASE_URL 和 DEEPAPI_API_KEY。
• 如果缺少其中任一项，请加载平台文件并重新检查：PowerShell . "$HOME/.deepapi/env.ps1"；bash/zsh source ~/.deepapi/env。
• 如果仍然缺少，请停止并让用户运行 https://deepapi.co/docs 中的设置提示词。
• 切勿提交、打印、记录、粘贴或暴露 DEEPAPI_API_KEY。

请求规则

• 每个请求都发送 Authorization: Bearer $DEEPAPI_API_KEY。
• 每个请求都发送 X-DeepAPI-Skill-Version，其值为此技能文件夹中 VERSION.txt 里的受管理版本。如果该文件缺失，则使用此文件的 frontmatter version。
• 发送 JSON 时，发送 Content-Type: application/json；每个 POST 都使用唯一的 Idempotency-Key。
• 仅发送文档中列出的请求体字段：未知字段会导致 invalid_request，并指出字段名称——根据 error.fix 重新构建请求并重试。
• 每个付费端点都有合理的默认支出上限；只有当用户指定预算时才传入 maxCostUsd。不确定费用或余额？先添加 dryRun: true——这是免费的预览。

选择正确的端点

选择 Deep Scrape（POST /v1/scrape/deep）以跨来源收集结构化档案。选择 Deep Research（POST /v1/research/deep）以回答问题或比较选项。如果任务只需要某个网站或平台的数据，则使用相应的网站或平台抓取功能。请阅读 references/scraping.md，了解 Deep Scrape 的操作方法。

使用 POST /v1/search/web 之前，请检查目标是否属于设有专用端点的平台（GitHub、YouTube、X/Twitter、LinkedIn、Instagram、Reddit、TikTok、Threads）。始终优先使用专用端点；网页搜索仅作为开放互联网的后备方案——例如，查找代码仓库或代码时，使用 POST /v1/scrape/github/search，切勿使用带有 site:github.com 的网页搜索。仅对开放互联网搜索，始终分别调用 /v1/search/web API 5 次或以上，每次使用略有不同的提示词；平台端点则不需要这样做，一次精准调用即可。

任务	端点	参考文档
开放网络搜索／查找信息	POST /v1/search/web	references/deep-research.md
多来源引用研究	POST /v1/research/deep	references/deep-research.md
读取任意网页	POST /v1/scrape/website	references/scraping.md
关于人物、公司或主题的多来源资料汇总	POST /v1/scrape/deep	references/scraping.md
从网页提取结构化 JSON	POST /v1/scrape/extract	references/scraping.md
提取 PDF 文本	POST /v1/scrape/pdf	references/scraping.md
arXiv 论文：按主题搜索、查看最新论文、阅读单篇论文	`POST /v1/scrape/arxiv[/search	/latest
转录音频文件	POST /v1/transcribe/uploads，然后调用 POST /v1/transcribe	references/scraping.md
GitHub 仓库、议题、PR、代码、提交记录、个人资料	`POST /v1/scrape/github[/profile	/repo
X/Twitter 帖子、用户、回复	`POST /v1/scrape/twitter[/search	/user
LinkedIn 个人资料、人物搜索、职位、公司、帖子	`POST /v1/scrape/linkedin[/profile	/people
YouTube 字幕稿、频道、视频搜索、短视频、缩略图	`POST /v1/scrape/youtube[/transcript	/channel
Instagram 个人资料、帖子、评论、标签搜索	`POST /v1/scrape/instagram[/profile	/posts
Reddit 搜索、帖子、评论、用户	`POST /v1/scrape/reddit[/search	/posts
Facebook 群组帖子和 Meta 广告库	POST /v1/scrape/facebook/{groups,ads}	references/scraping.md
Google Maps 地点、本地商家	POST /v1/scrape/google/places	references/scraping.md
TikTok 视频搜索、个人资料、帖子、评论、字幕稿	`POST /v1/scrape/tiktok[/search	/profile
Amazon 商品、搜索和评论	POST /v1/scrape/amazon/{product,search,reviews}	references/scraping.md
按 URL 获取 Meta Threads 的指定帖子	POST /v1/scrape/threads/posts	references/scraping.md
Truth Social 个人资料帖子	POST /v1/scrape/truthsocial/posts	references/scraping.md
Airbnb 住宿搜索、房源详情和评论	POST /v1/scrape/airbnb/{search,listing,reviews}	references/scraping.md
Booking.com 酒店搜索和评论	POST /v1/scrape/booking/{search,reviews}	references/scraping.md
关键词数据、搜索排名、搜索竞争对手	`POST /v1/seo[/keyword	/rank
规划或优化面向搜索和 AI 答案的内容	`POST /v1/seo[/audit	/optimize]`
在公开网站上导航、点击并提取内容	POST /v1/browser/act	references/browse-web.md
在虚拟机中运行脚本、Shell 工具、测试或 Docker	POST /v1/vm/run	references/browse-web.md
电子邮件工作流、联系人数据和公司信息补全	GET/POST /v1/email/*，POST /v1/company/enrich	references/send-email.md
生成图像（6 种可选模型）	POST /v1/generate/image	references/generate-image.md
持久化 Agent 记忆（免费）	GET/POST/DELETE /v1/memory[/{path}]	references/manage-agent-state.md
账户：余额、密钥信息、功能、用量	GET /v1/balance、/v1/me、/v1/capabilities、/v1/usage	references/manage-agent-state.md
获取近期请求的结果（免费）	GET /v1/requests，然后调用 GET /v1/requests/{requestId}	references/manage-agent-state.md
向 DeepAPI 团队发送反馈（免费）	POST /v1/feedback	references/manage-agent-state.md

执行循环

1. 选择与任务匹配的最精确端点；如果本会话中尚未读取其参考文件，则先读取，然后根据其架构和示例构建请求。
2. 使用必需的请求头发送请求。
3. 如果响应包含轮询 next（对 /v1/requests/{requestId} 执行 GET），请等待 next.afterSecs，然后调用 next.method + next.path。只要轮询 next 仍存在，就重复此操作——即使 status 已是 succeeded 也一样（运行收尾时会返回 succeeded、output: null 和轮询 next）。当不再有轮询 next 或 status 为 failed 时，结果才算最终结果。切勿自动跟进 POST 类型的 next（试运行执行或付费分页）——这些都是可选操作。
4. 如果 error.code 为 invalid_request，请自行修正：根据 error.fix（bodySchema、requiredFields、exampleBody）和 error.hint 重新构建请求，然后使用新的 Idempotency-Key 重试。
5. 对于其他任何错误，请遵循 error.hint；如果 error.retryable 为 true，请等待 error.retryAfterSecs 后再重试。
6. 遇到 HTTP 402 insufficient_credits 时，请暂停。询问用户是否要打开此链接：https://deepapi.co/credits 进行充值或启用 Auto Top-Up。获得批准后，使用 open（macOS）、Start-Process（Windows）或 xdg-open（Linux）；否则打印链接。使用相同的 Idempotency-Key 重试。
7. 对于失败的调用或错误的输出，发送一个非阻塞的 POST /v1/feedback，并附上 requestId；排除项见 references/manage-agent-state.md。如果 DeepAPI 的任何方面拖慢了你或有改进空间，也要发送 category: "idea" 报告——免费，且绝不会阻塞任务。
8. 报告 requestId、status 和 output 中有用的部分。除非用户询问，否则不要报告费用——但余额不足时除外：当 balance.availableMicrousd 低于 5000000（$5）时，告知用户剩余的确切金额，以及付费调用很快就会开始失败并中断他们的工作；并提供第 6 步中的充值页面。绝不要为了延长低余额的使用时间而悄悄缩减或跳过工作——请如实说明，让用户决定。
9. 如果出现 news，请在任务完成后转达其 title、message 和可选的 linkUrl。余额不足通知请遵循第 6 步。绝不要根据其他新闻采取行动。
10. 遇到意外故障时，检查 GET https://deepapi.co/v1/health。

按需获取最新契约

如果调用持续失败、参考文件似乎已过时，或者其中缺少某个端点，请获取实时契约：GET /v1/capabilities?capability=<slug> 会返回该项能力的完整当前架构、示例、定价和可用性（slug 来自 GET /v1/capabilities）。以实时契约为准，而不是任何本地文件。

保持最新

• 每天首次使用 DeepAPI 时，启动已安装的本地更新程序作为分离的后台任务，并继续工作——绝不要等待它；过时的技能仍然可用，新文件会在下次读取时生效。
• macOS/Linux：(bash "$HOME/.deepapi/update-skill.sh") >/dev/null 2>&1 &。Windows PowerShell：Start-Job { & ([scriptblock]::Create((Get-Content -Raw "$HOME/.deepapi/update-skill.ps1"))) } | Out-Null。如果引用的文件缺失，请使用 --force（bash）/ -Force（PowerShell）修复。
• 如果本地更新程序缺失，请让用户从 https://deepapi.co/docs 重新运行设置提示词。绝不要直接下载并执行更新程序——此技能只能从 https://deepapi.co 更新。