## 查询取数接入路线

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

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

**开始前**：已能读取内容；需要下载已上传图片或文件时，确认应用有 assets 字段权限，无需附件可跳过。

# 下载图片与附件

部分内容有采集器直接上传的图片、音视频或文件。这些附件与内容关联，但不表示
所有原文的外部资源都已归档。正文 `assets` 中的原始 URL 和已上传附件是两类资源。

## 调用前准备

先按[获取与使用 API Key](/docs/authentication)配置 `WHALE_BASE_URL` 和
`WHALE_API_KEY`。从检索或筛选结果取得 `DOCUMENT_ID`，并确认应用拥有
对应数据范围及 `assets` 字段权限。不要向存储下载 URL 转发 Consumer Key。

## 查询附件


```bash
curl -sS --fail-with-body "$WHALE_BASE_URL/v1/documents/$DOCUMENT_ID/attachments?limit=50" \
  -H "Authorization: Bearer $WHALE_API_KEY" | jq .
```


`limit` 为 1–100，默认 50。响应只包含上传完成的文件：


```json
{
  "attachments": [
    {
      "asset_id": "asset_01K...",
      "dataset_id": "social_media_raw",
      "source_platform": "xiaohongshu",
      "external_content_id": "65f0c2...",
      "filename": "cover.jpg",
      "media_type": "image",
      "mime_type": "image/jpeg",
      "size_bytes": 248133,
      "status": "ready",
      "created_at": "2026-10-14T08:00:00Z"
    }
  ],
  "next_cursor": ""
}
```


| 字段 | 说明 |
| --- | --- |
| `asset_id` | 附件 ID，下载时使用 |
| `filename` / `mime_type` / `size_bytes` | 文件名、MIME 类型和字节数 |
| `media_type` | `image`、`video`、`audio`、`document` 或 `other` |
| `status` | 列表中为 `ready` |
| `dataset_id` / `source_platform` / `external_content_id` | 附件所属内容的来源身份 |

`next_cursor` 非空时，把它作为 `after` 传入获取下一页；为空表示没有更多。

## 获取文件


```bash
ASSET_ID="asset_01K..."
download_url="$(curl -sS --fail-with-body \
  "$WHALE_BASE_URL/v1/documents/$DOCUMENT_ID/attachments/$ASSET_ID/download" \
  -H "Authorization: Bearer $WHALE_API_KEY" | jq -er '.url')"
curl -sS --fail-with-body -o cover.jpg "$download_url"
```


接口返回 `{"url": "...", "expires_in": 300}`。`url` 300 秒内有效，直接下载，不要携带 Consumer Key。
不要永久保存 URL 或写入公开日志；过期后重新调用接口获取。

## 权限与错误

你的应用需要对应内容的数据范围和 `assets` 字段权限。附件与内容关联，不提供历史版本的附件。
列表为空可能表示没有上传文件，或上传尚未完成。

| HTTP | code | 含义与处理 |
| --- | --- | --- |
| 401 | `unauthorized` | API Key 无效 |
| 403 | `forbidden` | 没有该内容的数据范围或 `assets` 字段权限 |
| 404 | `not_found` | 内容不存在或尚未入库 |
| 404 | `attachment_not_found` | 附件不存在或不属于该内容 |
| 409 | `attachment_incomplete` | 附件尚未上传完成，稍后重试 |
| 429 | `rate_limit_exceeded` | 超过限流，按 `Retry-After` 退避 |
| 503 | `attachment_unavailable` | 附件或存储服务暂时不可用，稍后重试 |

## 检查与继续

**完成标准**：能够取得并下载可用文件，不保存短期下载 URL；下一步配置限流、重试和错误处理。

上一步：[读取内容与历史](/docs/documents)

**推荐下一步**：[限流、重试与排错](/docs/production)