instagram-private-api 响应类型深度解析：ReelsMediaFeedResponse 接口与 Reels 故事流（Stories）数据模型

后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载导读ReelsMediaFeedResponse是 instagram-private-apiNodeJS Instagram 私有 API SDKTypeScript 编写中描述**单个用户 Reels 故事包story reel**的响应类型接口。它是ReelsMediaFeed对应 Instagram 私有接口POST /api/v1/feed/reels_media/返回的根对象ReelsMediaFeedResponseRootObject中reels字典的值类型承载了该用户故事包的整体状态有效期、已读标记、媒体计数以及可浏览的故事条目items。阅读本文后你将完整掌握该接口的全部字段语义、与ReelsMediaFeed的调用链关系并能基于它编写批量拉取多个用户 Stories → 解析媒体内容 → 标记已读的完整实战代码。一、接口在响应体系中的位置1.1 三层嵌套的响应结构从源码 src/responses/reels-media.feed.response.ts 可以清晰看到ReelsMediaFeedResponse所处的三层结构export interface ReelsMediaFeedResponseRootObject { reels: ReelsMediaFeedResponseReels; status: string; // 接口状态正常为 ok } export interface ReelsMediaFeedResponseReels { [pk: string]: ReelsMediaFeedResponse; // 以用户 pk 为键的字典 } export interface ReelsMediaFeedResponse { id: number; latest_reel_media: number; expiring_at: number; seen: number; can_reply: boolean; can_reshare: boolean; reel_type: string; user: ReelsMediaFeedResponseUser; items: ReelsMediaFeedResponseItem[]; prefetch_count: number; media_count: number; }根对象ReelsMediaFeedResponseRootObject仅含reels与status两个字段可参考接口文档 ReelsMediaFeedResponseRootObjectreels字典ReelsMediaFeedResponseReels键为用户pkstring值为ReelsMediaFeedResponse见接口文档 ReelsMediaFeedResponseReels本篇主角ReelsMediaFeedResponse单个用户的故事包描述对象对应本文档 ReelsMediaFeedResponse。1.2 与 Feed 类的关系ReelsMediaFeed在 src/feeds/reels-media.feed.ts 中被声明为FeedReelsMediaFeedResponseRootObject, ReelsMediaFeedResponseItem即请求得到的根类型是ReelsMediaFeedResponseRootObject而items()输出的元素类型是ReelsMediaFeedResponseItem。ReelsMediaFeedResponse是两者之间的中间层——它作为字典的值被遍历其items数组被扁平化汇入最终结果。该 Feed 类的完整成员与方法可参考文档 ReelsMediaFeed。二、ReelsMediaFeedResponse 全部字段详解以下字段均定义于 src/responses/reels-media.feed.response.ts#L8-L20与本文档的 Properties 一一对应。2.1 身份与时间字段字段类型说明idnumber故事包的媒体 IDreel media pk用于拼装seen已读上报的键名latest_reel_medianumber故事包内最新一条story 的时间戳/媒体标识用于快速判断是否有新内容expiring_atnumber故事包过期时间Unix 秒级时间戳。Instagram Stories 默认 24 小时有效超过该时间点的故事不可再拉取seennumber当前登录用户最后一次看到该故事包的时间戳Unix 秒级可用于判断是否全部已读其中expiring_at与seen在开发Stories 已读状态同步类功能时是核心判断依据若seen expiring_at说明该用户当前这条故事流已被全部看完。2.2 交互权限字段字段类型说明can_replyboolean当前用户是否可以向该故事包回复消息决定能否对 story 发起 DM 回复can_reshareboolean当前用户是否可以将该故事转发/分享到自己的故事这两个字段由发布者是否开启允许回复/允许分享决定也受关注关系影响。它们在判断能否对该用户的故事执行后续互动时非常实用。2.3 类型与内容字段字段类型说明reel_typestring故事包类型常见取值如普通 story 流对应的类型标记存在live、highlight等变体时可用于区分来源userReelsMediaFeedResponseUser故事发布者的用户摘要信息pk、username、头像等详见下文 2.4itemsReelsMediaFeedResponseItem[]故事包中的全部 story 条目是实际媒体内容图片/视频的载体prefetch_countnumber客户端预取prefetch的条目数量反映服务端建议的预加载条数media_countnumber故事包中的媒体总数可直接用于判断故事条数2.4 内嵌的用户摘要useruser字段的类型为ReelsMediaFeedResponseUser定义在同文件 src/responses/reels-media.feed.response.ts#L21-L30其接口文档见 ReelsMediaFeedResponseUser字段类型可选性说明pknumber必填用户唯一 IDusernamestring可选用户名full_namestring可选昵称is_privateboolean可选是否私密账号profile_pic_urlstring可选头像 URLprofile_pic_idstring可选头像媒体 IDfriendship_statusReelsMediaFeedResponseFriendshipStatus可选与当前登录用户的关注关系following、incoming_request、is_bestie等is_verifiedboolean可选是否认证账号注意items中每条 story 也内嵌了同样的user摘要见 src/responses/reels-media.feed.response.ts#L59因此在业务中既可以拿ReelsMediaFeedResponse.user作为作者信息也可以在逐条处理items时直接取item.user。三、ReelsMediaFeedResponseItemitems 数组中的媒体条目items是ReelsMediaFeedResponse最核心的内容字段元素类型ReelsMediaFeedResponseItem的接口文档见 ReelsMediaFeedResponseItem其定义同样位于 src/responses/reels-media.feed.response.ts#L38-L81。下面按用途分组说明关键字段。3.1 基础标识字段类型说明pkstring媒体主键配合user.pk可拼出已读上报键${item.id}_${sourceId}idstring媒体完整 IDpk与 user pk 拼接形式已读上报直接使用该字段codestring媒体短码如BxKabcDE用于拼接网页链接instagram.com/p/{code}/media_typenumber媒体类型1图片2视频3轮播用于区分渲染方式taken_atnumber发布时间戳Unix 秒已读上报中作为取值的一部分device_timestampstring设备侧时间戳client_cache_keystring客户端缓存键filter_typenumber滤镜类型编号3.2 媒体内容数据字段类型说明image_versions2ReelsMediaFeedResponseImageVersions2图片多分辨率候选列表candidates每项含width/height/url选择适配屏宽的分辨率即可original_width/original_heightnumber原始尺寸video_versionsReelsMediaFeedResponseVideoVersionsItem[]视频多码率版本type/width/height/url/id取最大type或最接近目标尺寸的 URLvideo_dash_manifeststringDASH 自适应流清单可用于流式播放video_codecstring视频编码格式number_of_qualitiesnumber可用视频质量档位数量has_audioboolean是否含音频video_durationnumber视频时长秒is_dash_eligiblenumber是否支持 DASH 播放caption_positionnumber字幕/文字位置标记is_reel_mediaboolean是否为 reelstory媒体3.3 互动与状态字段字段类型说明captionnull当前 SDK 将 story 的 caption 声明为nullstory 场景一般不携带独立 captioncaption_is_editedboolean文字是否被编辑过photo_of_youboolean是否标记了你can_viewer_saveboolean查看者能否保存can_reshare/can_replyboolean单条 story 的分享/回复许可与故事包级字段可能不同supports_reel_reactionsboolean是否支持 story 表情回应reactshow_one_tap_fb_share_tooltipboolean是否展示一键分享到 Facebook 的提示has_shared_to_fbnumber是否已分享到 Facebookorganic_tracking_tokenstring归因追踪 tokenexpiring_atnumber单条 story 的过期时间戳imported_taken_atnumber可选从其他平台导入的原始时间戳3.4 贴纸与扩展字段均可选items中内嵌了与互动贴纸相关的可选字段可用于解析投票、提问、测验、滑动条、倒计时和提及等交互元素reel_mentions?story 中提及的用户含坐标x/y/z/width/height/rotation与userstory_polls?投票贴纸含poll_stickerquestion、tallies、viewer_can_vote、viewer_vote?、finished等story_questions?提问贴纸含question_stickerquestion、media_id、viewer_can_interactstory_quizs?测验贴纸含quiz_stickerquestion、tallies、correct_answer、viewer_answer?story_sliders?滑动评分贴纸含slider_stickerquestion、emoji、viewer_vote?story_countdowns?倒计时贴纸含countdown_stickerend_ts、text、is_owner、viewer_is_followingstory_cta?行动号召按钮links含webUri、deeplinkUri、callToActionTitle等ad_action?/link_text?广告类附加字段。这些贴纸坐标字段x/y/z/width/height/rotation在故事包级接口与单条 item 级接口中结构一致便于统一解析。四、底层调用链从 userIds 到 ReelsMediaFeedResponse4.1 请求的发起ReelsMediaFeed的request()实现见 src/feeds/reels-media.feed.ts#L12-L27向私有端点POST /api/v1/feed/reels_media/发送请求表单中携带user_ids目标用户 pk 数组本接口支持一次查询多个用户的故事包这是与UserStoryFeed单用户/api/v1/feed/user/{userId}/story/见 src/feeds/user-story.feed.ts的关键区别source来源模块默认feed_timelineIgAppModule类型定义见 src/types/common.types.ts可传story_viewer_profile、story_viewer_default等_uuid、_uid、_csrftoken、device_id请求签名所需的会话参数supported_capabilities_new序列化后的客户端能力列表来自 src/samples/supported-capabilities.json。返回体即ReelsMediaFeedResponseRootObject其中reels就是user pk →ReelsMediaFeedResponse的映射。4.2 items() 的扁平化逻辑async items(): PromiseReelsMediaFeedResponseItem[] { const body await this.request(); return Object.values(body.reels).reduce( (accumulator, current: ReelsMediaFeedResponse) accumulator.concat(current.items), [], ); }从 src/feeds/reels-media.feed.ts#L29-L35 可以看到items()会遍历根对象reels字典中的每一个ReelsMediaFeedResponse将其items数组合并成一个扁平的 story 条目列表。因此当传入多个userIds时返回的items会混入多个用户的故事如需区分归属请使用item.user.pk或item.id前缀。4.3 FeedFactory 的创建入口ReelsMediaFeed实例通过ig.feed.reelsMedia(options)创建见 src/core/feed.factory.ts#L153-L155public reelsMedia(options: { userIds: Arraynumber | string; source?: IgAppModule }): ReelsMediaFeed { return plainToClassFromExist(new ReelsMediaFeed(this.client), options); }userIds必填Arraynumber | string一次可传入多个用户 pksource?可选默认feed_timeline。4.4 继承自基类 Feed 的能力ReelsMediaFeed继承自抽象基类 src/core/feed.ts因而天然具备attemptOptions默认重试策略{ delay: 60000, factor: 1.5, maxAttempts: 10, minDelay: 60000, maxDelay: 300000, jitter: true }对 400/429/500/502 等状态码自动退避重试observable(semaphore?, attemptOptions?)/items$RxJS 流式拉取能力适合长时间轮询场景serialize()/deserialize(data)/toPlain()基于 class-transformer 的序列化持久化能力可用于缓存 Feed 状态isMoreAvailable()判断是否还有更多页Reels 场景下当前实现未分页statesetter 为空实现见 src/feeds/reels-media.feed.ts#L10。五、实战批量拉取多用户 Stories 并标记已读官方示例 examples/user-stories-watching.example.ts 完整演示了本接口的典型用法结合上面解析的字段可以组成如下完整链路import dotenv/config; import { IgApiClient } from ../src; (async () { const ig new IgApiClient(); ig.state.generateDevice(process.env.IG_USERNAME); ig.state.proxyUrl process.env.IG_PROXY; const auth await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD); // 1. 精确搜索目标用户拿到其 pk const targetUser await ig.user.searchExact(username); // 2. 通过 FeedFactory 创建 ReelsMediaFeed可一次传入多个 user pk const reelsFeed ig.feed.reelsMedia({ userIds: [targetUser.pk], }); // 3. items() 内部即返回扁平化的 ReelsMediaFeedResponseItem[] const storyItems await reelsFeed.items(); if (storyItems.length 0) { console.log(${targetUser.username}s story is empty); return; } // 4. 依据 ReelsMediaFeedResponseItem 的字段做内容分发 for (const item of storyItems) { const { media_type, image_versions2, video_versions, expiring_at } item; if (media_type 1) { const candidate image_versions2.candidates.sort((a, b) b.width - a.width)[0]; console.log(图片 URL:, candidate.url); } else if (media_type 2) { const best video_versions.sort((a, b) b.type - a.type)[0]; console.log(视频 URL:, best.url, 时长:, item.video_duration, 秒); } console.log(该条 story 过期时间:, new Date(expiring_at * 1000).toISOString()); } // 5. 通过 StoryService 标记已读内部调用 /api/v2/media/seen/ const seenResult await ig.story.seen([storyItems[0]]); console.log(seenResult.status); // ok })();5.1 已读上报的底层原理ig.story.seen(input)由 src/services/story.service.ts 实现它依赖ReelsMediaFeedResponseItem的两个字段构造上报数据取item.id与item.user.pk拼接出键名${item.id}_${sourceId}sourceId默认取item.user.pk取item.taken_at与当前时间构造值${itemTakenAt}_${seenAt}通过ig.story.seen→this.client.media.seen(reels)最终 POST 到/api/v2/media/seen/见 src/repositories/media.repository.ts#L649-L669。这正是ReelsMediaFeedResponse的items元素之所以必须携带id、taken_at、user的原因——它们直接服务于已读状态上报协议。六、接口使用注意事项隐私账号限制私密账号is_private true的 Stories 仅对关注者可见拉取非关注私密用户时reels中可能缺少对应键或items为空需结合user.friendship_status判断过期时效expiring_at为秒级 Unix 时间戳访问过期故事会得到空结果或错误业务侧应在过期前拉取多用户去重传入多个userIds时items()扁平化结果不区分来源建议按item.user.pk或item.id进行分组处理请求频率批量拉取请控制频率遇到限流时依赖Feed.attemptOptions的指数退避重试机制自动等待能力清单请求携带supported_capabilities_new不同客户端能力声明会影响服务端返回的媒体格式与字段完整性。总结ReelsMediaFeedResponse是整个 Reels 故事流数据链路的骨架类型根对象通过reels字典把它与用户pk关联它自身通过items数组携带实际媒体条目而item的id/taken_at/user字段又支撑着已读上报协议。掌握本文档中 11 个顶层字段ReelsMediaFeedResponse及其关联类型ReelsMediaFeedResponseItem、ReelsMediaFeedResponseUser配合 ReelsMediaFeed 与 FeedFactory.reelsMedia 的调用入口即可在项目中安全、完整地实现 Stories 拉取、内容解析与已读同步功能。赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐instagram-private-api 故事问答响应数据模型StoryQuestionResponsesFeedResponseRootObject 接口深度解析instagram private api 故事问答响应数据模型StoryQuestionResponsesFeedResponseRootObject 接口后端instagram-private-api 响应类型解析IgtvBrowseFeedResponseComposer 接口与 IGTV 浏览流数据模型instagram private api 响应类型解析IgtvBrowseFeedResponseComposer 接口与 IGTV 浏览流数据模型 Igt后端instagram-private-api Stories 数据分析StoriesInsightsFeedResponseData 接口结构与响应链路深度解析instagram private api Stories 数据分析StoriesInsightsFeedResponseData 接口结构与响应链路深度解析后端上一篇5个关键理由为什么现代C项目需要统一的硬件信息采集库下一篇现代C跨平台硬件抽象统一接口的模块化解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考