## 查询取数接入路线

以下是推荐阅读顺序，不代表已完成的进度；可选步骤可以跳过。

1. [获取与使用 API Key](/docs/authentication)
2. [完成第一次查询](/docs/quickstart)
3. [关键词与语义检索](/docs/search)
4. [用户、话题、标签与分类](/docs/browse)（可选）
5. [读取内容与历史](/docs/documents) ← 当前页
6. [下载图片与附件](/docs/attachments)（可选）
7. [限流、重试与排错](/docs/production)

**开始前**：已通过查询获得一个授权范围内的 document_id。

# 读取内容与历史

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

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

| 接口 | 用途 |
| --- | --- |
| `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` | 统一内容类型，见[平台覆盖](/docs/platforms) |
| `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。分类字典与按分类取数见[用户、话题与分类取数](/docs/browse)。话题、原生标签和作者资料分别位于授权可见的 `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` | 日配额耗尽 |

## 检查与继续

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

上一步：[用户、话题、标签与分类](/docs/browse)

**推荐下一步**：[下载图片与附件](/docs/attachments)（可选，无需此能力可跳过）

跳过可选步骤：[限流、重试与排错](/docs/production)