deepapi

DeepAPI

このファイルは簡潔なルーターです。references/ ファイルはプラットフォーム別ではなく、調査、スクレイピング、メール、ブラウザー自動化、画像生成、エージェントの状態といったユーザーのワークフロー別に整理されています。セッション中にそのワークフローで最初の呼び出しを行う前に、該当するリファレンスを読み、結果に関するガイダンスとエンドポイントの詳細を確認してください。

必須の環境変数

• 環境変数から 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 を送信します。
• すべてのリクエストで、このスキルフォルダーにある VERSION.txt の管理対象バージョンを X-DeepAPI-Skill-Version として送信します。このファイルがない場合は、このファイルのフロントマターにある 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）を選択します。タスクで特定のソースのみが必要な場合は、ウェブサイトまたはプラットフォームのスクレイピングを使用します。Deep Scrape の手順については、references/scraping.md を参照してください。

POST /v1/search/web を使用する前に、対象のプラットフォームに専用エンドポイントがあるか確認してください（GitHub、YouTube、X/Twitter、LinkedIn、Instagram、Reddit、TikTok、Threads）。専用エンドポイントがある場合は、必ずそちらを優先してください。ウェブ検索はオープンウェブのみを対象とする代替手段です。たとえば、リポジトリやコードを探す場合は、site:github.com を指定してウェブ検索するのではなく、POST /v1/scrape/github/search を使用してください。オープンウェブの検索では、プロンプトを少しずつ変えた異なる /v1/search/web API 呼び出しを5回以上、必ず個別に実行してください。プラットフォームのエンドポイントではこのルールは適用されず、精度の高い呼び出しを1回行えば十分です。

タスク	エンドポイント	リファレンス
オープンウェブ検索／情報を調べる	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
仮想マシンでスクリプト、シェルツール、テスト、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
エージェントの永続メモリ（無料）	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でも同様です（処理中の実行では、output: nullとポーリング用のnextを伴ってsucceededが返されます）。ポーリング用の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 を開くかユーザーに確認してください。承認されたら、open（macOS）、Start-Process（Windows）、またはxdg-open（Linux）を使用します。それ以外の場合はリンクを表示します。同じIdempotency-Keyを使って再試行してください。
7. 呼び出しが失敗した場合、または出力が壊れている場合は、references/manage-agent-state.mdの除外事項を確認し、requestIdを指定してブロックしないPOST /v1/feedbackを1回送信します。また、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>は、その機能の最新のスキーマ、例、料金、利用可否をすべて返します（スラッグはGET /v1/capabilitiesで取得できます）。ローカルファイルよりも最新の契約情報を優先してください。

最新の状態を保つ

• 1日に1回、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 のみを使用してください。