图片上传（营销专用）

更新时间：2024.09.20

通过本接口上传图片后可获得图片url地址。图片url可在微信支付营销相关的API使用，包括商家券、代金券、支付有礼等。

接口频率：100/min

接口说明

支持商户：【普通商户】

请求方式：【POST】/v3/marketing/favor/media/image-upload

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

Content-Type 　必填　string

请设置为multipart/form-data

body 包体参数

file 　必填 file

将媒体图片进行二进制转换，得到的媒体图片二进制内容，在请求body中上传此二进制内容。媒体图片只支持JPG、BMP、PNG格式，文件大小不能超过2M。

meta 　必填 object

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

属性

JAVA详细请求示例见：wechatpay-apache-httpclient

PHP详细请求示例见：wechatpay-guzzle-middleware

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/favor/media/image-upload \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: multipart/form-data" \
6  -F file=@"/path/to/file" \
7  -F meta="{
8    "filename" : "example_filename",
9    "sha256" : "example_sha256"
10  }"

应答参数

200 OK

media_url 　必填 string(256)

【媒体文件URL地址】微信返回的媒体文件标识url。有效期为永久

应答示例

200 OK

1{
2  "media_url" : "https://qpic.cn/xxx"
3}
4

请求步骤

图片上传步骤

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

例如： POST https://api.mch.weixin.qq.com/v3/marketing/favor/media/image-upload HTTP/1.1

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

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

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

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

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

filename参数获取方式说明：

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

sha256参数获取方式说明：

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

2.3. 签名计算说明：

签名生成

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

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

待签名串示例：

1POST
2/v3/marketing/favor/media/image-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/marketing/favor/media/image-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--boundary  
14Content-Disposition: form-data; name="meta";
15Content-Type: application/json
16{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
17--boundary
18Content-Disposition: form-data; name="file"; filename="filea.jpg";
19Content-Type: image/jpg
20pic1
21--boundary--

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	图片文件为空	商户更换文件后，重新调用
403	REQUEST_BLOCKED	未知图片类型	图片类型必须为JPG、BMP、PNG
403	REQUEST_BLOCKED	图片meta信息不一致	请检查meta信息是否正确
403	REQUEST_BLOCKED	签名信息不匹配	请检查签名信息

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服