Seo Aio Diagnosis Billing

Get Balance

認証ユーザーのクレジット残高を返す。

Quote

操作に必要なクレジット数を事前見積り（課金なし）。

Run Report

★課金対象: ワンショットWFでレポート生成。残高をNクレジット消費（成功時のみ・失敗時返却）。 事前に run-spec が data/runs/<run_id>/ に必要（create_spec で作成）。 with_llmo=+52cr（LLM3社実査）、narrative="evaluate"=+13cr（AI評価）、 with_profiles=+39cr（競合ポジショニング/UVP）。フル構成=260cr。 fresh=True: 未課金runではキャッシュを無視して全データを最新で再取得する。 課金済みrunではエラーを返し、create_spec による新しいrun作成へ誘導する。 課金済みrunで競合/企業体が変更されている場合もエラーを返し、新run作成へ誘導する。 wait=false（HTTP では既定）: {job_id, status:"queued"} を即返し → get_job(job_id) でポーリング。 wait=true（stdio では既定）: 完了まで待って従来形のレスポンスを返す（最長30分）。 email_notification=T

Create Spec

診断設計（run-spec）を生成する。レポート発注（run_report）の前段。課金なし。 - name/target_domain/brief から LLM が seeds・topic_tokens・content_types・質問を設計 （LLM 失敗時は決定的テンプレートにフォールバック）。gather=True で実 SERP 証拠も収集。 - 生成された run_id は呼び出しユーザーの所有としてピン留めされ、他ユーザーは実行不可。 - 利用条件: 1ユーザー BILLING_SPEC_LIMIT 回/日まで（下調べは無料。課金=カード登録は run_report の直前）。 - 戻り値の run_id を run_report に渡すとレポート生成（こちらが課金対象）。

Run Research

★課金対象: データのみ購入（research.json）。レポートは生成しない（Tier 1）。 wait=false（HTTP では既定）: {job_id, status:"queued"} 即返し → get_job でポーリング。 4クレジット（with_llmo=True で +3: Gemini/ChatGPT/Claude 実査込み）。 検索数/CPC/SERP/AIO/footprint/keyword gap/サイト構造を出典・取得時刻つきの 単一 research.json に組み立て、署名付きダウンロードURLで返す。 課金済みの再呼び出しは再課金なし・キャッシュ返却。後から run_report を呼ぶと 取得済みデータを再利用してレポートだけ生成する（データ二重取得なし）。 fresh=True は未課金runの全再取得に使い、課金済みrunでは新しいrun作成を促すエラーを返す。 課金済みrunで競合/企業体が変更されている場合もエラーを返し、新run作成へ誘導する。

Get Run Data

購入済み run の個別データ取得（所有者のみ・課金なし）。 which: keywords | serp | footprint | gap | site | llm | research | status | shots | quality。 64KB 以下はインライン JSON、超える場合は署名付きダウンロードURL。 which="shots" は競合スクショ一覧（各画像の署名付きDLリンク付き・capture_screenshots で取得）。

Check Status

★課金対象: 定期モニタリング（2クレジット）。SERP順位/AIO引用/SERP SoV を再実査し前回比を返す。 同一日（JST）の再実行は再課金なし・前回結果を返す。履歴は history/serp-<date>.json に蓄積。 事前に run_research か run_report でデータが取得済みであること。

Get History

定点観測の履歴を時系列で返す（無料）。 check_status を実行した日付ごとに1点蓄積される（自社 SERP SoV と、順位変動/AIO引用変化の サマリ）。コンテナFSは揮発するため履歴は durable に DB 保持しており、再起動後も残る。 返り値の points は日付昇順: [{date, sov_pct, summary{rank_improved/declined, aio_citation_gained/lost, serp_sov_before_pct, serp_sov_after_pct}}]。 グラフ化や推移レポートはこの時系列をそのまま使える。

Capture Screenshots

★課金対象: 競合サイトのスクリーンショット取得（13クレジット・最小単位）。 各社（自社含む）の「トップページ」と「料金/サービス系の主要1ページ」を撮影し、 署名付きダウンロードURLで返す。撮影対象は競合プロファイル（with_profiles）と同じページ選定。 DataForSEO/LLM は使わない（API 実費ゼロ）。同一 run の再呼び出しは再課金なし・既存画像を返す。 wait=false（HTTP では既定）: {job_id, status:"queued"} を即返し → get_job(job_id) でポーリング。 撮影済み画像は get_run_data(run_id, which="shots") でも一覧取得できる。

Get Job

非同期ジョブの状態取得（所有者のみ・課金なし）。 status: queued → running → succeeded / failed。 succeeded: result（投入したツールの完了レスポンス相当）+ downloads（その場で署名・常に有効）。 failed: error を返す（課金ジョブは自動返金済み）。

Get Report Links

生成済みレポートの署名付きダウンロードURLを再発行する（所有者のみ・課金なし）。

Update Spec

確認済みの intents / competitors を run-spec に反映する（課金なし・所有者のみ）。 create_spec の spec_summary を人が確認・修正してから run_report する HITL 用。 intents は [{query, category?, why?, priority?}]（query 必須）、competitors は [{name, host}]。 questions（LLM実査）と aliases（SoV帰属）はサーバが intents/competitors から自動で整合させる。

Signup

セルフサーブ登録（認証不要）: アカウント作成 + APIキー発行 + 無料トライアル。 キー無しで接続したまま呼べる唯一の登録口。応答の connect コマンドをそのまま実行すれば 認証つき接続が完成する。★APIキーはこの応答でのみ返り、再表示は不可（漏えい時は rotate_api_key で即無効化）。1 IP あたり BILLING_SIGNUP_LIMIT 回/日まで。 無料トライアル（フルレポート1本＝260cr）はカード登録（¥0・即時課金なし）が必要。 応答の trial_url を開いてカードを登録すると自動付与される（気に入らなければ無課金で離脱可）。

Buy Credits

クレジット購入: Stripe Checkout の決済URLを発行する（pack="260": 260cr/¥1,500、"1300": 1300cr/¥6,500）。 決済完了で自動付与（webhook・冪等）。URLの有効期限は約24時間。 付与の確認は get_balance。（旧 pack="10"/"50" も当面利用可）

Subscribe

月額サブスク開始: Stripe Checkout(mode=subscription) の決済URLを発行する。 plan="standard"（¥4,980/月 → 毎月1,300クレジット, レポート約5本）/ plan="pro"（¥14,800/月 → 毎月5,200クレジット, 約20本）。 毎月の課金成功で自動付与（webhook・冪等）。未使用クレジットは翌月へ繰り越し。 既に有効なサブスクがある場合は拒否（解約は cancel_subscription）。付与確認は get_balance。

Cancel Subscription

現在の月額サブスクを期末解約する（cancel_at_period_end）。 期末までは利用でき、付与済みクレジット残高は没収されません（繰り越し）。即時の課金は発生しません。

Start Trial

無料トライアル: TRIAL_CREDITS（既定260）を1アカウント1回だけ付与（冪等）。 260クレジット = フルレポート1枚を体験できる量（base 130 + profiles 39 + llm 52 + shots 13 + report 26）。必要なデータだけ少しずつ取得することもできる。granted=false は付与済み。 success_url/cancel_url はカード登録後の着地先（既定 env。Web /app が独自の着地先を渡す用）。

Rotate Api Key

現行APIキー（Authorization: Bearer の sk_user_ キー）をローテーションする（課金なし）。 渡したキーのみ即時無効化し、新しいキーを発行して返す。 ★新キーはこのレスポンスでのみ返り、再表示は不可。受け取ったら即保存すること。 同一ユーザーの他の active キーには影響しない。Supabase JWT 認証ではキーを持たないため使用不可。