后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载导读SavedFeedResponseCarouselMediaItem是 instagram-private-apiNodeJS Instagram 私有 API SDKTypeScript 编写中定义「收藏夹 Feed 内轮播Carousel单页媒体」的 TypeScript 接口对应/api/v1/feed/saved/返回数据中carousel_media数组的每一项。本文将以该接口为骨架逐字段拆解轮播子项的图片与视频数据结构并结合 SavedFeed 的源码实现说明如何在收藏夹场景中实际读取、判断与消费这些数据帮助你精准提取收藏内容中每一张图片、每一段视频的原始资源。一、接口定位收藏夹里的「一张轮播卡片」在使用 instagram-private-api 时ig.feed.saved()返回的 SavedFeed 会请求GET /api/v1/feed/saved/接口见 src/feeds/saved.feed.ts分页返回当前账号保存过的所有帖子。从源码结构看每个帖子SavedFeedResponseMedia内部存在两个与轮播相关的可选字段见 src/responses/saved.feed.response.tscarousel_media_count?: number; carousel_media?: SavedFeedResponseCarouselMediaItem[];carousel_media_count轮播包含的媒体总数也就是总页数carousel_media轮播内每一页媒体对应的数据对象数组数组元素类型正是本篇文章的主角SavedFeedResponseCarouselMediaItem。也就是说当你收藏的是一个「多图/多视频」的轮播帖Instagram 常称 Album / Carousel时carousel_media数组会展开这个帖子的全部子媒体而当收藏的是普通单图或单视频帖时这两个字段通常不会出现子媒体信息直接落在image_versions2/video_versions等顶层字段上。SavedFeedResponseCarouselMediaItem的核心职责是用一个统一结构描述轮播中的某一页——无论这一页是图片还是视频都可以通过该接口拿到它的 ID、尺寸、图片候选地址、视频版本、时长以及用户标记usertags等完整信息。二、字段全景13 个属性的速查表该接口定义在 src/responses/saved.feed.response.ts共 13 个属性其中 8 个为必填、5 个为可选视频相关字段几乎全部可选因为轮播单页可能只是纯图片。速查如下属性类型必填/可选含义idstring必填该子媒体的完整媒体 IDmedia_typenumber必填子媒体类型图片/视频等数值标记image_versions2SavedFeedResponseImage_versions2必填图片候选版本集合original_widthnumber必填原始宽度original_heightnumber必填原始高度pkstring必填该子媒体的主键 IDcarousel_parent_idstring必填所属轮播父帖的 IDusertagsSavedFeedResponseUsertags必填该页图片上被 标记的用户列表video_versions?SavedFeedResponseVideoVersionsItem[]可选视频不同清晰度的版本列表video_duration?number可选视频时长秒is_dash_eligible?number可选是否支持 DASH 流式播放video_dash_manifest?string可选DASH manifest 文本XML/JSON 格式串video_codec?string可选视频编码格式如vp9、avc1number_of_qualities?number可选视频可用清晰度档位数注意TypeDoc 文档中is_dash_eligible、number_of_qualities、video_codec、video_dash_manifest、video_duration、video_versions均标注为Optional见 docs/interfaces/responses/SavedFeedResponseCarouselMediaItem.md即它们是轮播子项为视频时才可能存在的字段。三、必填字段详解轮播子项的基础骨架3.1 媒体 IDid与pkid和pk都用于唯一标识该子媒体idstring形如media_id的完整标识可用于拼接 API 路径例如mediaRepository.info({ mediaId })pkstring子媒体的主键 ID通常与id的数字部分一致但在本接口中单独暴露方便直接做去重、缓存或与本地数据库关联。两个字段均为string类型在使用时需要留意 Instagram 返回大整数时以字符串形式下发避免 JavaScript 的精度丢失问题。3.2 媒体类型media_typemedia_type是一个数值标记用于区分该子页是图片还是视频。从本仓库的 media.repository.ts 可看到删除媒体时存在PHOTO | VIDEO | CAROUSEL三种类别的显式枚举而 Instagram 私有 API 的通用约定是1表示图片、2表示视频、8表示轮播专辑。因此落在carousel_media数组里的子项media_type通常只会是1图片页或2视频页——你可以用它来决定优先读取image_versions2还是video_versions。3.3 图片资源image_versions2与原始尺寸image_versions2是必填字段类型为 SavedFeedResponseImage_versions2其内部只含一个candidates数组export interface SavedFeedResponseImage_versions2 { candidates: SavedFeedResponseCandidatesItem[]; } // SavedFeedResponseCandidatesItem: // width: number; height: number; url: string; estimated_scans_sizes?: number[];每个 SavedFeedResponseCandidatesItem 代表一张不同尺寸的图片候选candidates[0]通常即最高清版本可直接用作下载链接estimated_scans_sizes是服务端估算的图片体积信息可选。original_width/original_height则给出该子媒体被上传/保存时的原始像素尺寸可用于按比例裁剪、生成占位图或校验candidates中是否存在原图尺寸候选。3.4 归属关系carousel_parent_idcarousel_parent_id记录了该子媒体所属轮播父帖的 ID。它的存在让子媒体可以安全地与父帖SavedFeedResponseMedia解耦即使你在多个收藏中遇到同一张轮播页也能通过该字段精确归位到正确的父帖。3.5 用户标记usertagsusertags类型为 SavedFeedResponseUsertags结构为export interface SavedFeedResponseUsertags { in: SavedFeedResponseInItem[]; }in数组中的每个 SavedFeedResponseInItem 包含被标记用户的user信息pk、username、full_name、profile_pic_url等以及标记位置position: string[] | number[]在图片中的相对坐标。若该轮播页没有标记任何人in通常为空数组。四、可选字段详解轮播中的视频页当media_type 2视频页时以下字段会随之出现。它们与 SavedFeedResponseMedia 顶层字段的命名与语义完全一致可对照阅读。4.1video_versions多清晰度版本类型为 SavedFeedResponseVideoVersionsItem[]每个版本对象包含export interface SavedFeedResponseVideoVersionsItem { type: number; width: number; height: number; url: string; id: string; }url即该清晰度对应的视频直链width/height为该版本的分辨率type用于区分不同码率档位。实际下载时可按分辨率从高到低遍历选择合适的一版。4.2video_duration时长以秒为单位的视频时长number。可用于判断内容长短或在 UI 上直接展示播放时长。4.3 DASH 相关三件套is_dash_eligible、video_dash_manifest、video_codec、number_of_qualities这四个字段服务于 Instagram 的 DASH 自适应流媒体体系is_dash_eligiblenumber标记该视频是否支持 DASHDynamic Adaptive Streaming over HTTP播放非 0 即代表可用video_dash_manifeststringDASH 的 manifest 内容包含各分片/清晰度的描述供支持 DASH 的播放器直接消费video_codecstring编码格式标识常见的如vp9、avc1可据此判断设备兼容性number_of_qualitiesnumber可用清晰度档位数量。由于这四个字段均为可选且仅在视频页出现编写防御性代码时务必先判空再使用例如item.video_duration ?? 0或item.video_versions?.[0]?.url。五、实战从收藏夹 Feed 读取并消费轮播媒体5.1 建立客户端并登录参考 examples/session.example.ts 的标准初始化方式import { IgApiClient } from instagram-private-api; const ig new IgApiClient(); ig.state.generateDevice(process.env.IG_USERNAME); ig.state.proxyUrl process.env.IG_PROXY; await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD);5.2 遍历收藏夹并处理轮播ig.feed.saved()由 FeedFactory.saved() 提供返回 SavedFeed 实例其items()方法见 src/feeds/saved.feed.ts会自动展开items.map(i i.media)拿到SavedFeedResponseMedia[]再分页拉取const feed ig.feed.saved(); // 分页遍历全部收藏每页数量由服务端决定 do { const medias await feed.items(); for (const media of medias) { if (media.carousel_media media.carousel_media.length 0) { console.log(轮播帖 ${media.pk}共 ${media.carousel_media.length} 页); for (const item of media.carousel_media) { if (item.media_type 1) { // 图片页取最高清候选 const best item.image_versions2.candidates[0]; console.log([图片] ${best.width}x${best.height} - ${best.url}); } else if (item.media_type 2) { // 视频页取最高分辨率版本 const bestVideo item.video_versions?.[0]; console.log([视频] 时长 ${item.video_duration ?? 未知}s - ${bestVideo?.url}); } // carousel_parent_id 可用于回溯父帖 console.log( 归属父帖: ${item.carousel_parent_id}); } } } } while (feed.isMoreAvailable());说明SavedFeed.request()底层请求的是/api/v1/feed/saved/并携带max_id分页游标与include_igtv_preview: false参数见 src/feeds/saved.feed.tsmore_available/next_max_id会被同步进 feed 状态因此用isMoreAvailable()即可驱动完整分页。5.3 常见字段判空范式轮播子项是图片页时video_versions等字段为undefined反之image_versions2恒为必填。建议统一采用以下范式type CarouselItem import(instagram-private-api).SavedFeedResponseCarouselMediaItem; function resolveBestAsset(item: CarouselItem) { if (item.media_type 1) { return { kind: image, url: item.image_versions2.candidates[0].url }; } return { kind: video, url: item.video_versions?.[0]?.url, duration: item.video_duration, }; }六、同类结构横向对照轮播模型在各 Feed 中的一致性carousel_media?: XxxFeedResponseCarouselMediaItem[]的结构不仅存在于收藏夹。从仓库源码看以下响应模型同样定义了语义一致的轮播数组字段名、类型结构几乎一一对应src/responses/location.feed.response.ts地点 Feedsrc/responses/user.feed.response.ts用户主页 Feedsrc/responses/tags.feed.response.ts话题标签 Feedsrc/responses/tag.feed.response.tsTag Feedsrc/responses/timeline.feed.response.ts时间线 Feedsrc/responses/topical-explore.feed.response.ts探索 Feedsrc/responses/media.repository.configure-sidecar.response.ts发布轮播帖的返回结构这意味着你为SavedFeedResponseCarouselMediaItem编写的解析逻辑可以低成本复用到其他 Feed 的轮播数据处理上只需替换对应的接口类型即可。此外media.entity.ts 等实体层也会承载媒体元数据供上游业务统一访问。七、类型导出与源码定位接口定义SavedFeedResponseCarouselMediaItem位于 src/responses/saved.feed.response.ts与SavedFeedResponseMedia第 12 行起等同文件其中carousel_media字段声明在第 58 行类型导出整个saved.feed.response.ts通过 src/responses/index.ts 统一export *到包入口因此你可以直接以import { SavedFeedResponseCarouselMediaItem } from instagram-private-api的方式使用该类型接口文档TypeDoc 自动生成的完整字段文档见 docs/interfaces/responses/SavedFeedResponseCarouselMediaItem.md其中每个属性都标注了其在源码中的准确定义位置依赖类型image_versions2依赖 SavedFeedResponseImage_versions2、video_versions依赖 SavedFeedResponseVideoVersionsItem、usertags依赖 SavedFeedResponseUsertags三者均为同文件导出的兄弟接口。八、小结与使用建议SavedFeedResponseCarouselMediaItem虽然只是一个响应模型接口却是理解收藏夹轮播数据的钥匙。围绕它你可以确认四个关键信息这一页是图片还是视频media_type、最好的资源在哪里image_versions2.candidates[0]或video_versions[0]、它属于哪个父帖carousel_parent_id、以及页面上标记了谁usertags。实际开发中的几条建议区分必填与可选图片字段必填、视频字段可选判空是处理轮播子项的第一原则善用carousel_parent_id需要聚合整组轮播时用它作为分组键优先使用candidates[0]/video_versions[0]服务端一般按质量从高到低排序复用解析逻辑同一套轮播解析代码可同时服务收藏夹、用户主页、Tag、时间线等多个 Feed 场景。掌握了该接口你就能在 instagram-private-api 的收藏夹场景中精确、高效地提取任意轮播帖的全部图片与视频资源。赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐instagram-private-api 登录响应模型详解AccountRepositoryLoginResponseRootObject 接口完全指南instagram private api 登录响应模型详解AccountRepositoryLoginResponseRootObject 接口完全指南 本后端Nerd Fonts Roboto Mono Bold 字体选择与安装实战指南NF / NFM / NFP 变体、连字保留与自打补丁Nerd Fonts Roboto Mono Bold 字体选择与安装实战指南NF / NFM / NFP 变体、连字保留与自打补丁 导读 本文以 patch后端instagram-private-api 响应类型全解析DirectRepositoryCreateGroupThreadResponseFriendshipStatus 接口详解instagram private api 响应类型全解析DirectRepositoryCreateGroupThreadResponseFriendshi后端上一篇为什么选择Tempo模板引擎5大优势让前端开发更轻松下一篇Easings.net性能优化GPU加速动画的实现方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
