后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载本篇技术指南聚焦 instagram-private-apiNodeJS Instagram Private API SDKTypeScript 编写中StorySticker这一核心接口它是所有 Story 故事贴纸话题、投票、提问、倒计时、测验、滑块、聊天、提及、地点、附带媒体等 10 种共有的几何基座统一以归一化坐标x、y与归一化尺寸width、height以及角度rotation描述贴纸在 1080×1920 故事画布上的位置、大小与旋转。读完本文你将掌握该接口的完整字段语义、继承层级、与StickerBuilder链式 API 的对应关系以及从配置参数到/api/v1/media/configure_to_story/请求的底层序列化链路能够直接在ig.publish.story()中编写精确可控的贴纸布局代码。一、接口概览与源码位置StorySticker定义于类型声明文件 src/types/media.configure-story.options.ts其原始定义只有五个数值属性源码第 71-77 行/* range: 0..1 */ export interface StorySticker { x: number; y: number; width: number; height: number; rotation: number; }从 TypeDoc 生成的接口文档 docs/interfaces/types/StorySticker.md 可以看到该接口在types模块命名空间下全部属性均为number类型并在文档中逐一标注了其在源码中的精确行号属性类型源码行号语义xnumbersrc/types/media.configure-story.options.ts:72贴纸中心点的归一化横坐标ynumbersrc/types/media.configure-story.options.ts:73贴纸中心点的归一化纵坐标widthnumbersrc/types/media.configure-story.options.ts:74贴纸的归一化宽度heightnumbersrc/types/media.configure-story.options.ts:75贴纸的归一化高度rotationnumbersrc/types/media.configure-story.options.ts:76贴纸的旋转角度单位度接口上方的/* range: 0..1 */注释明确给出了取值边界x、y、width、height都是 0 到 1 之间的归一化数值relative unitsInstagram 客户端会按照故事画布的实际像素尺寸典型 1080×1920等比换算。而rotation单位为角度degree默认值0.0典型范围 0–360。二、继承层级10 种贴纸共用的几何基座StorySticker是整个故事贴纸类型体系的根接口。根据 StorySticker.md 的 Hierarchy 章节以下 10 个接口全部直接继承自它StorySticker基座x / y / width / height / rotation ├── StoryChat ├── StoryAttachedMedia ├── StoryCountdown ├── StoryQuestion ├── StorySlider ├── StoryPoll ├── StoryMention ├── StoryLocation ├── StoryHashtag └── StoryQuiz这意味着无论你使用哪一种贴纸都必须提供或由StickerBuilder提供默认值x、y、width、height、rotation这五个几何字段各子接口只在其上追加自己的业务字段。各子接口的详细定义均可在此处查阅StoryChat、StoryAttachedMedia、StoryCountdown、StoryQuestion、StorySlider、StoryPoll、StoryMention、StoryLocation、StoryHashtag、StoryQuiz。以 StoryChat 为例它继承StorySticker后追加了text、start_background_color、end_background_color、has_started_chat、is_sticker等字段而其x/y/width/height/rotation全部标注为 Inherited from StorySticker——这正是几何基座 业务扩展设计模式的直接体现。三、字段语义详解归一化坐标与旋转3.1 坐标与尺寸x / y / width / heightInstagram 故事画布的坐标系统以贴纸中心点为锚点画布左上角为原点右下角为(1, 1)x 0.5、y 0.5表示贴纸中心恰好位于画布正中央width 0.5表示贴纸宽度为画布宽度的 50%以画布宽度为基准归一化height 0.5表示贴纸高度为画布高度的 50%以画布高度为基准归一化。从源码注释与各贴纸默认值可以交叉验证这一语义例如 countdown.sticker.ts 中倒计时贴纸默认width 0.703125、height 0.26013514即约占画布宽度 70%、高度 26%hashtag.sticker.ts 中话题贴纸默认width 0.47、height 0.11poll.sticker.ts 中投票贴纸默认width 0.49934897、height 0.1266892。这些默认尺寸都是 Instagram 客户端实际渲染时的标准比例直接手动指定值时建议参考这些量级。另外注意源码中有两处关于宽高比aspect-ratio的注释media.configure-story.options.ts:103StoryQuestion// ig takes height as aspect-ratio——对于提问贴纸Instagram 会把height视作宽高比参与计算media.configure-story.options.ts:128StoryPoll// width height have an aspect-ratio (takes height)——投票贴纸同理。也就是说部分贴纸类型对width/height的解释并非严格意义上的绝对尺寸而是会被客户端按宽高比换算手动调整尺寸时需要留意这一点。3.2 旋转rotationrotation以度为单位默认值0.0。在 insta-sticker.ts 基类中旋转通过rotateDeg(deg)设置并做了取模归一化public rotateDeg(deg: number): this { this.rotation deg % 360.0; return this; }rotation 180即旋转 180°上下颠倒rotation 90为顺时针旋转 90°。由于取模运算rotateDeg(540)与rotateDeg(180)等价。四、坐标系统在 StickerBuilder 中的落地StorySticker的五个字段是贴纸布局的原始语言而 StickerBuilder 基于 InstaSticker 抽象基类提供了一套链式定位 API把归一化坐标的计算封装成了可读性更强的方法。基类源码insta-sticker.ts中默认值与定位方法如下export abstract class InstaSticker { public width: number; public height: number; public rotation: number 0.0; public x: number 0.0; public y: number 0.0; public z: number 0; ... public center() { this.x 0.5; this.y 0.5; return this; } // 居中 public rotateDeg(d) { this.rotation d % 360.0; return this; } // 旋转 public scale(f) { this.width * f; this.height * f; return this; } // 等比缩放 public right() { this.x 1.0 - this.width / 2; return this; } // 贴右 public left() { this.x this.width / 2; return this; } // 贴左 public top() { this.y this.height / 2; return this; } // 贴顶 public bottom() { this.y 1.0 - this.height / 2; return this; } // 贴底 }注意right()/left()/top()/bottom()的实现细节因为x/y锚定的是贴纸中心所以贴右时需要用1.0 - width/2让贴纸边缘与画布边缘对齐而非直接令x 1。居中则直接取画布中点(0.5, 0.5)。z层级用于控制贴纸前后遮挡关系moveForward()/moveBackwards()分别增减层级但注意z并不属于StorySticker接口的五个字段。StickerBuilder的构建流程sticker-builder.ts会把贴纸按键分组后JSON.stringify并汇总生成story_sticker_idspublic build(): StickerConfig { // 按 sticker.key 分组如 story_hashtags / story_polls / story_questions ... // 每组序列化为 JSON 字符串写入对应 key // 收集每个贴纸的 id 拼成 story_sticker_ids逗号分隔 return { ...defaults({}, ...additionalProperties), ...result, story_sticker_ids: ids.join(,), }; }因此手写StorySticker风格对象与使用StickerBuilder是同一套几何数据模型的两条路径最终都会落入MediaConfigureStoryBaseOptions中对应的story_hashtags、story_polls、story_questions、story_countdowns、story_sliders、story_chats、story_quizs、reel_mentions、story_locations、attached_media等字段。五、两种使用方式与完整示例5.1 方式一手写 StorySticker 对象面向 configure 选项PostingStoryOptionssrc/types/posting.options.ts允许直接传入贴纸对象。例如给ig.publish.story()传入一个居中、宽 50% 高 11% 的话题贴纸import { IgApiClient } from instagram-private-api; import { readFile } from fs; const ig new IgApiClient(); 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, caption: hello insta, hashtags: [ { tag_name: insta, // 注意# 是被禁止的字符无需携带 x: 0.5, // 居中 y: 0.5, width: 0.47, // 参考默认宽 height: 0.11, // 参考默认高 rotation: 0, use_custom_title: false, is_sticker: true, }, ], });这里的x/y/width/height/rotation就是StorySticker的五个字段StoryHashtag在此基础上追加tag_name、use_custom_title、is_sticker。源码注释还特别强调#是话题贴纸中的禁用字符media.configure-story.options.ts:154同时PublishService.story()会自动把tag_name中的#剥除并补写进 captionpublish.service.ts:322-336。5.2 方式二StickerBuilder 链式 API推荐仓库官方示例 examples/upload-story.example.ts 展示了完整的推荐写法通过StickerBuilder创建贴纸并用链式方法布局最后整体作为stickerConfig传入await ig.publish.story({ file, 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.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: ❤ })) .add(StickerBuilder.hashtag({ tagName: insta, width: 0.5, height: 0.5, x: 0.5, y: 0.5 })) .build(), });示例注释upload-story.example.ts:23-45系统罗列了可用的布局方法全部链式可组合例如StickerBuilder.hashtag({ tagName: tag }).scale(0.5).rotateDeg(90).center().left()。同时也可以直接显式指定几何值width: 0.5, height: 0.5, x: 0.5, y: 0.5——这正是StorySticker字段的直接映射。各贴纸构建器的默认尺寸与id最终进入story_sticker_ids可以在 src/sticker-builder/stickers 目录下逐一查看例如贴纸默认 width默认 heightstory_sticker_ids 中的 idHashtagSticker0.470.11hashtag_sticker_vibrantQuestionSticker0.72916670.28716215question_sticker_amaCountdownSticker0.7031250.26013514countdown_sticker_timePollSticker0.499348970.1266892polling_sticker_vibrantQuizSticker0.72916670.11824318 options.length * 0.10304056按选项数动态计算由 sticker-builder.ts 自动生成六、从 StorySticker 到服务端完整序列化链路了解StorySticker字段如何抵达 Instagram 服务端有助于排查贴纸不显示或位置错误的问题。整条调用链如下构建贴纸对象StorySticker的 5 个几何字段 子接口业务字段传入ig.publish.story()汇总PublishService.story() 将各贴纸写入MediaConfigureStoryBaseOptions的对应字段并把story_sticker_ids拼接为逗号分隔字符串同时把configure_mode置为1story-reel 模式支持贴纸或2direct-story 模式不支持贴纸media.configure-story.options.ts:8 注释明确说明序列化MediaRepository.stringifyStoryStickers 对story_hashtags、story_locations、reel_mentions、story_polls、story_sliders、story_questions、story_countdowns、attached_media、story_cta、story_chats、story_quizs逐一执行JSON.stringify仅当是数组且首元素非字符串时上传配置configureToStory() 走POST /api/v1/media/configure_to_story/照片默认画布回退为 1520×2048width options.width || 1520、height options.height || 2048edits.crop_original_size等裁剪参数一并携带视频走 configureToStoryVideo()。值得注意configure_mode 2direct-story发给指定私信时stringifyStoryStickers不会执行贴纸字段保持原样——这印证了direct-story 不支持贴纸的源码注释。另外PostingStoryOptions中stickerConfig字段类型为(any { story_sticker_ids }) | StickerBuilderPublishService.story()会在开头检测stickerConfig instanceof StickerBuilder若是则先调用.build()展开publish.service.ts:287-295。七、注意事项与实战建议综合源码注释与实现使用StorySticker系贴纸时有以下几点需要特别留意取值范围x/y/width/height严格处于0..1归一化区间rotation单位为度。超范围的值可能导致贴纸被裁剪或客户端渲染异常。# 字符StoryHashtag.tag_name中禁止出现#SDK 会替你把多余的#剥除并同步进 captionpublish.service.ts:322-336。部分贴纸的宽高按宽高比解释StoryQuestion与StoryPoll的注释均提示 Instagram 实际按 aspect-ratio 处理media.configure-story.options.ts:103、:128手动调尺寸时建议参考各贴纸默认值。颜色字段均为十六进制倒计时、提问、滑块、测验等贴纸的*_color字段要求#ff0a1d形式的 hex 值例如 StoryCountdown 的注释StickerBuilder的对应贴纸类已给出合理的默认配色如倒计时默认#ca2ee1 → #5eb1ff渐变。direct-story 不支持贴纸当threadIds/recipientUsers被设置时configure_mode切为2贴纸序列化被跳过media.repository.ts:441-448。附带的媒体贴纸StoryAttachedMedia的media_id只包含媒体 pkStickerBuilder.attachmentFromMedia()会从媒体对象中提取pk与user.pk自动补全sticker-builder.ts:123-132。综上所述StorySticker虽只有 5 个字段却是整个故事贴纸体系的坐标基石理解其归一化坐标语义、StickerBuilder的链式定位实现以及最终的 JSON 序列化路径即可在 instagram-private-api 中精确复刻或超越 App 端的贴纸布局效果。赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐instagram-private-api 中 ReelsMediaFeedResponsePollSticker 接口详解解析 Instagram 故事投票贴纸数据instagram private api 中 ReelsMediaFeedResponsePollSticker 接口详解解析 Instagram 故事投票后端instagram-private-api 中 ReelsTrayFeedResponseStoryQuizsItem 接口全解析从故事问答贴纸的读取、发布到答题instagram private api 中 ReelsTrayFeedResponseStoryQuizsItem 接口全解析从故事问答贴纸的读取、发布到后端instagram-private-api 故事问题贴纸回答者信息接口 StoryQuestionResponsesFeedResponseResponder_info 完全解析instagram private api 故事问题贴纸回答者信息接口 StoryQuestionResponsesFeedResponseResponder_后端上一篇GPU分子动力学模拟的终极指南GPUMD深度解析与实战配置下一篇WandB vs MLflow如何选择最适合你的机器学习实验跟踪工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考