上传图片

更新时间：2025.02.20

通过 POST 表单来调用该接口，表单媒体文件 id 为 media，需有 filename、filelength、content-type 等信息。

接口说明

适用对象：直连模式机构模式

请求URL：https://apihk.mch.weixin.qq.com/secapi/mch/uploadmedia

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

请求方式：POST

是否需要证书：是，详见证书使用

请求参数

参数名	变量	类型[长度限制]	必填	描述
商户号	mch_id	string[1,32]	是	微信支付分配的商户号示例值：1000000000
媒体文件	media	string[1,256]	是	form-data中媒体文件标识，有filename、filelength、content-type等信息。支持 jpeg、jpg、bmp、png 格式，图片大小不超过2M。不参与签名计算示例值：test.jpg
媒体文件内容hash值	media_hash	string[1,32]	是	根据媒体文件内容进行MD5计算后的值，注意小写示例值：hjkahkjsjkfsjk78687dhjahdajhk
签名	sign	string[1,32]	是	通过签名算法计算得出的签名值，详见签名生成算法示例值：D675A1E471DBF7C0B1AC5883B5BDA9EF
签名方式	sign_type	string[1,10]	否	HMAC-SHA256加密方式，其他或者不填为MD5方式示例值：HMAC-SHA256

请求示例

1curl --cert ./apiclient_cert.pem --key ./apiclient_key.pem -F 'mch_id=1000000000' -F 'media_hash=709d1e858d2ef9d0501cc053668b2872' -F 'sign=D675A1E471DBF7C0B1AC5883B5BDA9EF' -F 'media=@test.jpg' https://api.mch.weixin.qq.com/secapi/mch/uploadmedia

返回参数

参数名	变量	类型[长度限制]	必填	描述
返回状态码	return_code	string[1,16]	是	SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看trade_state来判断示例值：SUCCESS
返回信息	return_msg	string[1,128]	是	返回信息，如非空，为错误原因，签名失败，参数格式校验错误示例值：签名失败

以下字段在return_code为SUCCESS的时候有返回

参数名	变量	类型[长度限制]	必填	描述
业务结果	result_code	string[1,32]	是	SUCCESS/FAIL 示例值：FAIL
媒体标识Id	media_id	string[1,256]	是	微信返回的媒体文件标识Id 示例值：9UYfXi- WMUhgWXvJtEw4_gBl e_EfrD_pIL0bS8GAsK8
签名	sign	string[1,32]	是	微信返回的签名,详见签名生成算法示例值：pIL0bS8GAsKpIL0bS8GAsKpIL0bS8GAs
错误代码	err_code	string[1,32]	否	错误代码示例值：INVALID_REQUEST
错误代码描述	err_code_de s	string[1,128]	否	结果信息描述示例值：商户号信息有误，请检查修改后重试

返回示例

1<xml> 
2<return_code><![CDATA[SUCCESS]]></return_code> 
3<return_msg><![CDATA[OK]]></return_msg> 
4<result_code><![CDATA[SUCCESS]]></result_code> 
5<media_id><![CDATA[9UYfXi- WMUhgWXvJtEw4_gBle_EfrD_pIL0bS8GAsK8]]></media_id>
6<sign><![CDATA[D675A1E471DBF7C0B1AC5883B5BDA9EF]]></sign> 
7</xml>

错误码

状态码	错误码	描述	解决方案
NVALID_REQUEST	不支持http get 方法	请使用post 方法，请检查后重新提交	检查输入参数
INVALID_REQUEST	xml格式错误	xml参数格式错误，请检查后重新提交	参数格式错误，请检查后重新提交
SIGNERROR	验签错误	签名校验失败，请检查后重试	签名校验失败，请检查后重试
INVALID_REQUEST	需要证书	获取客户端证书序列号失败获取客户端证书特征名称(DN)域失败证书校验失败，请检查后重试	检查证书
PARAM_ERROR	参数错误	参数填写有误，请检查后重试	人工检查过滤
PARAM_ERROR	图片文件错误	图片格式不正确，请检查后重新提交图片大小不能超过2M，请检查后重新提交图片Hash 值有误，请检查后重新提交	检查图片
PARAM_ERROR	商户号错误	商户号mchid 有误，请检查后重试	检查商户号是否正确
INVALID_REQUEST	调用权限	暂无权限，请检查后重试	检查权限
FREQUENCY_LIMITED	频率限制	操作过快，请稍后重试	放慢上传频率
SYSTEMERROR	上传图片失败	上传图片失败，请稍后重试	联系微信支付客服