企业官网建设流程全解析

• 后端

本篇技术指南围绕 instagram-private-api（NodeJS/TypeScript 编写的 Instagram 私有 API SDK）中视频发布链路的关键响应类型MediaRepositoryConfigureVideoResponseRootObject，系统讲解其字段结构、嵌套类型、生成时机与底层调用链。读完本文，你将掌握视频 configure 响应的完整数据模型，并能在ig.publish.video()或ig.media.configureVideo()返回结果中准确提取媒体信息、判断发布结果，从而构建可靠的视频发布与校验逻辑。

一、接口定位：视频 configure 响应的顶层容器

在 instagram-private-api 的响应模型体系中，MediaRepositoryConfigureVideoResponseRootObject是对 Instagram 服务端/api/v1/media/configure/（视频模式）返回 JSON 的 TypeScript 类型化描述。它定义在 src/responses/media.repository.configure-video.response.ts，并通过 src/responses/index.ts 统一导出，供全仓库引用。

该接口只有三个顶层字段，结构非常精简：

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

文档中该接口归属responses模块（见 docs/modules/responses.md 接口清单中的MediaRepositoryConfigureVideoResponseRootObject条目），同一响应文件中还依次声明了Media、Image_versions2、CandidatesItem、User、Usertags、InItem、Fb_user_tags等嵌套接口，共同构成一棵完整的响应数据树。

二、核心字段详解：media 对象的数据模型

media字段是响应主体，其类型MediaRepositoryConfigureVideoResponseMedia（接口文档，源码见 src/responses/media.repository.configure-video.response.ts）包含了视频帖子被 Instagram 收录后的全部元数据，可按用途划分为以下几组。

2.1 媒体标识与时间戳

2.2 媒体类型与画面信息

image_versions2只含一个candidates数组（Image_versions2 文档），每个CandidatesItem（接口文档）描述一张封面缩略图：

export interface MediaRepositoryConfigureVideoResponseCandidatesItem { width: number; // 缩略图宽度 height: number; // 缩略图高度 url: string; // 可访问的 CDN 地址 estimated_scans_sizes: number[]; // 各渐进式扫描层预估大小（用于渐进式加载） }

取第一个 candidate 的url即可获得帖子封面，这是发布后立即生成可视化预览的常用手段。

2.3 作者信息：user 对象

user字段（接口文档）描述当前发布账号：

2.4 交互与评论配置

2.5 标签类信息

Usertags（接口文档）中的每个InItem（接口文档）结构为：

export interface MediaRepositoryConfigureVideoResponseInItem { user: MediaRepositoryConfigureVideoResponseUser; // 被标记的用户 position: number[]; // 标记在画面上的归一化坐标 start_time_in_video_in_sec: null; // 视频中出现起始秒数（本场景为 null） duration_in_video_in_sec: null; // 视频中持续秒数（本场景为 null） }

Fb_user_tags（接口文档）则只含in: any[]，说明该字段在本 SDK 中未做进一步类型化。

三、底层调用链：响应从何而来

MediaRepositoryConfigureVideoResponseRootObject是视频发布“configure（配置）阶段”的产物。从源码可以还原完整调用链（参见 examples/upload-video.example.ts）：

1. 入口：ig.publish.video({ video, coverImage, caption, usertags, location })（PublishService.video）。
2. 上传：依次完成视频分段/整段上传、封面图上传、media.uploadFinish()收尾（含source_type: '4'与video.length）。
3. configure：this.client.media.configureVideo(configureOptions)最终发出POST /api/v1/media/configure/?video=1请求（见 MediaRepository.configureVideo），其form通过this.client.request.sign(form)签名后提交。
4. 返回：请求响应体body即对应本接口所描述的 JSON 结构。

configureVideo内部通过applyConfigureDefaults为表单补充默认值（media.repository.ts）：自动注入_csrftoken、_uid、_uuid、device等签名必需字段，并填充timezone_offset、date_time_original、caption、source_type: '4'、filter_type: '0'、audio_muted: false、poster_frame_index: 0等默认项；若传入了usertags或location，则会先序列化为 JSON 字符串再随表单发送，与响应中的Usertags结构一一对应。

配置入参类型定义在 src/types/media.configure-video.options.ts（MediaConfigureTimelineVideoOptions），可选字段包括filter_type、timezone_offset、usertags、location、source_type、device_id、caption、date_time_original等。

细节提示：在 src/responses/media.repository.configure-video.response.ts 中同时声明了MediaRepositoryConfigureResponseRootObject与MediaRepositoryConfigureVideoResponseRootObject两个顶层接口，二者结构相同；repository 方法当前的返回类型标注为前者，文档侧则记录了后者。使用时两者可按相同结构对待。

四、错误处理与状态判断

发布阶段若失败，PublishService.video做了多层防护（publish.service.ts）：

• 上传阶段错误包装为IgUploadVideoError（src/errors/ig-upload-video-error.ts），携带响应体与视频信息。
• 遇到 HTTP 202（转码待完成）时，catchTranscodeError会按options.transcodeDelay（默认 5000ms）等待后重试（publish.service.ts）。
• configure 阶段最多重试 6 次（指数退避(i+1)*2秒）；超过次数或收到>= 400状态码时抛出IgConfigureVideoError（src/errors/ig-configure-video-error.ts）。

因此在业务代码中，拿到MediaRepositoryConfigureVideoResponseRootObject后，建议按以下顺序校验：

1. 检查status === 'ok'，否则视为发布未成功；
2. 读取media.pk/media.id拼接完整 mediaId，用于后续ig.media.info()、ig.media.delete()等操作；
3. 从media.image_versions2.candidates[0].url取封面图，从media.code构造帖子短链接。

五、完整示例：发布视频并解析响应

参考 examples/upload-video.example.ts，可写出如下端到端用法：

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'), // MP4 Buffer coverImage: await readFileAsync('./myVideoCover.jpg'), // 封面图 Buffer caption: 'posted via instagram-private-api', // 亦支持 usertags、location，参见 upload-photo.example.ts }); // publishResult 即 MediaRepositoryConfigureVideoResponseRootObject 对应结构 if (publishResult.status !== 'ok') { throw new Error('video configure failed'); } console.log('mediaId =', publishResult.media.pk, '/', publishResult.media.id); console.log('short code =', publishResult.media.code); console.log('cover url =', publishResult.media.image_versions2.candidates[0].url); console.log('upload_id =', publishResult.upload_id); })();

六、总结

MediaRepositoryConfigureVideoResponseRootObject是 instagram-private-api 视频发布链路中 configure 阶段的响应契约，以极简的三字段（media/upload_id/status）承载完整的视频帖元数据。其嵌套结构——Media、Image_versions2、CandidatesItem、User、Usertags、InItem、Fb_user_tags——与上传表单的参数设计相互呼应（如usertags表单字段对应响应中的Usertags.in）。理解这一数据模型，配合 PublishService 的重试与错误包装机制，即可在自动化发布、内容归档、封面预览等场景中稳健地处理视频发布结果。更多响应类型可查阅 docs/modules/responses.md 索引继续深入。

• 后端