KOL 对话 API · 快速接入

与 crypto KOL 人设对话的只读 API。两个端点：列出可用 KOL、按 handle 提问。

本文档覆盖需 API Key 的单轮对话端点（/v1/ask/*）。免鉴权的流式三轮讨论端点（/v1/ask/* 圆桌 + 流式，didotxyz 专用）见 frontend-api-spec。统一鉴权/限流规则见 gateway。

Base URL

https://api.eurybia.xyz

鉴权

所有请求都带请求头：

X-API-Key: <your_api_key>

API Key 由 Eurybia 团队提供（2026-09-20 起统一网关鉴权）。缺失/无效返回 401，无路径权限返回 403。

端点

1) 列出可用 KOL

curl -G 'https://api.eurybia.xyz/v1/ask/kols' \
  -H 'X-API-Key: <your_api_key>'

响应

{
  "data": [
    {"handle": "cz_binance", "display_name": "CZ 🔶 BNB", "avatar": "https://...", "profile": "币安创始人，擅长交易所..."},
    {"handle": "saylor", "display_name": "Michael Saylor", "avatar": "https://...", "profile": "MicroStrategy 创始人..."},
    {"handle": "SexyMichill", "display_name": "Michill💕", "avatar": "https://...", "profile": "Crypto KOL，预测市场..."}
  ],
  "meta": {"request_id": "..."}
}

/ask/kols 返回每个 KOL 的 4 个字段：handle（Twitter handle）、display_name（昵称）、avatar（头像，默认 pbs 直链；加 ?embed_avatar=true 返回 base64 data URI）、profile（一句话简介）。当前共 126 个 KOL（含中文 KOL）。

2) 与 KOL 对话

GET /ask/{handle}?q=<问题>

handle：路径参数，KOL 的 Twitter handle（大小写不敏感，@ 可选）
q：query 参数，要问的问题（1~2000 字符，必填，需 URL 编码）

curl -G 'https://api.eurybia.xyz/v1/ask/cz_binance' \
  -H 'X-API-Key: <your_api_key>' \
  --data-urlencode 'q=BTC 现在还能上车吗？'

响应（问题在允许范围）

{
  "data": {
    "handle": "cz_binance",
    "display_name": "CZ 🔶 BNB",
    "in_scope": true,
    "answer": "BTC 长期来看是通缩资产，很多人把它当数字黄金…… Keep building, 别把自己弄丢了。"
  },
  "meta": {"request_id": "..."}
}

响应（问题超出范围）

{
  "data": {
    "handle": "cz_binance",
    "display_name": "CZ 🔶 BNB",
    "in_scope": false,
    "answer": "问题超出回答范围"
  },
  "meta": {"request_id": "..."}
}

响应字段

字段	说明
`handle`	KOL 的 Twitter handle
`display_name`	KOL 昵称
`in_scope`	问题是否在允许范围内
`answer`	KOL 的回答；`in_scope=false` 时固定为「问题超出回答范围」

常见错误码

状态码	code	说明
401	`missing or invalid api key`	缺 key / key 无效
403	`api key is not permitted to access this path`	key 无 `/v1/ask` 前缀权限
404	`NOT_FOUND`	未知 KOL handle
400	`INVALID_FILTER`	缺 `q` 或参数非法
429	`rate limit exceeded` / `daily quota exceeded`	触发限流（响应头含 `Retry-After`）或日配额超限
500	`INTERNAL_ERROR`	服务端错误（可重试）

注意事项

Guardrail：只允许 Web3 / 加密货币 / 区块链 / DeFi / NFT / 交易所 / 预测市场 / 股票 / 宏观财经 / AI×Crypto 相关问题，其他问题直接返回「问题超出回答范围」。
语言跟随：回答语言与提问语言一致——中文提问用中文回答，英文提问用英文回答。
超时：单次调用底层是一次 LLM 生成，通常数秒返回，建议客户端超时 ≥ 60s。
限流：每个 key 有速率配额，超限返回 429，按 Retry-After 退避。
不缓存：每次调用独立生成，不保证同一问题返回完全一致。
免责：KOL 回答为 AI 人设生成，不构成任何投资建议。

Base URL​

鉴权​

端点​

1) 列出可用 KOL​

2) 与 KOL 对话​

响应字段​

常见错误码​

注意事项​