instagram-private-api 响应模型解析：MediaUpdatedMediaResponseCaption 图文接口详解

导读

MediaUpdatedMediaResponseCaption 是 instagram-private-api 响应类型体系（responses 模块）中用于描述「媒体图文信息（Caption）」的标准接口，集中定义于 media.updated-media.response.ts。它出现在 Story 投票、滑块、问答等互动操作的返回结果中，是读取帖文/Story 文字说明、作者身份、时间戳与审核状态的关键数据载体。读完本文，你将掌握该接口的全部 13 个字段及其类型约束、它在响应对象树中的嵌套位置、以及它由哪些 API 调用触发生成，并能在自己的 TypeScript 项目中正确地消费这份数据。

一、接口定位：响应模型中的「图文」节点

在 instagram-private-api 的响应类型设计中，MediaUpdatedMediaResponseCaption 不是孤立存在的，它嵌套在如下响应对象树中：

MediaUpdatedMediaResponseRootObject
└── updated_media: MediaUpdatedMediaResponseUpdated_media
    ├── user: MediaUpdatedMediaResponseUser
    ├── image_versions2: MediaUpdatedMediaResponseImage_versions2
    ├── story_polls: MediaUpdatedMediaResponseStoryPollsItem[]
    ├── creative_config: MediaUpdatedMediaResponseCreative_config
    └── caption: MediaUpdatedMediaResponseCaption   ← 本篇主角

• 根对象 MediaUpdatedMediaResponseRootObject 仅含两个字段：updated_media（MediaUpdatedMediaResponseUpdated_media）与 status（string），见 media.updated-media.response.ts。
• updated_media 内部通过 caption: MediaUpdatedMediaResponseCaption 字段持有图文对象（media.updated-media.response.ts），与 user、image_versions2、story_polls 等字段并列。
• 顶层导出由 src/responses/index.ts 统一 export * from './media.updated-media.response' 暴露，因此可直接从包根导入使用。

从命名与嵌套结构看，「UpdatedMedia」系列接口专门建模「一次媒体更新操作之后由服务端返回的最新媒体快照」，而 caption 就是该快照中承载文字说明的部分。

二、字段全解析：13 个属性一览

该接口共声明 13 个属性，字段名与源码中的 interface MediaUpdatedMediaResponseCaption 完全一致（media.updated-media.response.ts）。为便于查阅，按语义分组如下。

1. 标识与归属（4 个）

属性	类型	源码行号	说明
pk	string	media.updated-media.response.ts:75	图文记录的主键（Primary Key），服务端生成的唯一标识，可用于与评论/图文对象关联比对
media_id	string	media.updated-media.response.ts:87	该图文所属媒体（Media）的 ID，用于反查所属帖文或 Story
user_id	number	media.updated-media.response.ts:76	图文作者的数值型用户 ID
user	MediaUpdatedMediaResponseUser	media.updated-media.response.ts:84	作者完整用户信息对象，见下文「嵌套用户对象」小节

2. 内容与类型（3 个）

属性	类型	源码行号	说明
text	string	media.updated-media.response.ts:77	图文正文，即帖文/Story 上展示的文字内容；可含换行符与话题标签
type	number	media.updated-media.response.ts:78	图文类型枚举值（数值），表示该 caption 的形态分类
content_type	string	media.updated-media.response.ts:81	内容类型标识字符串（如 comment），描述 caption 的数据种类

3. 时间信息（2 个）

属性	类型	源码行号	说明
created_at	number	media.updated-media.response.ts:79	图文创建时间的 Unix 时间戳（秒级）
created_at_utc	number	media.updated-media.response.ts:80	同一时刻的 UTC 时间戳（秒级），与 created_at 通常数值一致，供时区无关的排序与统计使用

4. 状态与审核（4 个）

属性	类型	源码行号	说明
status	string	media.updated-media.response.ts:82	图文状态标识字符串
bit_flags	number	media.updated-media.response.ts:83	位标志（bit flag）聚合值，多位标志通过位运算组合表示若干布尔状态
did_report_as_spam	boolean	media.updated-media.response.ts:85	是否曾被举报为垃圾内容
share_enabled	boolean	media.updated-media.response.ts:86	该图文是否允许被转发/分享

三、嵌套用户对象：MediaUpdatedMediaResponseUser

user 属性指向同文件定义的 MediaUpdatedMediaResponseUser（media.updated-media.response.ts），用于快速读取作者资料而无需再次发起网络请求，包含：

• 身份基础：pk: number、username: string、full_name: string、profile_pic_url: string、profile_pic_id: string
• 账号属性：is_private: boolean、is_verified: boolean、has_anonymous_profile_picture: boolean、is_unpublished: boolean、is_favorite: boolean
• 关系状态：friendship_status 指向 MediaUpdatedMediaResponseFriendship_status（media.updated-media.response.ts:68），内含 following、outgoing_request、is_bestie、is_restricted 四个布尔字段，可直接判断当前登录账号与作者的关注关系。

这使得在一次 Story 互动响应中即可同时拿到「图文内容 + 作者画像 + 关系状态」，无需二次查询。

四、哪些接口会返回它：三个 Story 互动端点

从源码调用关系看，返回 MediaUpdatedMediaResponseRootObject（因此包含 MediaUpdatedMediaResponseCaption）的仓库方法集中在 media.repository.ts，全部是 Story 互动类 POST 请求：

1. Story 投票：storyPollVote(mediaId, pollId, vote)，向 /api/v1/media/${mediaId}/${pollId}/story_poll_vote/ 提交投票（vote 取 '0' 或 '1'），见 media.repository.ts:713-730。
2. Story 滑块评分：storySliderVote(mediaId, sliderId, vote)，向 /api/v1/media/${mediaId}/${sliderId}/story_slider_vote/ 提交 0～1 的滑块分值，内部以 vote.toFixed(8) 格式化精度，见 media.repository.ts:758-774。
3. Story 问答作答：storyQuizAnswer(mediaId, quizId, answer)，向 /api/v1/media/${mediaId}/${quizId}/story_quiz_answer/ 提交选项索引（answer 为 '0' | '1' | '2' | '3'），见 media.repository.ts:782-797。

这三个方法都通过 this.client.request.send() 发送带签名（this.client.request.sign({ _csrftoken, _uuid, ... })）的表单，返回体即为根对象。也就是说，当你的脚本对某个 Story 投票、评分或答题后，服务端会返回包含最新图文与互动结果的 updated_media 快照，caption 就在其中——典型的「写操作后读取最新状态」模式。

五、实战示例：如何在代码中消费该接口

下面演示如何在使用 storyQuizAnswer 后读取返回的图文信息：

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

const ig = new IgApiClient();
// 完成登录后……
// ig.state.generateDevice(username); ig.state.proxyUrl = '...';
// await ig.account.login(username, password);

// 对 Story 中的 Quiz 作答，返回根对象
const result = await ig.media.storyQuizAnswer(mediaId, quizId, '1');

// 通过响应类型可直接获得类型提示
const updatedMedia = result.updated_media;
if (updatedMedia.caption) {
  const caption = updatedMedia.caption;
  console.log('图文 ID:', caption.pk);
  console.log('正文:', caption.text);
  console.log('发布时间戳:', caption.created_at_utc);
  console.log('作者:', caption.user.username, '| 认证:', caption.user.is_verified);
  console.log('被举报为垃圾:', caption.did_report_as_spam);
  console.log('允许分享:', caption.share_enabled);
}

由于接口字段类型已完整声明，IDE 会给出 caption.pk、caption.text 等属性的自动补全与类型校验，无需依赖 any 或自定义类型断言。同理，storyPollVote 与 storySliderVote 的返回值同样遵循该结构，可共用同一套消费逻辑。

六、同模块内其他「caption」的区分

MediaUpdatedMediaResponseCaption 只是本仓库大量 Caption 响应接口之一。搜索 src 目录可见各自独立的建模（如 MediaInfoResponseCaption、MediaCommentsFeedResponseCaption、LocationFeedResponseCaption 等），它们分别对应不同端点返回的图文形态。使用时注意按端点选择匹配的接口，避免混用。MediaUpdatedMediaResponseCaption 的特异性在于：

• 服务于「更新/互动后返回快照」这一场景，而非静态的帖子详情查询；
• text、pk、created_at、user 等字段齐备，可直接用于渲染与展示；
• 类型与 updated_media 中的 user、image_versions2、story_polls 组合成一份完整媒体快照。

七、注意事项

• 字段来源为服务端响应：以上字段结构与类型均对齐 Instagram 私有 API 的真实 JSON 载荷，属于「按响应反推」的类型定义，字段的可空性以运行时的实际返回为准；例如 caption 在部分媒体上可能缺失（仓库中多处响应以 caption: null 建模），取值前建议做存在性判断。
• 时间戳为秒级数值：created_at / created_at_utc 是秒级 Unix 时间戳（number），换算为 JavaScript Date 时需乘以 1000。
• bit_flags 为聚合位值：解读其布尔语义时应参考对应位定义，而非直接强转布尔。
• 仅建议读取：这些字段是响应模型，不用于构造上传/发布请求参数；发布场景请使用 PublishService 及 posting.*.options 类型的 caption 配置（参见 publish.service.ts 等处的 options.caption 用法）。

结语

MediaUpdatedMediaResponseCaption 以 13 个字段完整刻画了一条 Instagram 图文（Caption）的全部关键信息：身份归属（pk/media_id/user_id/user）、正文内容（text/type/content_type）、时间（created_at/created_at_utc）与状态审核（status/bit_flags/did_report_as_spam/share_enabled）。它由 Story 投票、滑块评分与问答作答三个互动端点随 updated_media 快照一并返回，是 instagram-private-api 中「写后读」模式的典型响应结构。结合本文的字段表与源码位置，你可以在自己的自动化脚本中准确、类型安全地消费这一数据节点。