下载图片与附件

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

调用前准备

先按获取与使用 API Key配置 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；下一步配置限流、重试和错误处理。