Back to Details

wecomcli-media

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

企业微信媒体文件

WeCom Media Files

执行任何 
wecom-cli
命令前，必须先读取并完成 
wecomcli-shared
技能的公共前置检查。
资源型 skill，负责基于 
media_id
下载媒体文件到本地，以及把本地文件上传为 
media_id
。是其他技能（微盘、邮件等）处理 
media_id
相关操作的基础依赖：
upload
会产出新的 
media_id
，但本 skill 不负责搜索/发现其他业务场景中已存在的 
media_id
（如邮件附件、微盘文件的 
media_id
由对应业务技能产出），也不解析文件内容。
Before executing any 
wecom-cli
command, you must first read and complete the common pre-checks of the 
wecomcli-shared
skill.
A resource-type skill responsible for downloading media files to local based on 
media_id
and uploading local files to generate 
media_id
. It is a basic dependency for other skills (such as WeCom Disk, Email, etc.) to handle 
media_id
-related operations: 
upload
will generate a new 
media_id
, but this skill does not search/discover existing 
media_id
in other business scenarios (e.g., 
media_id
of email attachments or WeCom Disk files are generated by corresponding business skills), nor does it parse file content.

适用范围

Scope of Application

适用

Applicable Scenarios

  • 根据其他技能或用户提供的 
    media_id
    下载媒体文件到本地
  • 上传本地文件（本地路径已知）获取 
    media_id
    ，供其他技能后续使用（如微盘上传素材）
  • Download media files to local based on 
    media_id
    provided by other skills or users
  • Upload local files (with known local path) to obtain 
    media_id
    for subsequent use by other skills (such as uploading materials to WeCom Disk)

不适用

Inapplicable Scenarios

  • 解析/识别文件内容（正文提取、OCR、看图问答、PDF/Word/Excel 解析等） → 本 skill 只负责把文件下载到本地拿 
    file_path
    ，如需查看内容请直接通过 
    file_path
    读取该本地文件
  • 搜索/发现其他业务场景中已存在的 
    media_id
    （如邮件附件、微盘文件列表/搜索等） → 由对应业务技能负责产出并返回 
    media_id
    ，本 skill 只接收已有的 
    media_id
    做下载；本地文件转
    media_id
    的场景仍走本 skill 的 
    upload
  • 编造或猜测 
    media_id
    / 本地文件路径 → 两者必须来自其他技能返回或用户明确提供，禁止自行构造
  • Parse/identify file content (text extraction, OCR, image Q&A, PDF/Word/Excel parsing, etc.) → This skill only downloads files to local to get 
    file_path
    . If you need to view the content, please directly read the local file via 
    file_path
  • Search/discover existing 
    media_id
    in other business scenarios (such as email attachments, WeCom Disk file list/search, etc.) → Corresponding business skills are responsible for generating and returning 
    media_id
    . This skill only accepts existing 
    media_id
    for download; for converting local files to 
    media_id
    , still use the 
    upload
    function of this skill
  • Fabricate or guess 
    media_id
    / local file path → Both must come from other skills' returns or be clearly provided by users. Fabrication is prohibited

接口详述

Interface Details

下载媒体文件

Download Media File

根据 
media_id
下载媒体文件到本地，返回本地文件路径。
命令
bash
wecom-cli media download --json '{"media_id": "MEDIA_ID"}'
入参
字段类型必填说明
media_id
string是文件的 
media_id
，由上传文件后获得，或由其他技能（邮件附件/内嵌图片等）返回
返回
字段类型说明
file_path
string下载成功后的本地文件路径
使用规则
  • 下载完成后如需查看文件内容，直接通过 
    file_path
    读取该本地文件。
  • 下载失败时返回错误码和错误信息。
  • media_id
    必须是真正的 media_id，不接受任何形式的 URL    ：若拿到的是一个链接（如 
    attach_url
    、正文里的图片/附件链接），不要把这个 URL 当作 
    media_id
    传入本接口，会直接报错。尤其是命中 
    work.weixin.qq.com/filepreview/security/
    特征的防泄漏加密链接，属于加密的、与用户身份绑定的资源，本接口无法下载或解密，应直接告知用户该文件受防泄漏策略保护，引导其点击链接、在企业微信客户端内打开查看/保存，不要尝试用本接口或其他手段绕过。
Download media files to local based on 
media_id
and return the local file path.
Command
bash
wecom-cli media download --json '{"media_id": "MEDIA_ID"}'
Input Parameters
FieldTypeRequiredDescription
media_id
stringYes
media_id
of the file, obtained after file upload or returned by other skills (such as email attachments/embedded images, etc.)
Return
FieldTypeDescription
file_path
stringLocal file path after successful download
Usage Rules
  • If you need to view the file content after download, directly read the local file via 
    file_path
    .
  • Return error code and error message when download fails.
  • media_id
    must be a real media_id, no URLs of any form are accepted    : If you get a link (such as 
    attach_url
    , image/attachment link in the text), do not pass this URL as 
    media_id
    to this interface, as it will directly report an error. Especially for anti-leakage encrypted links with the feature 
    work.weixin.qq.com/filepreview/security/
    , which are encrypted resources bound to user identity, this interface cannot download or decrypt them. You should directly inform the user that the file is protected by anti-leakage policies, guide them to click the link and open/view/save it in the WeCom client, and do not attempt to bypass it using this interface or other means.

上传媒体文件

Upload Media File

将本地文件上传，获取 
media_id
。
命令
bash
wecom-cli media upload --json '{"file_path": "/tmp/example.pdf"}'
入参
字段类型必填说明
file_path
string是需要上传的文件的本地路径
返回
字段类型说明
type
string媒体类型：
image
(图片)/
voice
(语音)/
video
(视频)/
file
(文件)
media_id
string上传后的 
media_id
，供其他技能后续使用（如微盘
upload
的 
file_content_media
）
created_at
string创建时间，格式：
YYYY-MM-DD HH:mm:ss
Upload local files to obtain 
media_id
.
Command
bash
wecom-cli media upload --json '{"file_path": "/tmp/example.pdf"}'
Input Parameters
FieldTypeRequiredDescription
file_path
stringYesLocal path of the file to be uploaded
Return
FieldTypeDescription
type
stringMedia type: 
image
(image)/
voice
(voice)/
video
(video)/
file
(file)
media_id
string
media_id
after upload, for subsequent use by other skills (such as 
file_content_media
for WeCom Disk 
upload
)
created_at
stringCreation time, format: 
YYYY-MM-DD HH:mm:ss

关键约束

Key Constraints

  • media_id
    / 
    file_path
    不得编造    ：
    media_id
    必须来自上传结果、其他技能返回或用户明确提供；
    file_path
    必须是真实存在的本地路径。两者都没有时用自然语言追问，禁止靠猜测凑一个。
  • 不做内容解析：本 skill 只负责文件的下载落地与上传，
    download
    拿到 
    file_path
    后如需查看内容，直接通过 
    file_path
    读取，不在本 skill 职责范围内。
  • 内部 ID 不外露：
    media_id
    仅用于后续接口调用，禁止直接展示给用户；下载后的本地 
    file_path
    同样不展示给用户。
  • CLI 报错原样转达：命令返回明确错误码时如实告知用户并给替代建议，禁止用 curl / python 等通用手段绕过 CLI 强行完成。
  • media_id
    / 
    file_path
    cannot be fabricated    : 
    media_id
    must come from upload results, other skills' returns or be clearly provided by users; 
    file_path
    must be a real existing local path. If neither is available, ask the user clearly in natural language, do not guess.
  • No content parsing: This skill only handles file download and upload. After obtaining 
    file_path
    via 
    download
    , if you need to view the content, directly read it via 
    file_path
    , which is not within the scope of this skill.
  • Internal ID not exposed: 
    media_id
    is only used for subsequent interface calls, and it is prohibited to directly display it to users; the local 
    file_path
    after download is also not displayed to users.
  • Convey CLI errors as is: When the command returns a clear error code, inform the user truthfully and provide alternative suggestions. Do not use general methods such as curl / python to bypass the CLI to force completion.

跨技能依赖

Cross-Skill Dependencies

依赖场景说明
wecomcli-email
邮件附件/内嵌图片的 
media_id
，使用本 skill 的 
download
下载到本地后通过 
file_path
读取
wecomcli-disk
上传文件到微盘时若已有 
media_id
，直接作为 
disk files upload
的 
file_content_media
使用，无需再走本 skill；若只有本地路径且需要先转成 
media_id
，可用本 skill 的 
upload
参数缺失 / 意图不明确时，用自然语言追问让用户明确，不要瞎猜。
Dependency ScenarioDescription
wecomcli-email
For 
media_id
of email attachments/embedded images, use the 
download
function of this skill to download to local and read via 
file_path
wecomcli-disk
When uploading files to WeCom Disk, if 
media_id
already exists, directly use it as 
file_content_media
for 
disk files upload
without using this skill; if only local path is available and needs to be converted to 
media_id
first, use the 
upload
function of this skill
When parameters are missing / intent is unclear, ask the user clearly in natural language, do not guess.