提交图片生成任务
更新时间:2026.01.26根据指定类型生成对应商品券图片,生成结果将通过回调方式告知,或可通过主动查询接口获取生成结果。
接口说明
支持商户:【品牌商户】
请求方式:【POST】/brand/marketing/product-coupon/image-generation-tasks
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
接口限频:10/秒(品牌ID维度)
请求参数
折叠全部参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
Wechatpay-Serial 必填 string
【微信支付公钥ID】 请传入brand_id对应的微信支付公钥ID,接口将会校验两者的关联关系,参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥: 1、接收到接口的返回内容,需要使用微信支付公钥进行验签; 2、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引。
body 包体参数
task_id 必填 string
【图片生成的任务ID】 品牌创建图片生成任务的请求流水号,品牌侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间
image_generation_type 必填 string
【图片生成类型】 图片生成类型
可选取值
COMBINE_IMAGE: 适合全场类优惠头图,将品牌元素与商品券优惠等信息拼接生成头图CUT_OUT: 适合单品类优惠头图,用于去除图片背景,保留商品主体
combine_image 选填 object
【拼图数据】 当 image_generation_type 为 COMBINE_IMAGE 时,必填
| 属性 | |||||||||||||
scope 必填 string 【优惠范围】 商品券的优惠范围 可选取值
type 必填 string 【商品券类型】 商品券的优惠类型 可选取值
usage_mode 必填 string 【使用模式】 商品券使用模式,当前仅支持 可选取值
normal_coupon 选填 object 【满减券使用规则】 当且仅当
discount_coupon 选填 object 【折扣券使用规则】 当且仅当
exchange_coupon 选填 object 【兑换券使用规则】 当且仅当
background_color 选填 string 【背景颜色色值】 指定背景色(要求6字节Hex描述以#开头),用于指定拼图品牌色 |
cut_out 选填 object
【生成商品图数据】 当 image_generation_type 为 CUT_OUT 时,必填
| 属性 | |
image_url 必填 string 【图片URL】 填写待处理的图片URL,仅支持储存在https://wxpaylogo.qpic.cn域名的图片 |
请求示例
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/brand/marketing/product-coupon/image-generation-tasks \ 3 -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \ 4 -H "Accept: application/json" \ 5 -H "Wechatpay-Serial: PUB_KEY_ID_XXXX" \ 6 -H "Content-Type: application/json" \ 7 -d '{ 8 "task_id" : "image_generation_task_1", 9 "image_generation_type" : "COMBINE_IMAGE", 10 "combine_image" : { 11 "scope" : "ALL", 12 "type" : "NORMAL", 13 "usage_mode" : "SINGLE", 14 "normal_coupon" : { 15 "threshold" : 10000, 16 "discount_amount" : 100 17 }, 18 "discount_coupon" : { 19 "threshold" : 10000, 20 "percent_off" : 30 21 }, 22 "exchange_coupon" : { 23 "threshold" : 10000, 24 "exchange_price" : 100 25 }, 26 "background_color" : "#ff5733" 27 }, 28 "cut_out" : { 29 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/example.jpg" 30 } 31 }' 32
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayBrandUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/brand/4015826861 4 5import com.google.gson.annotations.SerializedName; 6import com.google.gson.annotations.Expose; 7import okhttp3.MediaType; 8import okhttp3.OkHttpClient; 9import okhttp3.Request; 10import okhttp3.RequestBody; 11import okhttp3.Response; 12 13import java.io.IOException; 14import java.io.UncheckedIOException; 15import java.security.PrivateKey; 16import java.security.PublicKey; 17import java.util.ArrayList; 18import java.util.HashMap; 19import java.util.List; 20import java.util.Map; 21 22/** 23 * 提交图片生成任务 24 */ 25public class SubmitImageGenerationTask { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/brand/marketing/product-coupon/image-generation-tasks"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 32 SubmitImageGenerationTask client = new SubmitImageGenerationTask( 33 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 34 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 35 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 SubmitImageGenerationTaskRequest request = new SubmitImageGenerationTaskRequest(); 41 request.taskId = "image_generation_task_1"; 42 request.imageGenerationType = ImageGenerationType.COMBINE_IMAGE; 43 request.combineImage = new CombineImage(); 44 request.combineImage.scope = ProductCouponScope.ALL; 45 request.combineImage.type = ProductCouponType.NORMAL; 46 request.combineImage.usageMode = UsageMode.SINGLE; 47 request.combineImage.normalCoupon = new NormalCouponUsageRule(); 48 request.combineImage.normalCoupon.threshold = 10000L; 49 request.combineImage.normalCoupon.discountAmount = 100L; 50 request.combineImage.discountCoupon = new DiscountCouponUsageRule(); 51 request.combineImage.discountCoupon.threshold = 10000L; 52 request.combineImage.discountCoupon.percentOff = 30L; 53 request.combineImage.exchangeCoupon = new ExchangeCouponUsageRule(); 54 request.combineImage.exchangeCoupon.threshold = 10000L; 55 request.combineImage.exchangeCoupon.exchangePrice = 100L; 56 request.combineImage.backgroundColor = "#ff5733"; 57 request.cutOut = new CutOut(); 58 request.cutOut.imageUrl = "https://wxpaylogo.qpic.cn/wxpaylogo/example.jpg"; 59 try { 60 SubmitImageGenerationTaskResponse response = client.run(request); 61 // TODO: 请求成功,继续业务逻辑 62 System.out.println(response); 63 } catch (WXPayBrandUtility.ApiException e) { 64 // TODO: 请求失败,根据状态码执行不同的逻辑 65 e.printStackTrace(); 66 } 67 } 68 69 public SubmitImageGenerationTaskResponse run(SubmitImageGenerationTaskRequest request) { 70 String uri = PATH; 71 String reqBody = WXPayBrandUtility.toJson(request); 72 73 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 74 reqBuilder.addHeader("Accept", "application/json"); 75 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 76 reqBuilder.addHeader("Authorization", WXPayBrandUtility.buildAuthorization(brand_id, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 77 reqBuilder.addHeader("Content-Type", "application/json"); 78 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 79 reqBuilder.method(METHOD, requestBody); 80 Request httpRequest = reqBuilder.build(); 81 82 // 发送HTTP请求 83 OkHttpClient client = new OkHttpClient.Builder().build(); 84 try (Response httpResponse = client.newCall(httpRequest).execute()) { 85 String respBody = WXPayBrandUtility.extractBody(httpResponse); 86 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 87 // 2XX 成功,验证应答签名 88 WXPayBrandUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 89 httpResponse.headers(), respBody); 90 91 // 从HTTP应答报文构建返回数据 92 return WXPayBrandUtility.fromJson(respBody, SubmitImageGenerationTaskResponse.class); 93 } else { 94 throw new WXPayBrandUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 95 } 96 } catch (IOException e) { 97 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 98 } 99 } 100 101 private final String brand_id; 102 private final String certificateSerialNo; 103 private final PrivateKey privateKey; 104 private final String wechatPayPublicKeyId; 105 private final PublicKey wechatPayPublicKey; 106 107 public SubmitImageGenerationTask(String brand_id, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 108 this.brand_id = brand_id; 109 this.certificateSerialNo = certificateSerialNo; 110 this.privateKey = WXPayBrandUtility.loadPrivateKeyFromPath(privateKeyFilePath); 111 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 112 this.wechatPayPublicKey = WXPayBrandUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 113 } 114 115 public static class SubmitImageGenerationTaskRequest { 116 @SerializedName("task_id") 117 public String taskId; 118 119 @SerializedName("image_generation_type") 120 public ImageGenerationType imageGenerationType; 121 122 @SerializedName("combine_image") 123 public CombineImage combineImage; 124 125 @SerializedName("cut_out") 126 public CutOut cutOut; 127 } 128 129 public static class SubmitImageGenerationTaskResponse { 130 @SerializedName("task_id") 131 public String taskId; 132 } 133 134 public enum ImageGenerationType { 135 @SerializedName("COMBINE_IMAGE") 136 COMBINE_IMAGE, 137 @SerializedName("CUT_OUT") 138 CUT_OUT 139 } 140 141 public static class CombineImage { 142 @SerializedName("scope") 143 public ProductCouponScope scope; 144 145 @SerializedName("type") 146 public ProductCouponType type; 147 148 @SerializedName("usage_mode") 149 public UsageMode usageMode; 150 151 @SerializedName("normal_coupon") 152 public NormalCouponUsageRule normalCoupon; 153 154 @SerializedName("discount_coupon") 155 public DiscountCouponUsageRule discountCoupon; 156 157 @SerializedName("exchange_coupon") 158 public ExchangeCouponUsageRule exchangeCoupon; 159 160 @SerializedName("background_color") 161 public String backgroundColor; 162 } 163 164 public static class CutOut { 165 @SerializedName("image_url") 166 public String imageUrl; 167 } 168 169 public enum ProductCouponScope { 170 @SerializedName("ALL") 171 ALL, 172 @SerializedName("SINGLE") 173 SINGLE 174 } 175 176 public enum ProductCouponType { 177 @SerializedName("NORMAL") 178 NORMAL, 179 @SerializedName("DISCOUNT") 180 DISCOUNT, 181 @SerializedName("EXCHANGE") 182 EXCHANGE 183 } 184 185 public enum UsageMode { 186 @SerializedName("SINGLE") 187 SINGLE, 188 @SerializedName("PROGRESSIVE_BUNDLE") 189 PROGRESSIVE_BUNDLE 190 } 191 192 public static class NormalCouponUsageRule { 193 @SerializedName("threshold") 194 public Long threshold; 195 196 @SerializedName("discount_amount") 197 public Long discountAmount; 198 } 199 200 public static class DiscountCouponUsageRule { 201 @SerializedName("threshold") 202 public Long threshold; 203 204 @SerializedName("percent_off") 205 public Long percentOff; 206 } 207 208 public static class ExchangeCouponUsageRule { 209 @SerializedName("threshold") 210 public Long threshold; 211 212 @SerializedName("exchange_price") 213 public Long exchangePrice; 214 } 215 216} 217
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_brand_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/brand/4015826866 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 10) 11 12func main() { 13 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 14 config, err := wxpay_brand_utility.CreateBrandConfig( 15 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 16 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 17 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 18 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 19 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 20 ) 21 if err != nil { 22 fmt.Println(err) 23 return 24 } 25 26 request := &SubmitImageGenerationTaskRequest{ 27 TaskId: wxpay_brand_utility.String("image_generation_task_1"), 28 ImageGenerationType: IMAGEGENERATIONTYPE_COMBINE_IMAGE.Ptr(), 29 CombineImage: &CombineImage{ 30 Scope: PRODUCTCOUPONSCOPE_ALL.Ptr(), 31 Type: PRODUCTCOUPONTYPE_NORMAL.Ptr(), 32 UsageMode: USAGEMODE_SINGLE.Ptr(), 33 NormalCoupon: &NormalCouponUsageRule{ 34 Threshold: wxpay_brand_utility.Int64(10000), 35 DiscountAmount: wxpay_brand_utility.Int64(100), 36 }, 37 DiscountCoupon: &DiscountCouponUsageRule{ 38 Threshold: wxpay_brand_utility.Int64(10000), 39 PercentOff: wxpay_brand_utility.Int64(30), 40 }, 41 ExchangeCoupon: &ExchangeCouponUsageRule{ 42 Threshold: wxpay_brand_utility.Int64(10000), 43 ExchangePrice: wxpay_brand_utility.Int64(100), 44 }, 45 BackgroundColor: wxpay_brand_utility.String("#ff5733"), 46 }, 47 CutOut: &CutOut{ 48 ImageUrl: wxpay_brand_utility.String("https://wxpaylogo.qpic.cn/wxpaylogo/example.jpg"), 49 }, 50 } 51 52 response, err := SubmitImageGenerationTask(config, request) 53 if err != nil { 54 fmt.Printf("请求失败: %+v\n", err) 55 // TODO: 请求失败,根据状态码执行不同的处理 56 return 57 } 58 59 // TODO: 请求成功,继续业务逻辑 60 fmt.Printf("请求成功: %+v\n", response) 61} 62 63func SubmitImageGenerationTask(config *wxpay_brand_utility.BrandConfig, request *SubmitImageGenerationTaskRequest) (response *SubmitImageGenerationTaskResponse, err error) { 64 const ( 65 host = "https://api.mch.weixin.qq.com" 66 method = "POST" 67 path = "/brand/marketing/product-coupon/image-generation-tasks" 68 ) 69 70 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 71 if err != nil { 72 return nil, err 73 } 74 reqBody, err := json.Marshal(request) 75 if err != nil { 76 return nil, err 77 } 78 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 79 if err != nil { 80 return nil, err 81 } 82 httpRequest.Header.Set("Accept", "application/json") 83 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 84 httpRequest.Header.Set("Content-Type", "application/json") 85 authorization, err := wxpay_brand_utility.BuildAuthorization(config.BrandId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 86 if err != nil { 87 return nil, err 88 } 89 httpRequest.Header.Set("Authorization", authorization) 90 91 client := &http.Client{} 92 httpResponse, err := client.Do(httpRequest) 93 if err != nil { 94 return nil, err 95 } 96 respBody, err := wxpay_brand_utility.ExtractResponseBody(httpResponse) 97 if err != nil { 98 return nil, err 99 } 100 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 101 // 2XX 成功,验证应答签名 102 err = wxpay_brand_utility.ValidateResponse( 103 config.WechatPayPublicKeyId(), 104 config.WechatPayPublicKey(), 105 &httpResponse.Header, 106 respBody, 107 ) 108 if err != nil { 109 return nil, err 110 } 111 response := &SubmitImageGenerationTaskResponse{} 112 if err := json.Unmarshal(respBody, response); err != nil { 113 return nil, err 114 } 115 116 return response, nil 117 } else { 118 return nil, wxpay_brand_utility.NewApiException( 119 httpResponse.StatusCode, 120 httpResponse.Header, 121 respBody, 122 ) 123 } 124} 125 126type SubmitImageGenerationTaskRequest struct { 127 TaskId *string `json:"task_id,omitempty"` 128 ImageGenerationType *ImageGenerationType `json:"image_generation_type,omitempty"` 129 CombineImage *CombineImage `json:"combine_image,omitempty"` 130 CutOut *CutOut `json:"cut_out,omitempty"` 131} 132 133type SubmitImageGenerationTaskResponse struct { 134 TaskId *string `json:"task_id,omitempty"` 135} 136 137type ImageGenerationType string 138 139func (e ImageGenerationType) Ptr() *ImageGenerationType { 140 return &e 141} 142 143const ( 144 IMAGEGENERATIONTYPE_COMBINE_IMAGE ImageGenerationType = "COMBINE_IMAGE" 145 IMAGEGENERATIONTYPE_CUT_OUT ImageGenerationType = "CUT_OUT" 146) 147 148type CombineImage struct { 149 Scope *ProductCouponScope `json:"scope,omitempty"` 150 Type *ProductCouponType `json:"type,omitempty"` 151 UsageMode *UsageMode `json:"usage_mode,omitempty"` 152 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 153 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 154 ExchangeCoupon *ExchangeCouponUsageRule `json:"exchange_coupon,omitempty"` 155 BackgroundColor *string `json:"background_color,omitempty"` 156} 157 158type CutOut struct { 159 ImageUrl *string `json:"image_url,omitempty"` 160} 161 162type ProductCouponScope string 163 164func (e ProductCouponScope) Ptr() *ProductCouponScope { 165 return &e 166} 167 168const ( 169 PRODUCTCOUPONSCOPE_ALL ProductCouponScope = "ALL" 170 PRODUCTCOUPONSCOPE_SINGLE ProductCouponScope = "SINGLE" 171) 172 173type ProductCouponType string 174 175func (e ProductCouponType) Ptr() *ProductCouponType { 176 return &e 177} 178 179const ( 180 PRODUCTCOUPONTYPE_NORMAL ProductCouponType = "NORMAL" 181 PRODUCTCOUPONTYPE_DISCOUNT ProductCouponType = "DISCOUNT" 182 PRODUCTCOUPONTYPE_EXCHANGE ProductCouponType = "EXCHANGE" 183) 184 185type UsageMode string 186 187func (e UsageMode) Ptr() *UsageMode { 188 return &e 189} 190 191const ( 192 USAGEMODE_SINGLE UsageMode = "SINGLE" 193 USAGEMODE_PROGRESSIVE_BUNDLE UsageMode = "PROGRESSIVE_BUNDLE" 194) 195 196type NormalCouponUsageRule struct { 197 Threshold *int64 `json:"threshold,omitempty"` 198 DiscountAmount *int64 `json:"discount_amount,omitempty"` 199} 200 201type DiscountCouponUsageRule struct { 202 Threshold *int64 `json:"threshold,omitempty"` 203 PercentOff *int64 `json:"percent_off,omitempty"` 204} 205 206type ExchangeCouponUsageRule struct { 207 Threshold *int64 `json:"threshold,omitempty"` 208 ExchangePrice *int64 `json:"exchange_price,omitempty"` 209} 210
应答参数
200 OK
task_id 必填 string
【图片生成的任务ID】 品牌创建图片生成任务的请求流水号,品牌侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间
应答示例
200 OK
1{ 2 "task_id" : "image_generation_task_1" 3} 4
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

