后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载本文基于 StickerBuilder 类文档 与配套源码系统讲解instagram-private-apiNodeJS/TypeScript 编写的 Instagram 私有 API SDK中用于在 Story 上叠加贴纸sticker的StickerBuilder类从静态工厂方法、可链式调用的布局 API到build()如何把多个贴纸对象序列化成 Instagram 私有接口要求的story_sticker_ids JSON 数组负载并结合publish.story()的实际调用链给出完整可运行的示例。一、StickerBuilder 是什么StickerBuilder定义在 src/sticker-builder/sticker-builder.ts由 src/sticker-builder/index.ts 统一导出。它是 SDK 为 Story 贴纸提供的构建器 静态工厂门面静态工厂方法每种贴纸类型hashtag、mention、location、countdown、chat、poll、question、quiz、slider、attachment都对应一个static方法内部通过class-transformer的plainToClass()把普通 JS 对象转换成对应的InstaSticker子类实例。源码中的注释说明这是wrappers, so you only have to import StickerBuilder——即用户只需 import 一个StickerBuilder就能创建所有贴纸实例方法add()/build()add(sticker)把贴纸压入内部数组并返回this以支持链式调用build()把所有贴纸聚合成最终发给服务器的StickerConfig参数类型StickerOptionsT定义在同文件第 18 行StickerOptionsT extends InstaSticker DiffT, InstaSticker PartialInstaSticker。含义是子类特有的业务字段如tagName、question必填而基类InstaSticker上的布局字段x、y、width、height、rotation等均可选有默认值。二、静态工厂方法一览文档列出的全部静态方法及其实现位置如下每种方法返回对应的贴纸类实例静态方法返回类型定义位置说明hashtag(options)HashtagStickersticker-builder.ts#L55话题贴纸必填tagName不能带#mention(options)MentionStickersticker-builder.ts#L59用户名 提及必填userIdmentionReel(mediaInfo, additional?)MentionStickersticker-builder.ts#L68Story 提及/分享他人 Story 的便捷包装location(options)LocationStickersticker-builder.ts#L82地理位置贴纸必填locationIdcountdown(options)CountdownStickersticker-builder.ts#L86倒计时贴纸必填text、endTschat(options)ChatStickersticker-builder.ts#L90Chat 贴纸必填textpoll(options)PollStickersticker-builder.ts#L94投票贴纸必填question、talliesquestion(options)QuestionStickersticker-builder.ts#L98提问贴纸必填questionquiz(options)QuizStickersticker-builder.ts#L102测验贴纸必填question、options、correctAnswerslider(options)SliderStickersticker-builder.ts#L110表情滑动条贴纸必填question、emojiattachment(options)AttachmentStickersticker-builder.ts#L119附带已有媒体帖子/Story到 StoryattachmentFromMedia(mediaInfo, additional?)AttachmentStickersticker-builder.ts#L123从媒体信息对象直接创建 attachment 的便捷包装两个便捷包装方法的细节值得展开mentionReel(mediaInfo, additional?)接收一个 StoryItem 形状的{ pk, user: { pk } }对象示例中通常来自ig.feed.userStory(username).items()返回的条目内部等价于StickerBuilder.mention({ userId: mediaInfo.user.pk.toString(), mediaId: mediaInfo.pk, displayType: mention_reshare, width: 0.7, height: 0.9, ...additional, // additional 可覆盖任意默认值 });attachmentFromMedia(mediaInfo, additional?)同理接收{ pk, user: { pk } }内部调用StickerBuilder.attachment({ mediaId: mediaInfo.pk, mediaOwnerId: mediaInfo.user.pk.toString(), ...additional })。文档特别注明The mediaId only contains the media pk. The user id is stored in mediaOwnerId.即mediaId只放媒体主键用户 id 单独存到mediaOwnerId字段中。三、InstaSticker 基类坐标系统与可链式布局方法所有贴纸都继承自抽象基类 InstaSticker它定义了贴纸的几何属性与一整套可链式调用的布局方法每个方法都返回this基类字段及默认值字段默认值含义x/y0.0贴纸中心点坐标取值范围 0..1相对 Story 画布width/height由子类设定相对尺寸0..1 区间的比例rotation0.0旋转角度度z0层叠顺序越大越靠前isStickertrue序列化时固定携带的标记字段子类必须实现两个抽象 getterid写入story_sticker_ids的标识串和key负载中对应的顶层字段名见下文build()逻辑。可链式布局方法定义于 insta-sticker.ts#L25-L69center()把x、y都设为0.5画布正中rotateDeg(deg)rotation deg % 360.0例如rotateDeg(180)旋转 180°scale(factor)width、height同时乘以factor例如scale(0.5)缩小一半moveForward(layers 1)/moveBackwards(layers 1)z加/减层级控制贴纸前后遮挡关系right()/left()x 1.0 - width / 2或x width / 2分别贴齐右/左边缘水平居中于边缘top()/bottom()y height / 2或y 1.0 - height / 2分别贴齐上/下边缘。这些方法可以任意串联例如 examples/upload-story.example.ts 注释中的StickerBuilder.hashtag({ tagName: tag }).scale(0.5).rotateDeg(90).center().left()也可以不用链式方法、直接在 options 里给出位置与尺寸StickerBuilder.hashtag({ tagName: insta, width: 0.5, height: 0.5, x: 0.5, y: 0.5 })另外基类提供additionalConfigurePropertiesgetter默认返回null仅用于附带媒体场景——例如 MentionSticker 在displayType mention_reshare时返回{ reshared_media_id: this.mediaId }AttachmentSticker 返回{ reshared_media_id: this.mediaId }这些属性会被build()合并到最终配置对象上。四、add() 与 build()从贴纸数组到私有接口负载build()sticker-builder.ts#L30-L52是 StickerBuilder 的核心把贴纸数组转换成 Instagrammedia/configure接口认识的负载。其算法按sticker.key用Map分组——同一种类型的贴纸同一个key会被归入同一组每组序列化为JSON.stringify(stickers)并通过Object.defineProperty以key为属性名挂到结果对象上例如story_hashtags: [tagName:...]...收集每个贴纸的additionalConfigureProperties用 lodash 的defaults()做浅合并不覆盖已有值从而把reshared_media_id等附加字段并入配置对象把每组的sticker.id收集进ids数组最终story_sticker_ids: ids.join(,)以英文逗号拼接。返回值类型即StickerConfig any { story_sticker_ids: string }sticker-builder.ts#L20。也就是说一个贴纸构建器最终产出类似这样的对象{ story_hashtags: [{...JSON.stringify(hashtag 贴纸)...}], story_questions: [{...}, {...}], // 多个 question 贴纸合并为同一组数组 story_sticker_ids: hashtag_sticker_vibrant,question_sticker_ama,question_sticker_ama, reshared_media_id: pk, // 来自 additionalConfigureProperties若有 }这与 src/types/media.configure-story.options.ts 中MediaConfigureStoryBaseOptions的字段一一对应story_hashtags、reel_mentions、story_polls、story_sliders、story_questions、story_countdowns、attached_media、story_chats、story_quizs注释中还给出了story_sticker_ids的取值约定如emoji_slider_{emoji}、question_sticker_ama、countdown_sticker_time、media_simple_{media_id}。每个贴纸子类的id/key组合正是为此设计例如贴纸类idkey负载字段名HashtagStickerhashtag_sticker_vibrantstory_hashtagsMentionStickermention_sticker_vibrantreel_mentionsLocationStickerlocation_sticker_vibrantstory_locationsCountdownStickercountdown_sticker_timestory_countdownsChatStickerchat_sticker_idstory_chatsPollStickerpolling_sticker_vibrantstory_pollsQuestionStickerquestion_sticker_amastory_questionsQuizStickerquiz_story_sticker_defaultstory_quizsSliderStickeremoji_slider_{emoji}由 emoji 动态生成story_slidersAttachmentStickermedia_simple_{mediaId}由 mediaId 动态生成attached_media序列化细节InstaSticker.toJSON()使用classToPlain()后套snakeCaseKeys()insta-sticker.ts#L71-L74即驼峰字段tagName、mediaOwnerId、startBackgroundColor…会被递归转成下划线格式tag_name、start_background_color…正好匹配私有接口的字段命名。MentionSticker 中的mediaId字段标注了Enumerable(false)装饰器实现见 src/decorators/enumerable.decorator.ts使该字段不参与序列化——它只用于计算additionalConfigureProperties中的reshared_media_id避免在贴纸 JSON 里出现多余的media_id键。五、与各贴纸子类的选项速览各子类的业务字段与默认值均定义在 src/sticker-builder/stickers/ 下HashtagStickerhashtag.sticker.ts必填tagName: string默认width 0.47、height 0.11。注意tag_name中#是FORBIDDEN character见 media.configure-story.options.ts#L154 注释传入时应不带#。MentionStickermention.sticker.ts必填userId: string可选displayType: mention_username | mention_reshare默认mention_username、mediaId默认width 0.64、height 0.125。LocationStickerlocation.sticker.ts必填locationId: string通常是 Facebook Place 的external_id默认width 0.47、height 0.111。CountdownStickercountdown.sticker.ts必填text、endTs。endTs的 setter 同时接受numberUnix 秒和 luxon 的DateTime内部Math.floor(value.toUTC().toSeconds())转换。可选颜色字段textColor默认#ffffff、startBackgroundColor#ca2ee1、endBackgroundColor#5eb1ff、digitColor#7e0091、digitCardColor#ffffffcc以及followingEnabled默认true默认width 0.703125、height 0.26013514。ChatStickerchat.sticker.ts必填text可选startBackgroundColor#3897f0、endBackgroundColor#27c4f5、hasStartedChatfalse默认width 0.453125、height 0.1266892。PollStickerpoll.sticker.ts必填question、tallies: [{ text, fontSize? }, { text, fontSize? }]恰好两个选项setter 会为每项补默认fontSize: 28.0。可选finishedfalse、viewerVote0、viewerCanVotetrue、isSharedResultfalse默认width 0.49934897、height 0.1266892。QuestionStickerquestion.sticker.ts必填question可选backgroundColor#ffffff、textColor#000000、profilePicUrl、questionType: text | music默认text、viewerCanInteractfalse默认width 0.7291667、height 0.28716215。QuizStickerquiz.sticker.ts必填question、options、correctAnswer正确项下标。options的 setter 同时接受string[]或Array{ text, count }纯字符串数组会自动映射为{ text, count: 0 }。可选textColor#ffffff、startBackgroundColor/endBackgroundColor#262626、viewerCanAnswerfalse、viewerAnswer-1。另外StickerBuilder.quiz()工厂会按选项数量自动计算高度height 0.11824318 options.length * 0.10304056width固定为0.7291667见 sticker-builder.ts#L102-L108传参可用...options覆盖。SliderStickerslider.sticker.ts必填question、emoji可选backgroundColor#ffffff、textColor#000000、viewerCanVotefalse、sliderVoteCount0、viewerVote-1.0、sliderVoteAverage0.0默认width 0.7291667、height 0.22212838。AttachmentStickerattachment.sticker.ts必填mediaId媒体 pk、mediaOwnerId用户 pk 的字符串形式默认width 0.8、height 0.67。颜色字段在负载里都是 hex 字符串源码注释示例#ff0a1d几何字段x、y、width、height、rotation的取值范围是 0..1 的比例见 media.configure-story.options.ts#L70-L77 中StorySticker接口注释/* range: 0..1 */。六、与 publish.story() 的集成完整可运行示例StickerBuilder的主要消费方是 src/services/publish.service.ts 的story()方法stickerConfig出现在PostingStoryOptions类型中src/types/posting.options.ts#L49类型为(any { story_sticker_ids }) | StickerBuilder即既可以直接传手工构造的配置对象也可以直接传StickerBuilder实例。story()内部会先做instanceof判断并调用build()publish.service.ts#L287-L295if (options.stickerConfig instanceof StickerBuilder) { options.stickerConfig options.stickerConfig.build(); } const configureOptions: MediaConfigureStoryBaseOptions { configure_mode: 1, ...(options.stickerConfig ? options.stickerConfig : {}), };configure_mode: 1表示普通 story-reel当请求携带recipientUsers/threadIds即发成 DM Story时会切到configure_mode: 2该模式从源码注释看不支持贴纸。build()的结果被整体展开进 configure 请求参数story_sticker_ids与各key字段story_hashtags、reel_mentions等随media/configure请求一并提交。仓库提供了覆盖全部贴纸类型的端到端示例 examples/upload-story.example.ts核心用法如下import { IgApiClient } from ../src; import { StickerBuilder } from ../src/sticker-builder; import { DateTime, Duration } from luxon; const ig new IgApiClient(); // 1. 生成设备信息并登录 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); // 2. 构建贴纸并发送 Story await ig.publish.story({ file, // 待上传的 Story 图片/视频 Buffer stickerConfig: new StickerBuilder() .add(StickerBuilder.hashtag({ tagName: insta }).center()) .add(StickerBuilder.mention({ userId: ig.state.cookieUserId }).center()) .add(StickerBuilder.question({ question: My Question }).scale(0.5)) .add(StickerBuilder.question({ question: Music?, questionType: music })) .add(StickerBuilder.countdown({ text: My Countdown, endTs: DateTime.local().plus(Duration.fromObject({ hours: 1 })), // 1 小时后结束 })) .add(StickerBuilder.chat({ text: Chat name })) .add(StickerBuilder.location({ locationId: (await ig.locationSearch.index(13, 37)).venues[0].external_id, })) .add(StickerBuilder.poll({ question: Question, tallies: [{ text: Left }, { text: Right }] })) .add(StickerBuilder.quiz({ question: Question, options: [0, 1, 2, 3], correctAnswer: 1 })) .add(StickerBuilder.slider({ question: Question, emoji: ❤ })) // 提及某用户的第一条 Storymention_reshare .add(StickerBuilder.mentionReel((await ig.feed.userStory(username).items())[0]).center()) // 附带时间线上的第一条媒体 .add(StickerBuilder.attachmentFromMedia((await ig.feed.timeline().items())[0]).center()) // 显式指定位置与尺寸 .add(StickerBuilder.hashtag({ tagName: insta, width: 0.5, height: 0.5, x: 0.5, y: 0.5 })) .build(), // 也可以不写 build()publish.story() 内部会自动调用 });示例中值得注意的取值来源locationId用ig.locationSearch.index(lat, lng)检索到的venues[0].external_idmentionReel/attachmentFromMedia的入参分别取自ig.feed.userStory(username).items()与ig.feed.timeline().items()返回的媒体项形如{ pk, user: { pk } }。七、小结与使用注意一条链路StickerBuilder.type(options)生成贴纸 → 链式布局方法调整x/y/width/height/rotation/z→add()累积 →build()或交给publish.story()自动触发产出story_sticker_ids 分组 JSON 负载 → 随media/configureconfigure_mode: 1提交同 key 合并多个同类型贴纸如两个question会被build()合并到同一个 JSON 数组字段中而story_sticker_ids会为每个实例各追加一次id覆盖默认值所有静态工厂都支持在 options 里直接写x、y、width、height等布局字段mentionReel/attachmentFromMedia还支持additional参数覆盖包装方法的默认值限制DM Storyconfigure_mode: 2路径下不使用贴纸配置story_cta链接贴纸在源码注释中标注links are only valid in business accountshashtag 的tag_name不允许带#。更多相关文档可参考 sticker-builder 模块索引 以及各贴纸类页面如 HashtagSticker、PollSticker。赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐instagram-private-api 中 AttachmentSticker 深度解析给 Story 附加媒体贴纸的构建与原理instagram private api 中 AttachmentSticker 深度解析给 Story 附加媒体贴纸的构建与原理 本篇围绕 instagr后端instagram-private-api 中 ChatSticker 聊天贴纸类详解构建并随 Story 发布的 story_chats 贴纸instagram private api 中 ChatSticker 聊天贴纸类详解构建并随 Story 发布的 story_chats 贴纸 本文以 in后端instagram-private-api 中 HashtagSticker 详解为 Instagram 快贴Story添加话题标签贴纸instagram private api 中 HashtagSticker 详解为 Instagram 快贴Story添加话题标签贴纸 本篇围绕 ins后端上一篇PostgREST 分页与计数全指南Range 请求头、limit/offset 参数与 Prefer: count 三种计数策略下一篇open-pencil FontPickerRoot 实战指南基于 Reka UI Combobox 的无头可搜索字体选择器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考