---
url: "https://pay.weixin.qq.com/doc/v3/merchant/4012557248.md"
title: "图片上传（营销专用）"
doc_id: 4012557248
---

>更新时间：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 使用该域名将访问异地的接入点，指引[点击查看](https://pay.weixin.qq.com/doc/v3/merchant/4012075113.md)

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考[签名认证](https://pay.weixin.qq.com/doc/v3/merchant/4012365342.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D)生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
| Content-Type | string | true | 请设置为 `multipart/form-data` |
### Body 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| file | file | true | 将媒体图片进行二进制转换，得到的媒体图片二进制内容，在请求body中上传此二进制内容。媒体图片只支持JPG、BMP、PNG格式，文件大小不能超过2M。 |
| meta | object | true | 媒体文件元信息，使用json表示，包含两个对象：filename、sha256。 |
| meta.filename | string(128) | true | 【文件名称】商户上传的媒体图片的名称，商户自定义，必须以JPG、BMP、PNG为后缀。 |
| meta.sha256 | string(256) | true | 【文件摘要】图片文件的文件摘要，即对图片文件的二进制内容进行sha256计算得到的值。 |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| media_url | string(256) | true | 【媒体文件URL地址】微信返回的媒体文件标识url。有效期为永久 |
## 请求步骤

### 图片上传步骤

#### 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" }

待签名串示例：

```
POST
/v3/marketing/favor/media/image-upload
1566987169           //时间戳
12ced2db6f0193dda91ba86224ea1cd8   //随机数
{"filename":"filea.jpg","sha256":"hjkahkjsjkfsjk78687dhjahdajhk"}
```

#### 3. 添加HTTP头

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

#### 4. 添加body

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

注意

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

#### 5.发送请求

```
POST /v3/marketing/favor/media/image-upload HTTP/1.1
Host: api.mch.weixin.qq.com
Authorization: WECHATPAY2-SHA256-RSA2048
mchid="1900231671",nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",
timestamp="1567067659",
serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7
SFR+BjDZh689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPN
Q7dBLO7ux6MoSuQp69PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e
7hwUbDwGln170ZXomoO1KpQSbw3f1uWUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M
7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
Content-Type: multipart/form-data;boundary=boundary
--boundary
Content-Disposition: form-data; name="meta";
Content-Type: application/json
{ "filename": "filea.jpg", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk" }
--boundary
Content-Disposition: form-data; name="file"; filename="filea.jpg";
Content-Type: image/jpg
pic1
--boundary--
```

## 错误码

### 公共错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 [接口规则](https://pay.weixin.qq.com/doc/v3/merchant/4012081709.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/v3/merchant/4012072670.md) |
| 500 | SYSTEM\_ERROR | 系统异常，请稍后重试 | 请稍后重试 |

### 业务错误码

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

请求示例

> POST

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

应答示例

> 200 OK

```
{
  "media_url" : "https://qpic.cn/xxx"
}

```
