消费方数据获取

消费方通过 API key 调用检索接口。授权范围由 data product 和 entitlement 控制，canonical data 仍属于数据中心。消费方不直接访问数据库、对象存储、索引或向量库。

当前验证环境使用 http://20.169.21.11。所有请求必须携带：

Authorization: Bearer whale_consumer_xxx

本页目录

接入流程

生产接入建议先用小时间窗口和明确平台验证结果，再扩大查询范围。

检索模式

外部消费方优先使用统一入口 POST /v1/contents/search，通过 mode 选择检索模式。旧的 /v1/search/keyword、/v1/search/vector、/v1/search/hybrid 保留为兼容和专项调试接口。

mode 省略时，没有 query_vector 默认走 keyword；传了 query_vector 默认走 hybrid。

统一入口默认返回文档级结果，同一页同一个 document_id 只出现一次。body 是最佳命中分块摘要，不是完整正文；需要分块明细时传 include_chunks=true。

请求过滤

常用过滤维度：

示例请求：

{
  "mode": "hybrid",
  "query": "AI 视频生成",
  "dataset_ids": ["social_media_raw"],
  "source_platforms": ["youtube", "bilibili", "xiaohongshu"],
  "published_from": "2026-08-01T00:00:00Z",
  "published_to": "2026-09-01T00:00:00Z",
  "languages": ["zh", "en"],
  "top_k": 20
}

文档详情

统一入口检索结果是文档级。需要完整文档时，先从检索结果取 document_id，再调用：

• POST /v1/documents/batch-get：批量读取文档元数据、当前版本、可选完整正文、最新快照、片段和事实
• GET /v1/documents/{document_id}：文档元数据和当前版本
• GET /v1/documents/{document_id}/content：当前版本完整正文
• GET /v1/documents/{document_id}/content?version_id=ver_xxx：指定版本完整正文
• GET /v1/documents/{document_id}/versions：正文版本历史
• GET /v1/documents/{document_id}/snapshots：指标、作者状态和平台状态快照历史
• GET /v1/documents/{document_id}/parts：字幕、OCR、规格、章节等多内容片段
• GET /v1/documents/{document_id}/facts：价格、公司、地点、技能等结构化事实

正文、标题、URL、字幕、规格等内容变化会生成新版本；点赞、评论、播放、粉丝数、价格、库存等随时间变化的数据应从 snapshots 读取趋势。parts 面向可读片段，facts 面向可筛选和可聚合的结构化字段。

外部响应不会返回 Blob/R2 的 raw、text、manifest 或 part object key；完整正文和片段内容必须通过授权 API 获取。

列表页建议先用 batch-get 读取轻量信息和最新快照，详情页或导出场景再开启 include_content=true。

版本、片段和快照

统计维度

对外统计通常按以下维度理解：

权限控制

consumer 不拥有数据，只拥有访问权。授权可以限制：

• dataset
• source platform
• language
• region
• published time range
• allowed fields

每日配额按 UTC 自然日、消费方和检索操作统计，并在进入检索后端前原子占用。已被平台接受但下游失败的请求仍计入请求用量；因达到配额而返回 429 的请求不计入。

实时限制由 entitlement 的 requests_per_second、burst 和 max_concurrency 控制。触发时返回 429 rate_limit_exceeded 和 Retry-After: 1，请求不会进入下游，也不计入 usage。当前该限制在单 Gateway 内执行；多 Gateway 部署需要在统一 API Gateway 层同步全局策略。

返回字段

默认返回文档、分块、标题、正文摘要和评分。服务会按每条结果实际命中的 entitlement 再次脱敏；未授权 body 时不会返回正文和高亮。请求中的 fields 只能缩小返回范围，不能扩大授权。文档详情接口同样受 entitlement 控制。

错误处理

完整接入步骤见快速开始，密钥与错误语义见鉴权与密钥。