云端快速上手

几分钟获取 API key，完成首次搜索、首次问答与首次浏览器会话。

OmniScout Cloud 是托管 API：在自有索引上做语义搜索、带依据的问答，以及在 Fly Sprite 上运行远程浏览器 / 桌面会话。本地 CLI 不变 — Cloud 是叠加能力。

1. 获取 API key

在 api.omniscout.xyz 登录。
前往 Dashboard → API Keys → Create key。复制该值 — 以 os_live_ 开头，仅显示一次。
导出：

export OMNISCOUT_API_KEY=os_live_YOUR_KEY
export OMNISCOUT_BASE_URL=https://api.omniscout.xyz

key 的工作原理与第二个凭证（会话 secret）：认证。

2. 首次搜索

curl -X POST $OMNISCOUT_BASE_URL/v0/search \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtimes", "limit": 5}'

返回带 url、title、snippet、score、rank 的排序结果，以及供工单使用的 request_id。见端点。

3. 首次问答

curl -X POST $OMNISCOUT_BASE_URL/v0/answer \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the latest stable Rust version?"}'

返回带 sources 与 confidence 的 answer — 证据不足时返回 status: insufficient_information 且答案为 null。见端点。

4. 首次浏览器会话

会话在远程 Sprite 上运行与 CLI 相同的 daemon 原语。生命周期：创建 → 轮询 → 操作 → 销毁。

# Create (API key only) — save session_id AND session_secret
CREATE=$(curl -sS -X POST $OMNISCOUT_BASE_URL/v0/sessions \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"computer"}')

SESSION_ID=$(echo "$CREATE" | jq -r .session_id)
SESSION_SECRET=$(echo "$CREATE" | jq -r .session_secret)

# Poll until ready
curl -sS $OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" | jq .status

# Act (API key + session secret)
curl -sS -X POST $OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID/actions \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action":"navigate","args":{"url":"https://example.com"}}'

# Destroy (API key only)
curl -sS -X DELETE $OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY"

类型："browser" 是轻量纯浏览器 Sprite；"computer" 是统一型（浏览器 + 桌面共用一个会话 id）。会话在空闲后过期（默认 30 分钟，最长 2 小时） — 每次命令都会延长窗口。

更喜欢 SDK？同样的流程见 SDK 的 Python 与 TypeScript 版。

5. 查看用量

curl -sS $OMNISCOUT_BASE_URL/v0/usage \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" | jq .

计费仅按用量（基础设施成本 × 1.30） — 见用量与计费。

下一步

认证 — key、会话 secret、请求头
端点 — 每条路由的 schema
SDK — Python、TypeScript、curl
错误 — 错误信封与重试规则
限流 — 防护与支出上限