后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载本指南以 instagram-private-api 仓库中 TypeDoc 生成的接口文档 ReelsMediaFeedResponseStoryCountdownsItem 为核心深入解析 Instagram Story 中倒计时贴纸Countdown Sticker在 API 响应里的完整数据模型包括 10 个贴纸布局字段与嵌套的countdown_sticker载荷结构。读完本文你将掌握通过ReelsMediaFeed拉取并解析带倒计时贴纸的 Story、将响应字段与发布侧StickerBuilder.countdown参数一一对应以及基于end_ts做倒计时业务判断的完整实战能力。一、接口定位倒计时贴纸在响应树中的位置ReelsMediaFeedResponseStoryCountdownsItem是 instagram-private-api 中reels_mediaStory 批量拉取响应嵌套结构里的一个叶子节点接口定义在 src/responses/reels-media.feed.response.ts:181-192。从接口文档的命名空间归属responses 模块可以看出它属于响应类型族response interfaces即 SDK 对 Instagram 私有 API 返回 JSON 的 TypeScript 静态类型映射。其完整数据链路如下ReelsMediaFeedResponseRootObject └── reels: ReelsMediaFeedResponseReels以用户 pk 为键 └── ReelsMediaFeedResponse └── items: ReelsMediaFeedResponseItem[] └── story_countdowns?: ReelsMediaFeedResponseStoryCountdownsItem[] └── countdown_sticker: ReelsMediaFeedResponseCountdown_sticker其中story_countdowns在 ReelsMediaFeedResponseItem 中声明为可选数组Optional story_countdowns: ReelsMediaFeedResponseStoryCountdownsItem[]对应 src/responses/reels-media.feed.response.ts:80——只有当该条 Story 确实附加了倒计时贴纸时此字段才会出现。ReelsMediaFeedResponseStoryCountdownsItem与同文件中并列的ReelsMediaFeedResponseStoryPollsItem、ReelsMediaFeedResponseStoryQuestionsItem、ReelsMediaFeedResponseStoryQuizsItem、ReelsMediaFeedResponseStorySlidersItem结构完全平行都遵循布局字段 专属贴纸载荷的模式这也从源码层面印证了 Instagram 对各类 Story 贴纸统一建模的规律。二、布局与状态字段详解贴纸画在哪里、是否可见ReelsMediaFeedResponseStoryCountdownsItem的 10 个属性中前 9 个描述贴纸在 Story 画面上的布局与显示状态类型均为number属性类型语义说明xnumber贴纸中心点的归一化横坐标0 1相对画面宽度ynumber贴纸中心点的归一化纵坐标0 1相对画面高度znumber贴纸层叠次序z-index数值越大越靠前widthnumber贴纸宽度的归一化比例相对画面宽度heightnumber贴纸高度的归一化比例相对画面高度rotationnumber贴纸旋转角度0 360°is_pinnednumber是否被用户固定/置顶在 Story 上0 或 1is_hiddennumber是否对观众隐藏0 或 1is_stickernumber是否属于贴纸类型标记通常为 1countdown_stickerReelsMediaFeedResponseCountdown_sticker倒计时贴纸的实际内容载荷值得注意的是is_pinned、is_hidden、is_sticker三个字段在服务端返回中类型是number0/1而非boolean这与 SDK 发布侧见下文第四节使用true/false的布尔表达不同是读取响应时常见的坑点。坐标与尺寸的归一化语义这 9 个布局字段并非随机生成而是与 InstaSticker 基类一一对应该基类定义了width、height、rotation默认 0.0、x默认 0.0、y默认 0.0、z默认 0以及isSticker默认true并提供center()、rotateDeg(deg)、scale(factor)、moveForward/moveBackwards(layers)、right/left/top/bottom()等链式布局方法。其中right()将x设为1.0 - width / 2left()将x设为width / 2可见 SDK 以画面宽高的归一化比例0 1为坐标系x 0.5, y 0.5即画面正中央center()的实现。因此响应中的width: 0.703125、height: 0.26013514countdown.sticker.ts 中的默认值表示贴纸约占画面宽度 70.3%、高度 26%在服务端渲染时按此比例换算为像素坐标。三、countdown_sticker倒计时贴纸的核心载荷接口文档将countdown_sticker指向独立的嵌套接口 ReelsMediaFeedResponseCountdown_sticker定义在 src/responses/reels-media.feed.response.ts:193-206共 12 个字段属性类型语义说明countdown_idnumber倒计时贴纸的服务端唯一 ID可用于后续业务关联end_tsnumber倒计时截止的Unix 时间戳秒用于计算剩余时间textstring贴纸上显示的标题文案如 My Countdowntext_colorstring文案颜色十六进制如#ffffffstart_background_colorstring背景渐变起始色十六进制end_background_colorstring背景渐变结束色十六进制digit_colorstring倒计时数字颜色十六进制digit_card_colorstring倒计时数字卡片背景色十六进制支持带 alpha 的#ffffffcc形式following_enabledboolean是否开启关注提醒倒计时结束后推送is_ownerboolean当前登录用户是否是该倒计时贴纸的创建者attributionnull归因信息服务端当前固定返回nullviewer_is_followingboolean当前查看者是否已关注贴纸创建者从接口文档的源码锚点reels-media.feed.response.ts:194-205可以看出这些字段与发布侧参数见第四节一一对应颜色字段全部要求十六进制格式。end_ts是业务上最有价值的字段它是 Unix 秒级时间戳可直接用end_ts * 1000得到毫秒时间戳与Date.now()对比判断倒计时是否已经结束。四、读写闭环从 StickerBuilder.countdown 发布到响应回读要真正理解响应模型必须看懂它的来源——SDK 发布 Story 时如何构造这组数据。仓库提供了完整的读写闭环4.1 发布侧CountdownSticker 与 StoryCountdown 类型CountdownSticker 是贴纸构建类id固定返回countdown_sticker_timekey固定返回story_countdowns——key决定了它在StickerBuilder.build()中序列化后写入的配置键名sticker-builder.ts:30-52即story_countdowns字段。其endTssetter 支持传入DateTimeluxon或数字传入DateTime时执行Math.floor(value.toUTC().toSeconds())转为UTC 秒级 Unix 时间戳countdown.sticker.ts:12-18与响应中end_ts: number的类型与语义完全吻合。默认样式值textColor #ffffff、startBackgroundColor #ca2ee1、endBackgroundColor #5eb1ff、digitColor #7e0091、digitCardColor #ffffffcc、followingEnabled true在 countdown.sticker.ts:21-26 中定义。底层配置类型 StoryCountdown 扩展自StorySticker即 x/y/width/height/rotation 布局字段要求text、四个颜色字段、end_ts、following_enabled、is_sticker: true全部存在——这正是响应接口countdown_sticker各字段除服务端补充的countdown_id、is_owner、viewer_is_following、attribution之外的镜像。4.2 PublishService 的写入路径PublishService.story 在检测到options.countdown存在时会执行if (typeof options.countdown ! undefined) { configureOptions.story_countdowns [options.countdown]; storyStickerIds.push(countdown_sticker_time); }见 src/services/publish.service.ts:370-373并把countdown_sticker_time追加进story_sticker_ids逗号分隔串与 media.configure-story.options.ts:23 的类型注释story_sticker_ids countdown_sticker_time一致。而StickerBuilder.build()会把 sticker 按key分组后JSON.stringify输出sticker-builder.ts:42-46最终随configureToStory请求发送。4.3 读取侧ReelsMediaFeed 拉取与解析ReelsMediaFeed 通过POST /api/v1/feed/reels_media/拉取指定userIds的 Story 媒体请求体携带_uuid、_uid、_csrftoken、device_id与supported_capabilities_new见 reels-media.feed.ts:12-27其items()方法将body.reels中所有用户的items扁平化返回reels-media.feed.ts:29-35。每条 item 若含倒计时贴纸其story_countdowns数组的每个元素即为本文档所述的ReelsMediaFeedResponseStoryCountdownsItem。五、实战示例解析带倒计时贴纸的 Story结合 examples/upload-story.example.ts 中StickerBuilder.countdown({ text, endTs })的用法下面给出从发布到回读的完整闭环示例import { IgApiClient } from instagram-private-api; import { DateTime, Duration } from luxon; import { StickerBuilder } from instagram-private-api/sticker-builder; import { readFile } from fs; import { promisify } from util; const readFileAsync promisify(readFile); const ig new IgApiClient(); // 1. 发布附带 1 小时后截止的倒计时贴纸与 examples/upload-story.example.ts:74-80 相同 async function publishWithCountdown() { await ig.state.generateDevice(process.env.IG_USERNAME); await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD); const file await readFileAsync(./myStory.jpg); await ig.publish.story({ file, stickerConfig: new StickerBuilder() .add( StickerBuilder.countdown({ text: My Countdown, // ts-ignore endTs: DateTime.local().plus(Duration.fromObject({ hours: 1 })), // 1 小时后截止 }).center(), ) .build(), }); } // 2. 回读拉取用户 Story解析倒计时贴纸 async function readCountdowns(userId: number | string) { const feed ig.feed.reelsMedia({ userIds: [userId] }); const items await feed.items(); for (const item of items) { for (const countdown of item.story_countdowns ?? []) { const remainingMs countdown.countdown_sticker.end_ts * 1000 - Date.now(); console.log({ text: countdown.countdown_sticker.text, endAt: new Date(countdown.countdown_sticker.end_ts * 1000), remainingSec: Math.max(0, Math.floor(remainingMs / 1000)), isOwner: countdown.countdown_sticker.is_owner, viewerIsFollowing: countdown.countdown_sticker.viewer_is_following, position: { x: countdown.x, y: countdown.y, z: countdown.z }, size: { width: countdown.width, height: countdown.height }, rotation: countdown.rotation, }); } } }要点提醒响应中is_pinned/is_hidden/is_sticker是number0/1如需布尔语义可自行Boolean(countdown.is_sticker)end_ts为 UTC 秒级时间戳跨时区计算剩余时间时直接* 1000与Date.now()比较即可story_countdowns为可选字段读取时应做空值保护如?./?? []与 ReelsMediaFeedResponseItem 中Optional标注一致attribution固定为null无需解析逻辑。六、类型族对比与小结ReelsMediaFeedResponseStoryCountdownsItem与ReelsMediaFeedResponseStoryPollsItem、ReelsMediaFeedResponseStoryQuestionsItem、ReelsMediaFeedResponseStoryQuizsItem、ReelsMediaFeedResponseStorySlidersItem共享同一套布局字段x/y/z/width/height/rotation/is_pinned/is_hidden/is_sticker 专属载荷骨架全部定义于 src/responses/reels-media.feed.response.ts 的 82-206 行区间区别仅在载荷对象的字段倒计时countdown_stickerend_ts 颜色 following_enabled投票poll_stickertallies统计 viewer_can_vote提问question_stickerquestion 配色 viewer_can_interact测验quiz_stickercorrect_answertalliesviewer_can_answer滑动评分slider_stickerslider_vote_averageslider_vote_count。理解这一统一模型后你可以用同一种遍历方式处理全部贴纸类型并根据载荷对象的差异分别提取业务数据。若需追溯完整的响应根结构可继续阅读 ReelsMediaFeedResponse 与 ReelsMediaFeedResponseRootObject若需了解构建端能力可查看 CountdownSticker 与 StickerBuilder 的完整源码。赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐instagram-private-api 响应模型详解ReelsMediaFeedResponseStorySlidersItem 与 Story 滑块贴纸数据链路instagram private api 响应模型详解ReelsMediaFeedResponseStorySlidersItem 与 Story 滑块贴纸后端instagram-private-api 响应类型详解MediaUpdatedMediaResponsePoll_sticker 与 Story 投票贴纸数据结构instagram private api 响应类型详解MediaUpdatedMediaResponsePoll_sticker 与 Story 投票贴纸数后端instagram-private-api 响应类型详解MediaUpdatedMediaResponseStoryPollsItem 与 Story 投票贴纸数据结构instagram private api 响应类型详解MediaUpdatedMediaResponseStoryPollsItem 与 Story 投票贴后端上一篇Dunst 版本发布全流程指南基于 release-checklist 的完整发布操作手册下一篇PaddleClas PULC 含文字图像方向分类模型实战从训练、知识蒸馏到部署的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考