后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载DirectThreadBroadcastPhotoOptions是 instagram-private-apiNodeJS Instagram 私有 API SDKTypeScript 编写中用于「向私信会话Direct Thread发送图片」的选项接口。本文将围绕该接口的三个属性展开结合 类型定义源码、DirectThreadEntity 调用链、UploadRepository 上传实现 与 官方示例帮助读者理解每个参数的含义、可选性、底层去向并掌握从登录、获取会话到发送图片的完整可运行流程。一、接口总览这个选项对象用来做什么DirectThreadBroadcastPhotoOptions在文档中被定义为位于 types 模块 下的一个 Interface其定义文件为 src/types/direct-thread.broadcast-media.options.ts源码原文如下export interface DirectThreadBroadcastPhotoOptions { file: Buffer; allowFullAspectRatio?: boolean; uploadId?: string; }它作为DirectThreadEntity.broadcastPhoto(options)方法的唯一入参使用见 DirectThreadEntity 类文档。也就是说开发者想通过 SDK 给某个私信会话发送一张图片时需要构造一个满足该接口形状的对象交给broadcastPhotoSDK 会依次完成「图片上传」和「会话消息广播」两步操作。三个属性中只有file是必填项其余两个均为可选TypeScript 的可选属性标记为?。下表概括三个属性的核心信息属性类型必填含义与去向fileBuffer是图片的二进制内容直接传给上传接口uploadIdstring否自定义上传 ID缺省时由 SDK 用时间戳生成allowFullAspectRatioboolean否是否允许完整宽高比默认按true处理二、参数逐个拆解2.1file: Buffer必填图片二进制内容file是整张图片的原始字节数据。在 broadcastPhoto 实现 中它被原样转发给上传仓库public async broadcastPhoto(options: DirectThreadBroadcastPhotoOptions) { const { upload_id } await this.client.upload.photo({ uploadId: options.uploadId, file: options.file, }); // ... }从实际使用场景看file通常由 Node.js 的fs.readFile读取本地图片得到官方示例 examples/dm-thrad.broadast-media.example.ts 即是如此async function sendPhoto(thread: DirectThreadEntity) { const photo: Buffer await readFileAsync(PATH_TO_PHOTO.jpg); console.log(await thread.broadcastPhoto({ file: photo, })); }在底层上传实现 UploadRepository.photo 中options.file.byteLength会被写入X-Entity-Length请求头同时整个 Buffer 作为 POST 请求体发送到/rupload_igphoto/{name}端点。因此传入的 Buffer 应当为完整的 JPEG 图片数据X-Entity-Type固定为image/jpeg而非经过切割的分片。2.2uploadId: string可选自定义上传标识uploadId用于标识这一次上传事务。如果不提供上传仓库会自行兜底const uploadId options.uploadId || Date.now();即默认取当前毫秒时间戳。随后生成的图片上传名称由三部分组成源码const name ${uploadId}_0_${random(1000000000, 9999999999)};即{uploadId}_0_{随机数}其中随机数来自lodash的random(1000000000, 9999999999)。这个upload_id会同时写入X-Instagram-Rupload-Params请求头中的upload_id字段createPhotoRuploadParams并作为configure_photo广播消息表单里的upload_id字段提交给服务端见下文调用链。使用建议如果你需要将「上传」与「广播」绑定为同一事务例如日志追踪、失败重试时需要保持同一个 uploadId可以显式传入自己的 ID否则完全可以让 SDK 自动生成保持缺省即可。2.3allowFullAspectRatio: boolean可选是否允许完整宽高比该参数控制发送的图片是否允许以完整宽高比展示。在 broadcastPhoto 中它的默认行为值得注意——代码里使用了||逻辑而非??return await this.broadcast({ item: configure_photo, form: { allow_full_aspect_ratio: options.allowFullAspectRatio || true, upload_id, }, });也就是说即使调用方显式传入allowFullAspectRatio: false由于false || true的结果为true最终提交给服务端的allow_full_aspect_ratio依然是true只有调用方省略该字段或传入true时结果同样为true。从源码结构可以推断当前版本下该选项实际上总是以true生效若希望发送被裁剪即非完整宽高比的图片需要关注后续版本是否将该逻辑调整为??。三、完整调用链从 Buffer 到私信中的图片理解接口的作用最好落到broadcastPhoto的两段式执行流程上。整个链路涉及三个文件上传阶段DirectThreadEntity.broadcastPhoto调用client.upload.photo(...)即 UploadRepository.photo以media_type: 1图片类型执行/rupload_igphoto/{name}的 POST 上传得到响应对象中的upload_id。广播阶段SDK 使用item: configure_photo调用私信广播接口见 DirectThreadRepository.broadcast请求POST /api/v1/direct_v2/threads/broadcast/configure_photo/表单中包含action: send_item、client_context、mutation_token、_csrftoken、device_id、_uuid以及携带图片upload_id的自定义表单。返回阶段广播成功后返回 DirectThreadRepositoryBroadcastResponseRootObjectbroadcastPhoto的返回值类型为PromiseDirectThreadRepositoryBroadcastResponseRootObject | DirectThreadRepositoryBroadcastResponsePayload详见 DirectThreadEntity.broadcastPhoto 文档。流程示意本地图片文件 │ fs.readFile → Buffer ▼ thread.broadcastPhoto({ file, uploadId?, allowFullAspectRatio? }) │ ① client.upload.photo() → /rupload_igphoto/{uploadId}_0_{rand} │ ② broadcast({item:configure_photo, form:{upload_id, allow_full_aspect_ratio}}) ▼ POST /api/v1/direct_v2/threads/broadcast/configure_photo/ ▼ DirectThreadRepositoryBroadcastResponseRootObject / Payload另外broadcastPhoto最终通过DirectThreadEntity私有方法broadcast源码决定接收方若实体持有threadId则提交threadIds否则提交userIds并且调用方未设置接收方时会抛出DirectThread: No recipients set错误。广播成功后实体还会把响应的thread_id写回自身、清空userIds。四、同文件中的兄弟接口避免混淆DirectThreadBroadcastPhotoOptions所在的 direct-thread.broadcast-media.options.ts 还定义了其他几个会话媒体选项容易与本文主题混淆这里做区分接口用途关键字段DirectThreadBroadcastPhotoOptions发送普通图片到会话file、uploadId?、allowFullAspectRatio?DirectThreadBroadcastVideoOptions发送视频到会话video、uploadId?、sampled?、transcodeDelay?DirectThreadBroadcastStoryOptions会话内 Story 的公共选项viewMode?、replyType?、uploadId?DirectThreadBroadcastPhotoStoryOptions发送图片版 Story直通 PublishService继承 Story 选项并追加fileDirectThreadBroadcastVideoStoryOptions发送视频版 Story直通 PublishService继承 Story 选项并追加video、coverImageDirectThreadBroadcastVoiceOptions发送语音消息file、waveform?、uploadId?、transcodeDelay?注意broadcastStory与broadcastPhoto是两条不同的路径——前者直接调用client.publish.story见 direct-thread.entity.ts#L195-L217后者走的是上传 configure_photo广播二者不要混用。五、实战从登录到发送图片的最小完整示例结合 官方示例 与 DirectInboxFeed一个可运行的完整流程如下import { IgApiClient, DirectThreadEntity } from instagram-private-api; import { promisify } from util; import { readFile } from fs; const readFileAsync promisify(readFile); const ig new IgApiClient(); (async () { // 1. 生成设备信息并登录 ig.state.generateDevice(process.env.IG_USERNAME); await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD); // 2. 获取收件箱中的第一个会话实体records() 返回 DirectThreadEntity[] const [thread] await ig.feed.directInbox().records(); // 3. 读取本地图片并以 Buffer 发送 const photo: Buffer await readFileAsync(PATH_TO_PHOTO.jpg); const result await thread.broadcastPhoto({ file: photo, // uploadId: custom-id, // 可选自定义上传 ID // allowFullAspectRatio: true, // 可选当前版本下恒为 true }); console.log(result); })();其中获取会话实体有两种常见来源收件箱ig.feed.directInbox().records()返回DirectThreadEntity[]见 direct-inbox.feed.ts指定会话使用ig.entity.directThread(threadId)见 entity.factory.ts。六、小结DirectThreadBroadcastPhotoOptions是 instagram-private-api 中「私信发图」这一功能的类型入口file是必填的图片 Buffer直接决定上传内容uploadId可选缺省由Date.now()兜底并参与生成/rupload_igphoto/的上传名称allowFullAspectRatio可选但在当前 broadcastPhoto 实现 中因|| true逻辑而恒为true这是阅读源码时最需要注意的坑。接口虽小却是理解 SDK「上传UploadRepository→ 广播DirectThreadRepository→ 响应解析」三段式设计的绝佳切入点。想要继续深入可以对照阅读 direct-thread.broadcast.options.ts广播基础选项使用XOR约束 threadIds/userIds 二选一以及 broadcast 响应类型。赞分享后端【免费下载链接】instagram-private-apiNodeJS Instagram private API SDK. Written in TypeScript.项目地址https://gitcode.com/gh_mirrors/in/instagram-private-api点击查看免费下载相关推荐instagram-private-api 中 IgtvBrowseFeedResponseCandidatesItem 接口详解IGTV 浏览流的图片候选解析instagram private api 中 IgtvBrowseFeedResponseCandidatesItem 接口详解IGTV 浏览流的图片候选解后端Instagram私有API终极指南instagram-private-api完整入门教程Instagram私有API终极指南instagram private api完整入门教程 想要完全掌控你的Instagram账户操作吗 instagr后端instagram-private-api 中 TopicalExploreFeedResponseCandidatesItem 接口详解Instagram 话题探索流图片候选响应结构instagram private api 中 TopicalExploreFeedResponseCandidatesItem 接口详解Instagram后端上一篇如何用5分钟快速掌握SQL代码检查专业开发者的终极指南下一篇终极SQL代码检查指南如何用sql-lint告别数据库开发中的低级错误创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考