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

