读取内容与历史

检索接口返回文档级摘要；本文档描述如何读取一篇文档的完整数据。所有接口都需要 Authorization: Bearer whale_consumer_xxx。

还没有文档 ID？关键词或语义检索见关键词与语义检索；精确筛选见用户、话题、标签与分类。

接口	用途
`POST /v1/documents/batch-get`	批量读取（列表页首选）
`GET /v1/documents/{document_id}`	单篇元数据 + 当前版本
`GET /v1/documents/{document_id}/content`	当前或指定版本完整正文
`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`	结构化事实（价格、公司等）

批量读取内容

POST /v1/documents/batch-get，每次最多 50 个 ID，按文档返回，单个失败不影响其他。

请求：

JSON

{
  "document_ids": ["doc_01J...", "doc_01K..."],
  "include_content": true,
  "include_latest_snapshot": true,
  "include_parts": false,
  "include_facts": false,
  "parts_limit": 20,
  "facts_limit": 50
}

字段	默认	说明
`document_ids`	必填	1–50 个文档 ID
`include_content`	false	返回当前版本完整正文
`include_latest_snapshot`	false	返回最新指标快照
`include_parts` / `include_facts`	false	返回片段 / 事实
`parts_limit` / `facts_limit`	20 / 50	每个文档返回的片段、事实上限

响应（单个条目）：

JSON

{
  "document_id": "doc_01J...",
  "document": {
    "id": "doc_01J...",
    "dataset_id": "social_media_raw",
    "source_platform": "weibo",
    "external_content_id": "5112345678901234",
    "canonical_url": "https://weibo.com/...",
    "content_type": "post",
    "language": "zh",
    "title": "...",
    "current_version_id": "ver_01J...",
    "status": "active",
    "quality_status": "normal",
    "published_at": "2026-09-01T08:00:00Z",
    "first_seen_at": "2026-09-01T08:05:00Z",
    "last_seen_at": "2026-09-02T10:00:00Z",
    "metadata": {}
  },
  "current_version": {
    "version_id": "ver_01J...",
    "content_hash": "sha256:...",
    "body_format": "plain",
    "size_bytes": 1523,
    "char_count": 712,
    "created_at": "2026-09-01T08:05:00Z"
  },
  "content": {
    "body": "完整正文...",
    "body_format": "plain",
    "char_count": 712
  },
  "latest_snapshot": {
    "snapshot_at": "2026-09-02T10:00:00Z",
    "metrics": {"like_count": 1204, "comment_count": 86, "repost_count": 45}
  }
}

单篇读取失败时该条目含 error：{"code": "not_found" | "forbidden", "message": "..."}。

内容标识与元数据

document 对象在各接口中结构一致：

字段	说明
`id`	Whale 文档 ID（`doc_` 前缀），检索与详情共用；不是来源平台的内容 ID
`dataset_id`	所属数据集，也是数据授权范围的一部分
`source_platform`	来源平台枚举
`external_content_id`	平台侧内容 ID（如微博 mid、YouTube video id、Reddit fullname）
`canonical_url`	规范化 URL；同一内容跨来源合并时稳定
`content_type`	统一内容类型，见平台覆盖
`language` / `region` / `country_code`	内容语言与地区
`title`	当前标题
`current_version_id`	当前正文版本
`status`	`active` / `deleted` / `unavailable` 等平台状态
`quality_status`	平台质量标记
`published_at`	平台发布时间
`first_seen_at` / `last_seen_at`	平台侧首次/最近一次被采集观察到的时间

外部响应不返回对象存储地址（raw/text/manifest/object_key）；完整正文和片段只能通过授权 API 读取。

读取完整正文

GET /v1/documents/{document_id}/content?version_id=ver_xxx

参数	说明
`version_id`	可选；省略返回当前版本。传历史版本 ID 读取历史正文

JSON

{
  "content": {
    "document_id": "doc_01J...",
    "version_id": "ver_01J...",
    "body": "完整正文文本",
    "body_format": "plain | markdown",
    "content_hash": "sha256:...",
    "size_bytes": 1523,
    "char_count": 712
  }
}

正文超长时 body 仍是完整文本；如需流式或分段读取请联系平台开通。

查看正文版本历史

GET /v1/documents/{document_id}/versions?limit=100，按创建时间倒序。标题、正文、URL、字幕等内容变化会产生新版本；点赞数等数值变化不产生版本，走 snapshots。

JSON

{
  "versions": [
    {
      "version_id": "ver_01J...",
      "content_hash": "sha256:...",
      "body_format": "markdown",
      "size_bytes": 1523,
      "char_count": 712,
      "created_at": "2026-09-01T08:05:00Z"
    }
  ]
}

对比两个版本的正文：分别用 content?version_id= 读取后自行 diff。

versions 和 snapshots 当前只支持 limit（最大 500），没有 cursor 或历史时间窗口分页；超过上限不能靠重复请求遍历完整历史。parts、facts 也为限量列表，不是分页导出。需要完整长周期历史时先与平台确认交付方案。

查看指标与作者快照

GET /v1/documents/{document_id}/snapshots?limit=500，按时间倒序。

JSON

{
  "snapshots": [
    {
      "id": "ds_01J...",
      "snapshot_at": "2026-09-02T10:00:00Z",
      "received_at": "2026-09-02T10:00:20Z",
      "metrics": {
        "like_count": 1204,
        "comment_count": 86,
        "repost_count": 45,
        "view_count": 152000
      },
      "author_snapshot": {"follower_count": 89000},
      "platform_payload": {}
    }
  ]
}

metrics：统一指标字段（like_count、comment_count、share_count、view_count、play_count、collect_count 等）+ 平台扩展字段。
author_snapshot：作者粉丝数等状态，仅在采集器上报时存在。
趋势分析建议拉取多次快照自行连线；不要假设固定采集间隔。

读取字幕、OCR 与片段

GET /v1/documents/{document_id}/parts?version_id=ver_xxx&limit=500

JSON

{
  "parts": [
    {
      "id": "part_01J...",
      "part_type": "transcript | transcript_segment | ocr | spec | chapter | comment",
      "format": "plain | srt | vtt | json",
      "language": "en",
      "text": "片段文本",
      "start_ms": 12000,
      "end_ms": 15800,
      "sequence": 4
    }
  ]
}

part_type=transcript：完整字幕/转录；transcript_segment：按时间切分，带 start_ms/end_ms。
没有文本只有对象的片段（如图片 OCR 源图）会省略 text，内容已脱敏为平台内读取。

读取结构化字段与分类

GET /v1/documents/{document_id}/facts?version_id=ver_xxx&limit=500

JSON

{
  "facts": [
    {
      "id": "fact_01J...",
      "fact_type": "price | company | location | skill | salary_range | custom",
      "name": "price",
      "value_number": 199.0,
      "unit": "CNY",
      "confidence": 0.95,
      "source": "extractor | collector | platform",
      "observed_at": "2026-09-01T08:05:00Z"
    }
  ]
}

value_* 四选一（string/number/bool/time）。字段随数据集而异，缺失不表示数值为零。当前没有任意 facts 条件的对外搜索或聚合接口；读取后可以自行聚合。

外部分类使用 fact_type=category，metadata.label_code 是分类 code。分类字典与按分类取数见用户、话题与分类取数。话题、原生标签和作者资料分别位于授权可见的 document.metadata.topics、tags、author，不应把三者当成同一个字段。

错误

HTTP	code	含义
401	`unauthorized`	key 缺失/无效
403	`forbidden`	该文档不在订阅范围或字段未授权
404	`not_found`	ID 不存在
400	`invalid_request`	参数错误（如 batch-get 超过 50 个）
429	`quota_exceeded`	日配额耗尽

完成标准： 能够分别读取文档元数据、完整正文和所需事实，不把搜索摘要当作完整内容。

无需此工具或能力？跳过可选步骤：限流、重试与排错