• 后端

在 instagram-private-api（TypeScript 编写的 NodeJS Instagram 私有 API SDK）中，每一次视频发布最终都会走到/api/v1/media/configure/配置接口，并由服务器返回一个结构完整的根对象。MediaRepositoryConfigureVideoResponseFb_user_tags正是该响应树中描述"Facebook 用户标记（fb_user_tags）"信息的叶子接口。本篇技术指南将围绕该接口的定义、它在视频发布调用链中的位置、与普通用户标记（usertags）的区别，以及在实际开发中如何消费这些字段展开深入讲解。读完本文，你将能够准确理解该响应类型的设计动机，并能在自己的发布脚本中正确处理与判断返回数据。

接口定义：一个字段的完整画像

依据仓库中自动生成的接口文档 MediaRepositoryConfigureVideoResponseFb_user_tags.md，该接口位于 responses 模块命名空间之下，只包含一个属性：

export interface MediaRepositoryConfigureVideoResponseFb_user_tags { in: any[]; }

• in: any[]：必选字段。语义上表示"被标记进这条内容里的实体集合"。在与之配套的普通用户标记接口中，in数组中的每个元素都携带user（被标记用户）与position（标记位置坐标），但此处刻意声明为any[]，意味着 SDK 并未对 Facebook 标记的条目做进一步的结构化建模。
• 定义位置：该接口在 src/responses/media.repository.configure-video.response.ts 第 70～72 行定义，属于视频配置（configure video）响应族。

文档同时给出了接口所属模块的导航：responses 模块、根入口 README。这也提示我们：该接口不是孤立存在的，而是整个 responses 类型体系的一部分——Instagram 私有 API 的每个端点响应都在仓库中有对应的 TypeScript 接口，供 SDK 使用者获得完整的类型提示。

视频发布：从上传到 configure 的完整调用链

要真正理解这个响应接口的价值，需要先看清它在发布流程中的位置。视频发布并非一步到位，而是"上传 → 封面图 → finish → configure"的多阶段流程，核心逻辑位于 src/services/publish.service.ts 的PublishService.video()方法（第 154～209 行）：

1. 初始化视频上传：调用upload.initVideo走 RUpload 分段上传协议（regularVideo，第 456～469 行）；
2. 上传封面图：this.client.upload.photo({ file: options.coverImage, uploadId })（第 167～170 行）；
3. 通知转码完成：this.client.media.uploadFinish({ upload_id, source_type: '4', video: { length } })，若服务器返回202 Accepted（转码 pending），SDK 会按transcodeDelay（默认 5000ms，见第 178 行）等待后重试；
4. 正式配置：组装MediaConfigureTimelineVideoOptions（含upload_id、caption、length、width、height、clips、可选的location与usertags，第 180～193 行），随后调用this.client.media.configureVideo(configureOptions)（第 201 行）。

最后一次调用会进入 src/repositories/media.repository.ts 的configureVideo()方法（第 365～399 行）。该方法向POST /api/v1/media/configure/（带qs: { video: '1' }标识视频类型）发送签名表单，并声明返回类型为MediaRepositoryConfigureResponseRootObject——而根对象的media字段类型正是MediaRepositoryConfigureVideoResponseMedia，其中就包含fb_user_tags属性。

也就是说，当你的代码拿到publishResult（即根对象）时，可以经由publishResult.media.fb_user_tags.in访问本接口所描述的字段。

响应树全景：fb_user_tags 在其中的位置

从源码 src/responses/media.repository.configure-video.response.ts 可以看出，视频 configure 响应的完整类型树如下：

export interface MediaRepositoryConfigureVideoResponseRootObject { media: MediaRepositoryConfigureVideoResponseMedia; upload_id: string; status: string; }

MediaRepositoryConfigureVideoResponseMedia是响应中信息最丰富的部分，其字段包括：

可以看到fb_user_tags与usertags相邻出现，二者共同构成了"这条媒体标记了谁"的完整信息。开发者解析publishResult.media时，可将fb_user_tags.in是否为空数组作为"该内容是否关联了 Facebook 实体"的判据。

fb_user_tags 与 usertags：两种标记体系的对比

这是理解本接口的关键。在同一份响应文件里，Instagram 站内标记被建模为结构化的接口：

export interface MediaRepositoryConfigureVideoResponseUsertags { in: MediaRepositoryConfigureVideoResponseInItem[]; } export interface MediaRepositoryConfigureVideoResponseInItem { user: MediaRepositoryConfigureVideoResponseUser; position: number[]; // 标记在图上的位置 start_time_in_video_in_sec: null; // 视频场景预留字段 duration_in_video_in_sec: null; // 视频场景预留字段 }

而MediaRepositoryConfigureVideoResponseFb_user_tags仅保留in: any[]。对比二者可以得出以下结论：

• 结构层级一致：两者都采用{ in: [...] }的包裹形式，说明 Instagram 内部对两类标记使用了统一的响应容器；
• 细粒度不同：站内标记被完整建模（用户、坐标、视频时间段），而 Facebook 标记未建模——SDK 作者选择any[]，从源码结构看，这是为了保持类型定义的简洁，同时避免对 Facebook 侧不稳定的字段结构做过度承诺；
• 使用场景不同：usertags是开发者通过publish.video({ usertags: { in: [{ user_id, position }] } })主动写入的（类型定义见 src/types/posting.options.ts），而fb_user_tags通常由 Instagram 在联动 Facebook 账号（如跨平台分享、Facebook 好友标记）时回填。

fb_user_tags 在项目其他响应中的分布

搜索整个src目录可以发现，fb_user_tags并非视频配置响应独有，它广泛出现在其他媒体响应类型中，进一步印证了这是 Instagram 媒体对象上的通用字段：

• src/responses/media.repository.configure.response.ts：照片 configure 响应（MediaRepositoryConfigureResponseFb_user_tags，同样为in: any[]）；
• src/responses/media.repository.configure-sidecar.response.ts：相册 configure 响应，且轮播子媒体也带可选的fb_user_tags（第 46 行）；
• src/responses/list-reel-media-viewer.feed.response.ts：Reel 媒体 viewer 响应；
• src/responses/user.feed.response.ts：用户 Feed 中的媒体（此处为可选字段fb_user_tags?）；
• src/responses/highlights.repository.edit-reel.response.ts：快拍精选编辑响应；
• src/responses/direct-thread.repository.approve-participant-request.response.ts：私信线程媒体。

从这些分布可以看出，凡是涉及媒体（photo / video / carousel / reel）的响应，Instagram 都可能返回fb_user_tags字段，因此 SDK 中所有相关响应接口都为其保留了类型位置。这为开发者提供了统一的访问入口：例如在 examples/upload-video.example.ts 这类示例的基础上，发布成功后即可通过publishResult.media.fb_user_tags检查跨平台标记情况。

实际使用：在发布脚本中消费该字段

结合 examples/upload-video.example.ts 展示的标准登录与发布流程，一个消费fb_user_tags的完整示例可以这样组织：

import { IgApiClient } from '../src'; import { readFile } from 'fs'; import { promisify } from 'util'; const readFileAsync = promisify(readFile); const ig = new IgApiClient(); async function login() { 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); } (async () => { await login(); const publishResult = await ig.publish.video({ video: await readFileAsync('./myVideo.mp4'), coverImage: await readFileAsync('./myVideoCover.jpg'), caption: 'Hello from instagram-private-api', }); // 根对象 -> media -> fb_user_tags const fbUserTags = publishResult.media.fb_user_tags; console.log('fb_user_tags.in:', fbUserTags.in); // 与站内标记对比：usertags 是有结构的 console.log('usertags.in:', publishResult.media.usertags.in); console.log('status:', publishResult.status, 'upload_id:', publishResult.upload_id); })();

其中publishResult的类型即MediaRepositoryConfigureResponseRootObject（configureVideo方法声明返回该类型，见 src/repositories/media.repository.ts），publishResult.media.fb_user_tags就是我们本文讨论的MediaRepositoryConfigureVideoResponseFb_user_tags实例。由于in是any[]，在进一步处理每个元素前，建议先对元素结构做运行时校验或按实际响应进行类型收缩。

设计意图与使用边界

综合文档与源码，可以对MediaRepositoryConfigureVideoResponseFb_user_tags的设计做出如下判断：

1. 它是"存在性标记"而非"完整业务模型"：SDK 通过in: any[]确保响应中可能出现 FB 标记时不会破坏类型结构，但不承诺字段细节——这与 Instagram 私有 API 逆向工程的现实相符：Facebook 联动字段在不同账号类型、不同客户端版本下结构差异较大；
2. 不要依赖该字段做核心业务判断：由于元素类型未建模，若你的业务需要依赖"是否标记了 Facebook 用户"或"标记了哪些人"，建议同时参考usertags与媒体详情接口，并在实际账号环境（需关联 Facebook 账号）下验证返回结构；
3. 字段可能缺席：在部分响应类型（如 src/responses/user.feed.response.ts）中fb_user_tags被声明为可选（?），说明 Instagram 并非对所有媒体都返回该字段，代码中应做好 undefined 防护。

总而言之，MediaRepositoryConfigureVideoResponseFb_user_tags虽然只有一个字段，却是理解 instagram-private-api 响应建模哲学的绝佳切片：它展示了 SDK 如何用最少的类型承诺覆盖不确定的服务器行为，同时也为开发者明确划出了"已建模"与"未建模"的边界。掌握它，意味着你在解析视频发布结果时将不再困惑于fb_user_tags这个陌生的键名。

• 后端