图片上传（营销专用）

更新时间：2024.11.18

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

接口说明

支持商户：【普通服务商】

请求方式：【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 　必填 message

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

meta 　必填 object

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

属性

请求示例

示例代码

1String filePath = "/your/home/hellokitty.png";
2URI uri = new URI("https://api.mch.weixin.qq.com/v3/marketing/favor/media/image-upload");
3File file = new File(filePath);
4try (FileInputStream ins1 = new FileInputStream(file)) { 
5  String sha256 = DigestUtils.sha256Hex(ins1);
6  try (InputStream ins2 = new FileInputStream(file)) {
7    HttpPost request = new WechatPayUploadHttpPost.Builder(uri)
8        .withImage(file.getName(), sha256, ins2)
9        .build();
10    CloseableHttpResponse response1 = httpClient.execute(request);
11  }
12}

PHP

1// 参考上述指引说明，并引入 `MediaUtil` 正常初始化，无额外条件
2use WechatPay\GuzzleMiddleware\Util\MediaUtil;
3// 实例化一个媒体文件流，注意文件后缀名需符合接口要求
4$media = new MediaUtil('/your/file/path/with.extension');
5// 正常使用Guzzle发起API请求
6try {
7    $resp = $client->request('POST', 'https://api.mch.weixin.qq.com/v3/marketing/favor/media/image-upload', [
8        'body'    => $media->getStream(),
9        'headers' => [
10            'Accept'       => 'application/json',
11            'content-type' => $media->getContentType(),
12        ]
13    ]);
14    // POST 语法糖
15    $resp = $client->post('merchant/media/upload', [
16        'body'    => $media->getStream(),
17        'headers' => [
18            'Accept'       => 'application/json',
19            'content-type' => $media->getContentType(),
20        ]
21    ]);
22    echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
23    echo $resp->getBody()."\n";
24} catch (Exception $e) {
25    echo $e->getMessage()."\n";
26    if ($e->hasResponse()) {
27        echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
28        echo $e->getResponse()->getBody();
29    }
30    return;
31}

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

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

应答参数

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版)开发者社区微信开放平台微信公众平台腾讯客服