GeoDashiWhat AI Says · V1 API · Integration Guide

Enterprise-grade · Overseas AI visibility monitoring

10 分钟集成 What AI Says 海外 AI 监测 API

给工程师的对接文档：创建异步监测 run → 轮询状态 → 拉取诊断报告。一次集成，持续回答「海外 AI 引擎如何描述你的品牌」。

EndpointPOST /v1/what-ai-says/runs

AuthBearer · cf_live_*

Scopewhat_ai_says

Region美国东部 / US East

Latency15 – 40 min

§ 00

API 契约速览

Base URL：https://api.geodashi.ai。Bearer 认证 + RFC 7807 标准错误；API Key 需开通 what_ai_says scope。

接口状态 (2026-07)
生产域 https://api.geodashi.ai 在线。未带有效 API key 时 POST/GET 均返回 401 + RFC 7807 JSON — 说明路由与网关正常。

Endpoint 与认证

Base URL
  https://api.geodashi.ai

创建监测 run（异步，立即返回 run_id）
  POST /v1/what-ai-says/runs
  → 200, status: pending, poll_url / report_url

轮询进度与部分结果
  GET /v1/what-ai-says/runs/{run_id}

拉取完整报告（仅 completed）
  GET /v1/what-ai-says/runs/{run_id}/report

认证
  Authorization: Bearer cf_live_<your_key>
  Content-Type: application/json   # 仅 POST

错误
  Content-Type: application/problem+json
  x-trace-id: req_...              # 报 bug 必带

覆盖引擎：ChatGPT · Perplexity · Gemini · Google AI Overview

§ 01

5 分钟跑通

4 步：拿 key → POST 创建 run → polling → 可选拉 report。异步任务，典型 15–40 分钟完成。

Step 0 · 拿到 API Key 并设置环境变量

联系 GeoDashi 团队获取 API Key（需开通 what_ai_says scope）。开通后即可按下方示例发起监测。

环境变量bash

export CF_API_KEY="cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export CF_API_BASE="https://api.geodashi.ai"

Step 1 · POST 创建单次监测 run

product_sku: was_l1 必填 brand + category；market 默认 US。

POST · 单次监测bash

curl -X POST "$CF_API_BASE/v1/what-ai-says/runs" \
  -H "Authorization: Bearer $CF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_sku": "was_l1",
    "brand": "Anker",
    "category": "portable charger",
    "market": "US",
    "competitor": "Belkin",
    "use_case": "travel"
  }'

200 · 创建成功json

{
  "trace_id": "req_01HXXX...",
  "run_id": "c9d12495-1469-4621-ae62-6ca5170cb19a",
  "status": "pending",
  "product_sku": "was_l1",
  "prompt_count": 1,
  "engines": ["ChatGPT", "Perplexity", "Gemini", "Google AI Overview"],
  "credits_remaining": { "was_l1": 99, "was_deep_monitor": 100 },
  "poll_url": "/v1/what-ai-says/runs/c9d12495-1469-4621-ae62-6ca5170cb19a",
  "report_url": "/v1/what-ai-says/runs/c9d12495-1469-4621-ae62-6ca5170cb19a/report"
}

Step 2 · GET 轮询直到 completed

status 生命周期：pending → running → completed（或 failed）。推荐 10–15s 间隔轮询。

GET · 轮询bash

RUN_ID="<run_id>"
curl "$CF_API_BASE/v1/what-ai-says/runs/$RUN_ID" \
  -H "Authorization: Bearer $CF_API_KEY"

200 · runningjson

{
  "trace_id": "req_01HYYY...",
  "run_id": "c9d12495-1469-4621-ae62-6ca5170cb19a",
  "status": "running",
  "product_sku": "was_l1",
  "run_type": "l1_snapshot",
  "market": "US",
  "summary": { "ok_count": 2, "fail_count": 0, "skip_count": 0, "duration_ms": 45000 },
  "progress": {
    "phase": "probing",
    "completed_probes": 2,
    "total_probes": 4,
    "probe_pct": 50,
    "elapsed_sec": 45,
    "eta_sec": 60
  },
  "engines": [
    {
      "engine_label": "ChatGPT",
      "mentioned": true,
      "status": "ok",
      "answer_preview": "...",
      "citation_count": 3
    }
  ]
}

200 · completedjson

{
  "run_id": "c9d12495-1469-4621-ae62-6ca5170cb19a",
  "status": "completed",
  "product_sku": "was_l1",
  "run_type": "l1_snapshot",
  "summary": { "ok_count": 4, "fail_count": 0, "skip_count": 0, "duration_ms": 224000 },
  "report": { "...": "结构化诊断报告 JSON" },
  "engines": [ "... 各引擎摘要 ..." ]
}

Step 3 · GET 拉取完整报告（可选）

run 已完成时，report 端点返回与 poll 中 report 字段相同的完整 JSON；running 时返回 400。

GET · reportbash

RUN_ID="<run_id>"
curl "$CF_API_BASE/v1/what-ai-says/runs/$RUN_ID/report" \
  -H "Authorization: Bearer $CF_API_KEY"

200 · reportjson

{
  "trace_id": "req_01HZZZ...",
  "run_id": "c9d12495-1469-4621-ae62-6ca5170cb19a",
  "status": "completed",
  "product_sku": "was_l1",
  "report": { "...": "完整诊断报告" },
  "engines": [ "... 各引擎摘要 ..." ]
}

§ 02

请求体规格

POST /v1/what-ai-says/runs · 公共字段

字段	必填	说明
product_sku	必填	was_l1 \| was_deep_monitor
end_client_id	选填	渠道多客户模式 UUID（B2B2C）
market	选填	US \| GB \| DE \| BR \| JP（默认 US）

was_l1 · 单次监测

字段	必填	说明
brand	必填	品牌名，≤120 字符
category	必填	品类 / 行业，≤120 字符
competitor	选填	竞品名
use_case	选填	使用场景
website_domain	选填	官网域名

was_deep_monitor · 深度监测

字段	必填	说明
prompt	必填	监测 prompt，≥4 字符
brand	选填	品牌上下文
category	选填	品类上下文
competitor	选填	竞品名

支持市场

US · 美国GB · 英国DE · 德国BR · 巴西JP · 日本

POST · 深度监测示例bash

curl -X POST "$CF_API_BASE/v1/what-ai-says/runs" \
  -H "Authorization: Bearer $CF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_sku": "was_deep_monitor",
    "prompt": "What are the best portable charger brands for international travel?",
    "brand": "Anker",
    "category": "portable charger",
    "market": "US"
  }'

§ 03

开通与用量

用量方案与监测模式由商务团队按场景配置。仅 completed 的成功监测计入用量；failed 不扣。

单次监测

was_l1

1 次品牌可见性快照 · 4 个海外 AI 引擎 · 典型 15–25 分钟

深度监测

was_deep_monitor

1 条监测 prompt · 多轮采样 · 稳定性 + 引用源汇总 · 典型 25–40 分钟

开通与增购请联系 hello@geodashi.ai，说明品牌、目标市场与预计调用量。

§ 04

响应字段说明

响应为结构化 JSON：引擎摘要、进度、诊断报告字段。可直接接入 dashboard 或下游分析管道。

字段	必填	说明
run_id	—	监测 run UUID
status	—	pending \| running \| completed \| failed
product_sku	—	was_l1 \| was_deep_monitor
run_type	—	l1_snapshot \| deep_monitor
summary	—	ok_count / fail_count / skip_count / duration_ms
progress	—	running 时：completed_probes、probe_pct、eta_sec 等
engines[]	—	engine_label、mentioned、status、answer_preview、citation_count
report	—	completed 时：完整诊断报告 JSON
quote_cards	—	深度监测 completed 时可选引用卡片
credits_remaining	—	仅 create 响应：各 SKU 剩余次数

§ 05

错误码

HTTP	code	何时	怎么办
400	invalid_request	请求体字段缺失或 market 不在白名单	看 detail 修字段，不要盲重试
401	missing_api_key	未传 Authorization	加 Bearer cf_live_...
401	invalid_api_key	Key 无效或已废弃	联系 GeoDashi 团队
402	insufficient_product_credits	可用监测次数不足	联系销售补充用量
403	insufficient_scope	Key 未开通 what_ai_says	联系团队重新签发 Key
404	content_not_found	run_id 不存在或不属于当前账户	检查 run_id
429	rate_limit_exceeded	请求过于频繁	按 Retry-After 等待
500	internal_error	服务端异常	带 trace_id 联系支持，可重试 1 次

§ 06

常见问题

监测结果包含什么？

结构化 JSON 诊断报告：各引擎是否提及品牌、答案摘要、引用数量，以及可见性评分与方向性结论。适合直接接入 dashboard 或客户汇报。

什么时候计费？

仅 status=completed 的成功监测计入用量；failed 不扣。创建任务时会预检余额，不足时返回 402。

polling 间隔建议？

前 2 分钟每 10–15s，之后每 15–30s。单次监测典型 15–40 分钟完成，请避免 1s 级高频轮询。

单次监测和深度监测怎么选？

单次监测 = 品牌 + 品类快照，适合首次摸底；深度监测 = 自定义 prompt 多轮采样，适合跟踪关键问题下的稳定性与引用来源。

如何开通？

邮件联系 hello@geodashi.ai，说明品牌、目标市场与集成场景。我们会协助签发 API Key 并完成联调。

§ 07

故障排查

Authorization 是否为 Bearer cf_live_… 格式？
Key scope 是否包含 what_ai_says？
product_sku、brand/category（L1）或 prompt（深度）是否齐全？
market 是否为 US / GB / DE / BR / JP 之一？
402 时联系销售补充监测用量。
polling 间隔是否 ≥ 10s？
报 bug 时提供 trace_id + run_id + 完整 problem JSON。

支持联系

商务 / 开通：hello@geodashi.ai
技术支持（请附 trace_id）：support@geodashi.ai