开发者中心
首页
教程
接口
社区
工具
第三方应用开发
快速入门 服务端API 客户端API 运营规范 附录 更新日志 联系我们
第三方应用开发 服务端API 素材管理 异步上传临时素材
异步上传临时素材
最后更新：2022/12/14
可联系渠道经理采购或代理智慧硬件接口已支持设备 联系渠道经理
异步上传临时素材
最后更新：2022/12/14

目录

  • 概述
  • 使用场景说明
  • 生成异步上传任务
  •       上传的媒体文件限制
  • 查询异步任务结果
  •       任务结果常见错误码列表（detail.errcode）
  • 回调异步任务结果

    • 概述

    为了满足临时素材的大文件诉求（最高支持200M），支持指定文件的CDN链接（必须支持Range分块下载），由企微微信后台异步下载和处理，处理完成后回调通知任务完成，再通过接口主动查询任务结果。

    跟普通临时素材一样，media_id仅三天内有效，media_id在同一企业内应用之间可以共享。

    使用场景说明

    跟上传临时素材拿到的media_id使用场景是不通用的，目前适配的接口如下：

    接口适用场景值(scene)说明
    获取临时素材所有若文件大小超过20M，必须使用Range分块下载且分块大小不超过20M，否则返回错误830002
    入群欢迎语素材管理1添加素材、编辑素材兼容video和file两种素材类型使用；
    获取素材返回的media_id类型则跟添加/编辑时的media_id类型对应

    生成异步上传任务

    请求方式：POST（HTTPS）
    请求地址：https://qyapi.weixin.qq.com/cgi-bin/media/upload_by_url?access_token=ACCESS_TOKEN

    请求包体

    {
    "scene": 1,
    "type": "video",
    "filename": "video.mp4",
    "url": "https://xxxx",
    "md5": "MD5"
}

    参数说明：

    参数类型必须说明
    access_tokenstring是调用接口凭证
    sceneuint32是场景值。1-客户联系入群欢迎语素材（目前仅支持1）。
    注意：每个场景值有对应的使用范围，详见上面的「使用场景说明」
    typestring是媒体文件类型。目前仅支持video-视频，file-普通文件
    不超过32字节。
    filenamestring是文件名，标识文件展示的名称。比如，使用该media_id发消息时，展示的文件名由该字段控制。
    不超过128字节。
    urlstring是文件cdn url。url要求支持Range分块下载
    不超过1024字节。
    如果为腾讯云cos链接，则需要设置为「公有读」权限。
    md5string是文件md5。对比从url下载下来的文件md5是否一致。
    不超过32字节。

     

    权限说明：

    • 客户联系权限

     

    返回数据：

    {
   "errcode": 0,
   "errmsg": "ok",
   "jobid": "jobid"
}

    参数说明：

    参数说明
    jobid任务id。可通过此jobid查询结果

    上传的媒体文件限制

    所有文件size必须大于5个字节

    • 图片（image）：暂不支持
    • 语音（voice） ：暂不支持
    • 视频（video） ：200MB，仅支持MP4格式
    • 普通文件（file）：200MB

     

    查询异步任务结果

    请求方式：POST（HTTPS）
    请求地址：https://qyapi.weixin.qq.com/cgi-bin/media/get_upload_by_url_result?access_token=ACCESS_TOKEN

    请求包体

    {
    "jobid": "JOBID"
}

    参数说明：

    参数类型必须说明
    access_tokenstring是调用接口凭证
    jobidstring是任务id。最长为128字节，60分钟内有效

     

    权限说明：

    • 客户联系权限

     

    返回结果:

    {
    "errcode": 0,
    "errmsg": "ok",
    "status": 2,
    "detail": {
        "errcode": 0,
        "errmsg": "ok",
        "media_id": "3*1*G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0",
        "created_at": "1380000000"
    }
}

    参数说明:

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述
    statusstring任务状态。1-处理中，2-完成，3-异常失败
    detailobj结果明细
    detail.errcodeint32任务失败返回码。当status为3时返回非0，其他返回0
    detail.errmsgstring任务失败错误码描述
    detail.media_idstring媒体文件上传后获取的唯一标识，3天内有效。当status为2时返回。
    detail.created_atstring媒体文件创建的时间戳。当status为2时返回。

     

    任务结果常见错误码列表（detail.errcode）

    错误码错误说明排查方法
    830001url非法确认url是否支持Range分块下载
    830003url下载数据失败确认url本身是否能正常访问
    45001文件大小超过限制确认文件在5字节~200M范围内
    301019文件MD5不匹配确认url对应的文件内容md5，跟所填的md5参数是否一致

     

    回调异步任务结果

    当异步上传任务完成时，将任务完成的通知（不包含具体的结果）回调到提交任务的应用配置的回调地址。

    事件示例：

    <xml>
	<ToUserName><![CDATA[wx28dbb14e3720FAKE]]></ToUserName>
	<FromUserName><![CDATA[sys]]></FromUserName>
	<CreateTime>1425284517</CreateTime>
	<MsgType><![CDATA[event]]></MsgType>
	<Event><![CDATA[upload_media_job_finish]]></Event>
	<JobId><![CDATA[jobid_S0MrnndvRG5fadSlLwiBqiDDbM143UqTmKP3152FZk4]]></JobId>
</xml>

    参数说明：

    参数说明
    ToUserName企业微信CorpID
    FromUserName此时固定为sys
    CreateTime消息创建时间，unix时间戳
    MsgType消息类型，此时固定为event
    Event事件类型，此时固定为upload_media_job_finish
    JobId异步任务id
    上一篇
    获取高清语音素材
    下一篇
    服务商上传临时素材