instagram-private-api 响应模型详解：SavedFeedResponseCaption 保存帖文文案接口全解析

导读

SavedFeedResponseCaption 是 NodeJS TypeScript 版 Instagram 私有 API SDK（instagram-private-api）中，用于描述「已保存帖文」文案（caption）的数据接口。当通过 ig.feed.saved() 拉取当前账号的收藏内容时，每个帖文对象的 caption 字段即为此接口的实例，承载帖文正文、发布时间、发布者信息与各项内容标志。读完本文，你将掌握该接口全部 14 个字段的类型与语义、其在响应结构树中的位置、时间戳与位标志的解读方法，并能直接写出读取收藏帖文文案的可用代码。

一、接口定位：保存帖文响应结构中的「文案节点」

SavedFeedResponseCaption 不是独立存在的顶层响应，而是保存帖文（Saved Feed）响应中的内嵌对象。从 src/responses/saved.feed.response.ts 的源码结构看，完整的数据链路为：

SavedFeedResponseRootObject
└── items: SavedFeedResponseItemsItem[]
    └── media: SavedFeedResponseMedia      // 单条保存的帖文
        └── caption: SavedFeedResponseCaption   // 本帖文案

• SavedFeedResponseMedia 在 saved.feed.response.ts:43 以 caption: SavedFeedResponseCaption 声明该字段为必选属性，意味着服务端返回的每条保存帖文都携带文案节点（即使无文字内容，也可能返回空字符串）。
• 该接口在文档的响应模块索引中被统一导出，位于 SavedFeedResponseCaption.md，其源码定义位于 saved.feed.response.ts:162-177。

二、接口全景：14 个属性的完整类型清单

以下属性表完整继承自原文档，并标注了对应源码行号（以 saved.feed.response.ts 为准）：

属性	类型	必选	源码行号	语义分类
pk	string	✓	L163	标识类
user_id	number	✓	L164	标识类
text	string	✓	L165	内容类
type	number	✓	L166	内容类
created_at	number	✓	L167	时间类
created_at_utc	number	✓	L168	时间类
content_type	string	✓	L169	内容类
status	string	✓	L170	内容类
bit_flags	number	✓	L171	标志类
user	SavedFeedResponseUser	✓	L172	关联类
did_report_as_spam	boolean	✓	L173	标志类
share_enabled	boolean	✓	L174	标志类
media_id	string	✓	L175	标识类
has_translation	boolean	✗（可选）	L176	标志类

除 has_translation 外，其余 13 个字段均为必选字段。TS 接口中的 ? 可空修饰符意味着服务端可能不返回该字段，读取时应做好缺省处理。

三、字段语义逐项解读

3.1 标识类：pk / media_id / user_id

• pk: string：文案记录在 Instagram 服务端的唯一主键，通常为一串数字字符串，可用于去重或日志追踪。
• media_id: string：该文案所属帖文的媒体 ID（media id），可用于反向关联到 SavedFeedResponseMedia.pk。
• user_id: number：发布者的用户 ID（数字形式），与 user.pk 对应。

3.2 内容类：text / type / content_type / status

• text: string：帖文正文。这是使用频率最高的字段，可直接用于内容检索、数据导出或自动回复场景。
• type: number：内容类型数值，常见如 1（图片）与 2（视频）对应的文案标记，具体含义与媒体类型联动。
• content_type: string：内容形态描述，典型值为 comment 字符串，表示该节点属于评论式内容载体。
• status: string：节点状态标识，服务端通常会返回 ok，可用于快速校验响应合法性。

3.3 时间类：created_at / created_at_utc

• 两个字段均为 Unix 时间戳（秒级，number），分别表示发布时间的本地化与 UTC 表述。
• 换算示例：new Date(caption.created_at_utc * 1000).toISOString() 可得到标准 ISO 时间字符串。

3.4 标志类：bit_flags / did_report_as_spam / share_enabled / has_translation

• bit_flags: number：位标志位集合，Instagram 客户端常用于压缩布尔状态；不同位代表「是否已编辑」「是否含敏感词」等语义，应按位运算解读。
• did_report_as_spam: boolean：是否被举报为垃圾内容。
• share_enabled: boolean：是否允许对外分享/转发该帖文。
• has_translation?: boolean：可选字段，为 true 表示该文案存在翻译结果，可用于多语言展示逻辑。

3.5 关联类：user

• user: SavedFeedResponseUser：内嵌的发布者用户对象，字段定义见 SavedFeedResponseUser.md，包含 pk、username、full_name、is_private、profile_pic_url、is_verified 等用户核心信息（源码见 saved.feed.response.ts:70-86）。

四、实战：从 SavedFeed 中读取文案

SavedFeedResponseCaption 的获取入口是 ig.feed.saved()，该方法在 src/core/feed.factory.ts:218-220 中直接实例化 SavedFeed，无需额外初始化参数：

import { IgApiClient } from 'instagram-private-api';

const ig = new IgApiClient();
// 登录等初始化省略（参见 examples/session.example.ts）

(async () => {
  // 创建 SavedFeed 实例（无参工厂方法）
  const savedFeed = ig.feed.saved();
  // 拉取第一页保存帖文，返回 SavedFeedResponseMedia[]
  const firstPage = await savedFeed.items();

  for (const media of firstPage) {
    const caption = media.caption; // SavedFeedResponseCaption
    if (caption) {
      console.log(`[${media.pk}] ${caption.user.username}: ${caption.text}`);
      console.log(`  发布于 ${new Date(caption.created_at_utc * 1000).toISOString()}`);
      console.log(`  翻译可用: ${caption.has_translation ?? false}`);
    }
  }
})();

关键点说明：

• SavedFeed.items() 在 src/feeds/saved.feed.ts:26-29 中通过 items.map(i => i.media) 剥掉 items 外层包装，直接返回 SavedFeedResponseMedia[]，因此每一页即可直接访问 media.caption。
• 分页基于 max_id 游标：request()（src/feeds/saved.feed.ts:14-24）向 /api/v1/feed/saved/ 发送请求，携带 max_id 与 include_igtv_preview: false 查询参数，并通过 set state 更新 moreAvailable 与 nextMaxId；持续调用 items() 即可翻页。
• 如需流式消费所有页，可改用 savedFeed.items$（Observable），它在 src/core/feed.ts:18-20 定义，底层自动按 src/core/feed.ts:27-50 的重试策略（默认 delay: 60000、maxAttempts: 10、jitter: true）处理 400/429/500/502 等限流响应。

五、响应模型的代码生成与类型生态

从仓库结构看，SavedFeedResponseCaption 这类接口由 tools/response-to-interface.ts 生成脚本从真实响应样本批量生成，并被 src/responses/index.ts:69 统一导出。与之同族的 SavedFeedResponsePreviewCommentsItem（saved.feed.response.ts:93-111）在字段上与 Caption 高度一致（同样包含 pk、text、type、created_at、user、did_report_as_spam 等），可相互印证评论与文案共用同一套内容描述模式。

六、使用注意事项

1. 可空字段处理：has_translation 为可选字段，直接读取可能得到 undefined，建议使用 ?? false 做缺省兜底。
2. 时间戳单位：created_at / created_at_utc 为秒级 Unix 时间戳，JavaScript 的 Date 需要乘以 1000。
3. 文案与媒体类型：type、content_type 的取值随帖文媒体类型（图片/视频/轮播）变化，不宜硬编码判断，应结合 SavedFeedResponseMedia.media_type 一并使用。
4. 空文案边界：没有正文的帖文其 text 可能为空字符串，涉及内容过滤时需兼容空串场景。

通过本文，你可以基于 SavedFeedResponseCaption 的字段模型，直接在 instagram-private-api 中读取、解析和归档账号收藏帖文的文案数据；如需查看更多响应接口，可查阅响应接口文档目录及响应模块索引。