图片上传

更新时间:2023.08.16

部分微信支付业务指定商户需要使用图片上传 API来上报图片信息,从而获得必传参数的值:图片MediaID 。

# 接口说明

支持商户:
【普通服务商】
请求方式:
【POST】/v3/merchant/media/upload
请求域名:
【主域名】
https://api.mch.weixin.qq.com
使用该域名将访问就近的接入点
【备域名】
https://api2.mch.weixin.qq.com
使用该域名将访问异地的接入点 ,指引点击查看

请求主体类型: multipart/form-data

# 字段说明

# 请求参数

    Body 包体参数
  • file 必填 message
    【图片文件】 将媒体图片进行二进制转换,得到的媒体图片二进制内容,在请求body中上传此二进制内容。媒体图片只支持JPG、BMP、PNG格式,文件大小不能超过2M。
  • meta 必填 Object
    【】 媒体文件元信息,使用json表示,包含两个对象:filename、sha256。
    • 属性

# 应答字段

    200OK
  • media_id 必填 string(512)
    【媒体文件标识ID】 微信返回的媒体文件标识ID。

请求示例

示例代码

JAVA详细请求示例见:wechatpay-apache-httpclient (opens new window)

PHP详细请求示例见:wechatpay-guzzle-middleware (opens new window)

应答示例

200 OK

# 请求步骤

# 图片上传步骤

# 1. 创建一个POST的方法请求/upload URI

例如: POST https://api.mch.weixin.qq.com/v3/merchant/media/upload HTTP/1.1

# 2. 将文件的数据添加到请求主体

2.1. 图片文件file参数的获取方式说明:

媒体图片二进制内容,放在请求HTTP的body中。

2.2. 媒体文件元信息meta参数的获取方式说明:

媒体文件元信息,使用json表示,包含两个对象:filename、sha256。

  • filename参数获取方式说明:

商户上传的媒体图片的名称,商户自定义,必须以JPG、BMP、PNG为后缀。

  • sha256参数获取方式说明:

图片文件的文件摘要,即对图片文件的二进制内容进行sha256计算得到的值。

2.3. 签名计算说明:

签名生成 (opens new window)

参与签名计算的请求主体为meta的json串:

{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }

待签名串示例:

1POST
2/v3/merchant/media/upload
31566987169 //时间戳
412ced2db6f0193dda91ba86224ea1cd8 //随机数
5{"filename":"filea.jpg","sha256":"hjkahkjsjkfsjk78687dhjahdajhk"}

# 3. 添加HTTP头

1Content-Type:multipart/form-data.设置为要上载的对象的MIME媒体类型。
2Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900231671",
3nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",timestamp="1567067659",
4serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
5signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7SFR+BjDZh6
689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPNQ7dBLO7ux6MoSuQp69
7PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e7hwUbDwGln170ZXomoO1KpQSbw3f1u
8WUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
9Content-Type: multipart/form-data;boundary=boundary

# 4. 添加body

1// 以下为body的内容
2--boundary // boundary为商户自定义的一个字符串
3Content-Disposition: form-data; name="meta";
4Content-Type: application/json
5//此处必须有一个空行
6{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
7--boundary
8Content-Disposition: form-data; name="file"; filename="filea.jpg";
9Content-Type: image/jpg
10//此处必须有一个空行
11pic1 //pic1即为媒体图片的二进制内容
12--boundary--

注意

请求包体每行结尾都需要包含\r\n(空行也需要)。

# 5.发送请求

1POST /v3/merchant/media/upload HTTP/1.1
2Host: api.mch.weixin.qq.com
3Authorization: WECHATPAY2-SHA256-RSA2048
4mchid="1900231671",nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",
5timestamp="1567067659",
6serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
7signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7
8SFR+BjDZh689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPN
9Q7dBLO7ux6MoSuQp69PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e
107hwUbDwGln170ZXomoO1KpQSbw3f1uWUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M
117aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
12Content-Type: multipart/form-data;boundary=boundary
13
14--boundary
15Content-Disposition: form-data; name="meta";
16Content-Type: application/json
17
18{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
19--boundary
20Content-Disposition: form-data; name="file"; filename="filea.jpg";
21Content-Type: image/jpg
22
23pic1
24--boundary--

# 错误码

状态码 错误码 描述 解决方案
500 SYSTEM_ERROR 系统错误 系统异常,请使用相同参数稍后重新调用
500 SYSTEM_ERROR 文件系统错误,请稍后重试 文件系统异常,请使用相同参数稍后重新调用
400 PARAM_ERROR 图片文件名称不正确,请检查后重新提交 图片文件名称不正确,只支持jpg,jpeg,png,bmp,请使用正确图片文件重新调用
400 PARAM_ERROR 文件二进制内容不是图片,请检查后重新提交 上传文件二进制内容头部不正确,只支持jpg,jpeg,png,bmp,请使用正确图片文件重新调用
400 PARAM_ERROR 图片sha256值有误,请检查后重新提交 图片sha256值计算有误,请检查算法,重新计算后提交
400 PARAM_ERROR 文件大小不能超过2M,请检查后重新提交 商户更换文件或者对图片进行压缩后,重新调用
400 PARAM_ERROR 文件为空,请检查后重新提交 商户更换文件后,重新调用
429 FREQUENCY_LIMIT_EXCEED 操作过快,请稍后重试 请商户降低每秒调用频率
429 FREQUENCY_LIMIT_EXCEED 当天上传文件数已达上限 请商户降低每天调用频率
403 NO_AUTH 商户权限异常 请确认是否已经开通相关权限
反馈
咨询
目录