查询图片生成任务执行结果
更新时间:2026.01.26查询图片生成任务执行结果
接口说明
支持商户:【普通服务商】
请求方式:【GET】/v3/marketing/partner/product-coupon/image-generation-tasks/{task_id}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
接口限频:20/秒(商户号维度)
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
path 路径参数
task_id 必填 string
【图片生成的任务ID】 服务商创建图片生成任务的请求流水号,服务商侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间
query 查询参数
brand_id 必填 string
【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系
image_generation_type 必填 string
【图片生成类型】 与提交图片生成任务时所传的类型一致
可选取值
COMBINE_IMAGE: 适合全场类优惠头图,将品牌元素与商品券优惠等信息拼接生成头图CUT_OUT: 适合单品类优惠头图,用于去除图片背景,保留商品主体
请求示例
GET
1curl -X GET \ 2 https://api.mch.weixin.qq.com/v3/marketing/partner/product-coupon/image-generation-tasks/image_generation_task_1?brand_id=120344&image_generation_type=COMBINE_IMAGE \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" 5
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/v3/partner/4014985777 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 GetImageGenerationTask { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "GET"; 28 private static String PATH = "/v3/marketing/partner/product-coupon/image-generation-tasks/{task_id}"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 GetImageGenerationTask client = new GetImageGenerationTask( 33 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 34 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 35 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 GetImageGenerationTaskRequest request = new GetImageGenerationTaskRequest(); 41 request.taskId = "image_generation_task_1"; 42 request.brandId = "120344"; 43 request.imageGenerationType = ImageGenerationType.COMBINE_IMAGE; 44 try { 45 ImageGenerationTask response = client.run(request); 46 // TODO: 请求成功,继续业务逻辑 47 System.out.println(response); 48 } catch (WXPayUtility.ApiException e) { 49 // TODO: 请求失败,根据状态码执行不同的逻辑 50 e.printStackTrace(); 51 } 52 } 53 54 public ImageGenerationTask run(GetImageGenerationTaskRequest request) { 55 String uri = PATH; 56 uri = uri.replace("{task_id}", WXPayUtility.urlEncode(request.taskId)); 57 Map<String, Object> args = new HashMap<>(); 58 args.put("brand_id", request.brandId); 59 args.put("image_generation_type", request.imageGenerationType); 60 String queryString = WXPayUtility.urlEncode(args); 61 if (!queryString.isEmpty()) { 62 uri = uri + "?" + queryString; 63 } 64 65 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 66 reqBuilder.addHeader("Accept", "application/json"); 67 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 68 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null)); 69 reqBuilder.method(METHOD, null); 70 Request httpRequest = reqBuilder.build(); 71 72 // 发送HTTP请求 73 OkHttpClient client = new OkHttpClient.Builder().build(); 74 try (Response httpResponse = client.newCall(httpRequest).execute()) { 75 String respBody = WXPayUtility.extractBody(httpResponse); 76 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 77 // 2XX 成功,验证应答签名 78 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 79 httpResponse.headers(), respBody); 80 81 // 从HTTP应答报文构建返回数据 82 return WXPayUtility.fromJson(respBody, ImageGenerationTask.class); 83 } else { 84 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 85 } 86 } catch (IOException e) { 87 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 88 } 89 } 90 91 private final String mchid; 92 private final String certificateSerialNo; 93 private final PrivateKey privateKey; 94 private final String wechatPayPublicKeyId; 95 private final PublicKey wechatPayPublicKey; 96 97 public GetImageGenerationTask(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 98 this.mchid = mchid; 99 this.certificateSerialNo = certificateSerialNo; 100 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 101 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 102 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 103 } 104 105 public static class GetImageGenerationTaskRequest { 106 @SerializedName("brand_id") 107 @Expose(serialize = false) 108 public String brandId; 109 110 @SerializedName("task_id") 111 @Expose(serialize = false) 112 public String taskId; 113 114 @SerializedName("image_generation_type") 115 @Expose(serialize = false) 116 public ImageGenerationType imageGenerationType; 117 } 118 119 public static class ImageGenerationTask { 120 @SerializedName("brand_id") 121 public String brandId; 122 123 @SerializedName("task_id") 124 public String taskId; 125 126 @SerializedName("image_generation_type") 127 public ImageGenerationType imageGenerationType; 128 129 @SerializedName("task_state") 130 public TaskState taskState; 131 132 @SerializedName("combine_image_result") 133 public CombineImageResult combineImageResult; 134 135 @SerializedName("cut_out_result") 136 public CutOutResult cutOutResult; 137 } 138 139 public enum ImageGenerationType { 140 @SerializedName("COMBINE_IMAGE") 141 COMBINE_IMAGE, 142 @SerializedName("CUT_OUT") 143 CUT_OUT 144 } 145 146 public enum TaskState { 147 @SerializedName("PROCESSING") 148 PROCESSING, 149 @SerializedName("FAIL") 150 FAIL, 151 @SerializedName("SUCCESS") 152 SUCCESS 153 } 154 155 public static class CombineImageResult { 156 @SerializedName("image_url") 157 public String imageUrl; 158 } 159 160 public static class CutOutResult { 161 @SerializedName("image_url") 162 public String imageUrl; 163 } 164 165} 166
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "demo/wxpay_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/v3/partner/4015119446 5 "encoding/json" 6 "fmt" 7 "net/http" 8 "net/url" 9 "strings" 10) 11 12func main() { 13 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 14 config, err := wxpay_utility.CreateMchConfig( 15 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 16 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 17 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 18 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 19 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 20 ) 21 if err != nil { 22 fmt.Println(err) 23 return 24 } 25 26 request := &GetImageGenerationTaskRequest{ 27 BrandId: wxpay_utility.String("120344"), 28 TaskId: wxpay_utility.String("image_generation_task_1"), 29 ImageGenerationType: IMAGEGENERATIONTYPE_COMBINE_IMAGE.Ptr(), 30 } 31 32 response, err := GetImageGenerationTask(config, request) 33 if err != nil { 34 fmt.Printf("请求失败: %+v\n", err) 35 // TODO: 请求失败,根据状态码执行不同的处理 36 return 37 } 38 39 // TODO: 请求成功,继续业务逻辑 40 fmt.Printf("请求成功: %+v\n", response) 41} 42 43func GetImageGenerationTask(config *wxpay_utility.MchConfig, request *GetImageGenerationTaskRequest) (response *ImageGenerationTask, err error) { 44 const ( 45 host = "https://api.mch.weixin.qq.com" 46 method = "GET" 47 path = "/v3/marketing/partner/product-coupon/image-generation-tasks/{task_id}" 48 ) 49 50 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 51 if err != nil { 52 return nil, err 53 } 54 reqUrl.Path = strings.Replace(reqUrl.Path, "{task_id}", url.PathEscape(*request.TaskId), -1) 55 query := reqUrl.Query() 56 if request.BrandId != nil { 57 query.Add("brand_id", *request.BrandId) 58 } 59 if request.ImageGenerationType != nil { 60 query.Add("image_generation_type", fmt.Sprintf("%v", *request.ImageGenerationType)) 61 } 62 reqUrl.RawQuery = query.Encode() 63 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 64 if err != nil { 65 return nil, err 66 } 67 httpRequest.Header.Set("Accept", "application/json") 68 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 69 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 70 if err != nil { 71 return nil, err 72 } 73 httpRequest.Header.Set("Authorization", authorization) 74 75 client := &http.Client{} 76 httpResponse, err := client.Do(httpRequest) 77 if err != nil { 78 return nil, err 79 } 80 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 81 if err != nil { 82 return nil, err 83 } 84 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 85 // 2XX 成功,验证应答签名 86 err = wxpay_utility.ValidateResponse( 87 config.WechatPayPublicKeyId(), 88 config.WechatPayPublicKey(), 89 &httpResponse.Header, 90 respBody, 91 ) 92 if err != nil { 93 return nil, err 94 } 95 response := &ImageGenerationTask{} 96 if err := json.Unmarshal(respBody, response); err != nil { 97 return nil, err 98 } 99 100 return response, nil 101 } else { 102 return nil, wxpay_utility.NewApiException( 103 httpResponse.StatusCode, 104 httpResponse.Header, 105 respBody, 106 ) 107 } 108} 109 110type GetImageGenerationTaskRequest struct { 111 BrandId *string `json:"brand_id,omitempty"` 112 TaskId *string `json:"task_id,omitempty"` 113 ImageGenerationType *ImageGenerationType `json:"image_generation_type,omitempty"` 114} 115 116func (o *GetImageGenerationTaskRequest) MarshalJSON() ([]byte, error) { 117 type Alias GetImageGenerationTaskRequest 118 a := &struct { 119 BrandId *string `json:"brand_id,omitempty"` 120 TaskId *string `json:"task_id,omitempty"` 121 ImageGenerationType *ImageGenerationType `json:"image_generation_type,omitempty"` 122 *Alias 123 }{ 124 // 序列化时移除非 Body 字段 125 BrandId: nil, 126 TaskId: nil, 127 ImageGenerationType: nil, 128 Alias: (*Alias)(o), 129 } 130 return json.Marshal(a) 131} 132 133type ImageGenerationTask struct { 134 BrandId *string `json:"brand_id,omitempty"` 135 TaskId *string `json:"task_id,omitempty"` 136 ImageGenerationType *ImageGenerationType `json:"image_generation_type,omitempty"` 137 TaskState *TaskState `json:"task_state,omitempty"` 138 CombineImageResult *CombineImageResult `json:"combine_image_result,omitempty"` 139 CutOutResult *CutOutResult `json:"cut_out_result,omitempty"` 140} 141 142type ImageGenerationType string 143 144func (e ImageGenerationType) Ptr() *ImageGenerationType { 145 return &e 146} 147 148const ( 149 IMAGEGENERATIONTYPE_COMBINE_IMAGE ImageGenerationType = "COMBINE_IMAGE" 150 IMAGEGENERATIONTYPE_CUT_OUT ImageGenerationType = "CUT_OUT" 151) 152 153type TaskState string 154 155func (e TaskState) Ptr() *TaskState { 156 return &e 157} 158 159const ( 160 TASKSTATE_PROCESSING TaskState = "PROCESSING" 161 TASKSTATE_FAIL TaskState = "FAIL" 162 TASKSTATE_SUCCESS TaskState = "SUCCESS" 163) 164 165type CombineImageResult struct { 166 ImageUrl *string `json:"image_url,omitempty"` 167} 168 169type CutOutResult struct { 170 ImageUrl *string `json:"image_url,omitempty"` 171} 172
应答参数
折叠全部参数
200 OK
brand_id 必填 string
【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系
task_id 必填 string
【图片生成的任务ID】 服务商创建图片生成任务的请求流水号,服务商侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间
image_generation_type 必填 string
【图片生成类型】 图片生成类型
可选取值
COMBINE_IMAGE: 适合全场类优惠头图,将品牌元素与商品券优惠等信息拼接生成头图CUT_OUT: 适合单品类优惠头图,用于去除图片背景,保留商品主体
task_state 必填 string
【任务状态】 任务状态
可选取值
PROCESSING: 任务执行中FAIL: 任务失败SUCCESS: 任务成功
combine_image_result 选填 object
【拼图结果】 当 image_generation_type 为 COMBINE_IMAGE ,并且任务状态为 SUCCESS 时,该数据结构值有效
| 属性 | |
image_url 必填 string 【生成的图片URL】 当任务状态为 |
cut_out_result 选填 object
【生成商品图结果】 当 image_generation_type 为 CUT_OUT ,并且任务状态为 SUCCESS 时,该数据结构值有效
| 属性 | |
image_url 必填 string 【生成的图片URL】 当任务状态为 |
应答示例
200 OK
1{ 2 "brand_id" : "120344", 3 "task_id" : "image_generation_task_1", 4 "image_generation_type" : "COMBINE_IMAGE", 5 "task_state" : "PROCESSING", 6 "combine_image_result" : { 7 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/example.jpg" 8 }, 9 "cut_out_result" : { 10 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/example.jpg" 11 } 12} 13
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

