智能图像扩展--veImageX-火山引擎

文档中心

veImageX

AI 能力组件 2.0

智能图像扩展

智能图像扩展附加组件利用 AI 能力，对原图上下左右 4 个方向进行图片内容的扩展。算法会根据原图内容对扩展区域自动补充上相似内容，使补充结果图符合原图纹理与内容。本文介绍如何使用智能图像扩展附加组件。

效果示例

场景	输入图	生成示例结果
竖屏转横屏
横屏转竖屏

效果调试

为直观了解图像扩展后的实时效果，您可以在调试地址中实时修改扩展比例，查看不同处理效果。

调试地址：https://p3-mofang.byteimg.com/tos-cn-i-x9vch4xmek/example.jfif~tplv-x9vch4xmek-ImageExtension:0.2:0.1.png
- 原图访问地址为：https://p3-mofang.byteimg.com/tos-cn-i-x9vch4xmek/example.jfif
- 图片扩展模板为（指定向上向下扩展）：tplv-x9vch4xmek-ImageExtension:0.2:0.1.png
  - 0.2 为向上扩展的比例。
  - 0.1 为向下扩展的比例。
在实际调试中，请修改这两个比例参数，将其指定为您的自定义扩展比例。
图片展示
原图
图片智能扩展后的结果图

使用场景

广告展示平台适配：支持在广告主图片基础上做纯色的填充，适配不同的展示入口。可以有效避免图像放大缩小而带来的比例失调，提高图片利用率，减少处理工作量。
视觉素材设计，支持依据原图内容进行智能页面扩展，使扩展内容与原图的边沿融合自然。可提高您的图片处理效率，适应不同的设计需求。

使用限制

为确保能够生成图像，请满足以下限制。

输入格式：.png、.jpg、.jpeg、.webp、.tiff、.bmp、.heic。如果为其他格式，请先通过模板变更图片格式。
输入分辨率：建议长边 ≤ 2048 px。更高分辨率可能导致处理耗时较高，可先通过模板变更图片分辨率。
输出格式：.png、.jpg、.jpeg、.webp、.tiff、.bmp、.heic。可通过模板二次处理为其他格式。

使用方法

前提条件

已开通 veImageX 产品服务并创建服务。
已开通智能处理计费配置。
（可选）如需完成以下操作，确保已新建模板。
- 处理输入图像：如果输入图像不符合输入限制，您可以通过模板来压缩图片大小或变更图片格式等，再将处理后的图片作为输入图像。
- 处理生成图像：对生成的图像进行二次处理，例如添加水印或调整分辨率。

步骤一：调用 AI 能力

方式一：通过 API 调用

同步处理

调用同步处理接口 AIProcess，提交一条 URL 或 URI 资源执行同步 AI 图像处理任务。
请求示例

POST https://imagex.volcengineapi.com/?Action=AIProcess&Version=2023-05-01
{
    "ServiceId": "91**2g", // 必选。服务 ID。
    "WorkflowTemplateId": "system_workflow_ai_bgfill", // 必选。模板 ID。
    "WorkflowParameter": "{\"Input\":{\"ObjectKey\":\"example.webp\",\"DataType\":\"uri\"},\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}" // 必选。模板参数。
}

其中，

ServiceId：服务 ID，可从服务管理页面获取。
WorkflowTemplateId：取值固定为 system_workflow_ai_bgfill。
WorkflowParameter：根据输入参数，设置该参数取值。

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "AIProcess",
        "Version": "2023-05-01",
        "Service": "ImageX",
        "Region": "cn-north-1"
    },
    "Result": {
        "Output": "{\"ObjectKey\":\"a.webp\",\"Size\":54509,\"Format\":\"webp\"}"
    }
}

Output 的参数含义详见输出参数。

异步处理

批量执行 AI 图像处理任务。

注意

确保已新建并启动批量处理任务队列。详见步骤一：新建并启动任务队列。

调用异步处理接口 CreateImageAITask，创建批量处理任务。
请求示例

POST https://imagex.volcengineapi.com/?Action=CreateImageAITask&Version=2023-05-01
{
    "ServiceId": "5s****fo", // 必选。服务 ID。
    "DataType": "uri", // 必选。图片地址类型，支持取值 uri 和 url。
    "DataList": [
        "a.png",
        "uridemo.png"
    ], // 必选。图片 URI 或 URL 列表（URI 不包含 tos-*-i-* 前缀）。
    "CallbackConf": { // 可选。回调配置。
        "Method": "HTTP", // 必选。回调方式，取值固定为 HTTP。
        "Endpoint": "https://demo.com", // 必选。回调地址，用于接收处理结果。
        "DataFormat": "JSON", // 可选。回调数据格式，支持取值 XML 和 JSON。
        "Args": "product id", // 可选。业务自定义回调参数。
        "Type": "task" // 可选。回调触发类型，支持取值 task 和 entry。默认值为 entry。
    },
    "WorkflowParameter": "{\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}", // 必选。模板参数。
    "WorkflowTemplateId": "system_workflow_ai_bgfill", // 必选。模板 ID。
    "QueueId": "62f224ce61****826e38c29a" // 必选。队列 ID。
}

其中，

WorkflowTemplateId：取值固定为 system_workflow_ai_bgfill。
WorkflowParameter：根据输入参数，设置该参数取值。
返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateImageAITask",
        "Version": "2023-05-01",
        "Service": "ImageX",
        "Region": "cn-north-1"
    },
    "Result": {
        "TaskId": "649b9d3****5537684010a7", // 任务 ID。
        "QueueId": "62f224ce61****826e38c29a" // 队列 ID。
    }
}

通过以下任一方式获取图像处理结果。
- 回调通知：如果您在上一步设置了回调地址（Endpoint），则当任务完成后，veImageX 会向该回调地址发送回调消息。详见回调。
- 主动查询：如果您未设置回调地址，调用 GetImageAIDetails 接口，获取图像处理结果。

方式二：通过服务端 SDK 调用

veImageX 提供了以下编程语言的 SDK，方便您调用 API。

Golang SDK

Python SDK

Java SDK

PHP SDK

Node.js SDK

前提条件

调用接口前，请先完成 Golang SDK 的安装及初始化操作。

同步处理

提交一条 URL 或 URI 资源执行同步 AI 图像处理任务。详见同步处理。

package imagex_test

import (
        "context"
        "encoding/json"
        "fmt"
        "testing"

        "github.com/volcengine/volc-sdk-golang/base"
        imagex "github.com/volcengine/volc-sdk-golang/service/imagex/v2"
)

func Test_AIProcess(t *testing.T) {
        instance := imagex.NewInstance()

        instance.SetCredential(base.Credentials{
              // 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
                AccessKeyID:     "ak",
                SecretAccessKey: "sk",
        })

        param := &imagex.AIProcessReq{
                AIProcessBody: &imagex.AIProcessBody{
                  ServiceID: "91**2g", // 必选。服务 ID。
                  WorkflowTemplateID: "system_workflow_ai_bgfill",   // 必选。模板 ID。固定取值。
                  WorkflowParameter: "{\"Input\":{\"ObjectKey\":\"example.webp\",\"DataType\":\"uri\"},\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}", // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
 },
        }
        
        resp, err := instance.AIProcess(context.Background(), param)

        if err != nil {
                fmt.Printf("error %v", err)
        } else {
                t, _ := json.Marshal(resp)
                fmt.Printf("success %v", string(t))
        }
}

异步处理

创建批量处理任务。接口参数说明详见 CreateImageAITask。

package imagex_test

import (
        "context"
        "encoding/json"
        "fmt"
        "testing"

        "github.com/volcengine/volc-sdk-golang/base"
        imagex "github.com/volcengine/volc-sdk-golang/service/imagex/v2"
)

func Test_CreateImageAITask(t *testing.T) {
        instance := imagex.NewInstance()

        instance.SetCredential(base.Credentials{
              // 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
              // 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。        
                AccessKeyID:     "ak",
                SecretAccessKey: "sk",
        })

        param := &imagex.CreateImageAITaskReq{
            CreateImageAITaskBody: &imagex.CreateImageAITaskBody{
               ServiceID: "5s****fo",                       // 必选。服务 ID。
               QueueID:   "649a9dbc32**064d44cf5b0",        // 必选。队列 ID。
               DataType:  "uri",                            // 必选。图片地址类型，支持取值 uri 和 url。
               DataList:  []string{"a.png", "uridemo.png"}, // 必选。图片 URI 或 URL 列表（URI 不包含 tos-*-i-* 前缀）。
               CallbackConf: &imagex.CreateImageAITaskBodyCallbackConf{ // 可选。回调配置。
                  Method:     "HTTP",             // 必选。回调方式，取值固定为 HTTP。
                  Endpoint:   "https://demo.com", // 必选。回调地址，用于接收处理结果。
                  DataFormat: "JSON",             // 可选。回调数据格式，支持取值 XML 和 JSON。
                  Args:       "productid",        // 可选。业务自定义回调参数。
                  Type:       "task",             // 可选。回调触发类型，支持取值 task 和 entry。默认值为 entry。
               },
               WorkflowParameter:  "{\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}", // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
               WorkflowTemplateID: "system_workflow_ai_bgfill",                                                // 必选。模板 ID。固定取值。
            },
        }

        resp, err := instance.CreateImageAITask(context.Background(), param)

        if err != nil {
                fmt.Printf("error %v", err)
        } else {
                t, _ := json.Marshal(resp)
                fmt.Printf("success %v", string(t))
        }
}

通过以下任一方式获取图像处理结果。

回调通知：如果您在上一步设置了回调地址，则当任务完成后，veImageX 会向该回调地址发送回调消息。详见回调。

主动查询：如果您未设置回调地址，需主动获取图像处理结果。接口参数说明详见 GetImageAIDetails。

package imagex_test

import (
        "context"
        "encoding/json"
        "fmt"
        "testing"

        "github.com/volcengine/volc-sdk-golang/base"
        imagex "github.com/volcengine/volc-sdk-golang/service/imagex/v2"
)

func Test_GetImageAIDetails(t *testing.T) {
        instance := imagex.NewInstance()

        instance.SetCredential(base.Credentials{
              // 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
              // 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。              
                AccessKeyID:     "ak",
                SecretAccessKey: "sk",
        })

        param := &imagex.GetImageAIDetailsQuery{
            QueueID: "649a9dbc32**064d44cf5b0", // 必选。队列 ID。
            TaskID: "67174744a**54449623155b9", // 必选。任务 ID。
            StartTime: 1684713599, // 必选。查询开始时间。Unix 秒级时间戳。
            EndTime: 1684913599, // 必选。查询结束时间。Unix 秒级时间戳。
            Status: "Success", // 可选。任务执行状态。默认返回所有任务。
            SearchPtn: "test", // 可选。图片 URI 或 URL 关键字。默认返回所有任务。
            Limit: 10, // 必选。分页条数。取值范围为 (0, 100]。
            Offset: 0, // 可选。分页偏移量。
            ServiceID: "5s****fo", // 必选。服务 ID。
        }

        resp, err := instance.GetImageAIDetails(context.Background(), param)

        if err != nil {
                fmt.Printf("error %v", err)
        } else {
                t, _ := json.Marshal(resp)
                fmt.Printf("success %v", string(t))
        }
}

前提条件

调用接口前，请先完成 Python SDK 的安装及初始化操作。

同步处理

提交一条 URL 或 URI 资源执行同步 AI 图像处理任务。详见同步处理。

# coding:utf-8
from volcengine.imagex.v2.imagex_service import ImagexService

if __name__ == '__main__':
    service = ImagexService()

    # 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
    # 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
    service.set_ak('ak')
    service.set_sk('sk')

    body = {
        "ServiceId": "91**2g",  # 必选。服务 ID。
        "WorkflowTemplateId": "system_workflow_ai_bgfill",  # # 必选。模板 ID。固定取值。
        "WorkflowParameter": "{\"Input\":{\"ObjectKey\":\"example.webp\",\"DataType\":\"uri\"},\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}" # 必选。根据本文模板说明 > 输入参数，设置该参数取值。
    }
    query = {}

    resp = service.ai_process(query, body)
    print(resp)

异步处理

创建批量处理任务。接口参数说明详见 CreateImageAITask。

# coding:utf-8
from volcengine.imagex.v2.imagex_service import ImagexService

if __name__ == '__main__':
    service = ImagexService()

    # 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
    # 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
    service.set_ak('ak')
    service.set_sk('sk')

    body = {
        "ServiceId": "5s****fo",  # 必选。服务 ID。
        "QueueId": "649a9dbc32**064d44cf5b0",  # 必选。队列 ID。
        "DataType": "uri",  # 必选。图片地址类型，支持取值 uri 和 url。
        "DataList": ["a.png", "uridemo.png"],  # 必选。图片 URI 或 URL 列表（URI 不包含 tos-*-i-* 前缀）。
        "CallbackConf": {  # 可选。回调配置。
            "Method": "HTTP",  # 必选。回调方式，取值固定为 HTTP。
            "Endpoint": "https://demo.com",  # 必选。回调地址，用于接收处理结果。
            "DataFormat": "JSON",  # 可选。回调数据格式，支持取值 XML 和 JSON。
            "Args": "productid",  # 可选。业务自定义回调参数。
            "Type": "task"  # 可选。回调触发类型，支持取值 task 和 entry。默认值为 entry。
        },
        "WorkflowParameter": "{\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}",  # 必选。根据本文模板说明 > 输入参数，设置该参数取值。
        "WorkflowTemplateId": "system_workflow_ai_bgfill"  # 必选。模板 ID。固定取值。
    }

    resp = service.create_image_ai_task(query, body)
    print(resp)

通过以下任一方式获取图像处理结果。

回调通知：如果您在上一步设置了回调地址，则当任务完成后，veImageX 会向该回调地址发送回调消息。详见回调。

主动查询：如果您未设置回调地址，需主动获取图像处理结果。接口参数说明详见 GetImageAIDetails。

# coding:utf-8
from volcengine.imagex.v2.imagex_service import ImagexService

if __name__ == '__main__':
    service = ImagexService()

    # 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
    # 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
    service.set_ak('ak')
    service.set_sk('sk')

    query = {
         "QueueId": "649a9dbc32**064d44cf5b0", # 必选。队列 ID。
         "TaskId": "67174744a**54449623155b9", # 必选。任务 ID。
         "StartTime": 1684713599, # 必选。查询开始时间。Unix 秒级时间戳。
         "EndTime": 1684913599, # 必选。查询结束时间。Unix 秒级时间戳。
         "Status": "Success", # 可选。任务执行状态。默认返回所有任务。
         "SearchPtn": "test", # 可选。图片 URI 或 URL 关键字。默认返回所有任务。
         "Limit": 10, # 必选。分页条数。取值范围为 (0, 100]。
         "Offset": 0, # 可选。分页偏移量。
         "ServiceId": "5s****fo" # 必选。服务 ID。
    }

    resp = service.get_image_ai_details(query)
    print(resp)

前提条件

调用接口前，请先完成 Java SDK 的安装及初始化操作。

同步处理

提交一条 URL 或 URI 资源执行同步 AI 图像处理任务。详见同步处理。

package com.volcengine.example.imagex.v2.api;

import com.volcengine.model.imagex.v2.*;
import com.volcengine.service.imagex.v2.ImagexService;

public class AIProcessExample {
    public static void main(String[] args) {
        ImagexService service = ImagexService.getInstance();
         // 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
        // 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。       
        service.setAccessKey("ak");
        service.setSecretKey("sk");

        AIProcessBody body = new AIProcessBody();
         body.setServiceId("91**2g"); // 必选。服务 ID。
         body.setWorkflowTemplateId("system_workflow_ai_bgfill"); // 必选。模板 ID。固定取值。
         body.setWorkflowParameter("{\"Input\":{\"ObjectKey\":\"example.webp\",\"DataType\":\"uri\"},\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}"); // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
 
        try {
            AIProcessRes resp = service.aIProcess(body);
            System.out.println(resp);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

异步处理

创建批量处理任务。接口参数说明详见 CreateImageAITask。

package com.volcengine.example.imagex.v2.api;

import com.volcengine.model.imagex.v2.*;
import com.volcengine.service.imagex.v2.ImagexService;

public class CreateImageAITaskExample {
    public static void main(String[] args) {
        ImagexService service = ImagexService.getInstance();
        // 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
        // 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
        service.setAccessKey("ak");
        service.setSecretKey("sk");

     // 1.（可选）构建回调配置（CallbackConf）。
     CreateImageAITaskBodyCallbackConf callbackConf = new CreateImageAITaskBodyCallbackConf();
     callbackConf.setMethod("HTTP"); // 必选。回调方式，取值固定为 HTTP。
     callbackConf.setEndpoint("https://demo.com"); // 必选。回调地址，用于接收处理结果。
     callbackConf.setDataFormat("JSON"); // 可选。回调数据格式，支持取值 XML 和 JSON。
     callbackConf.setArgs("productid"); // 可选。业务自定义回调参数。
     callbackConf.setType("task"); // 可选。回调触发类型，支持取值 task 和 entry。默认值为 entry。
    
     // 2. 构建请求体（CreateImageAITaskBody）。
     CreateImageAITaskBody body = new CreateImageAITaskBody();
     body.setServiceId("5s****fo"); // 必选。服务 ID。
     body.setQueueId("649a9dbc32**064d44cf5b0"); // 必选。队列 ID。
     body.setDataType("uri"); // 必选。图片地址类型，支持取值 uri 和 url。
     body.setDataList(Arrays.asList("a.png", "uridemo.png")); // 必选。图片 URI 或 URL 列表（URI 不包含 tos-*-i-* 前缀）。
     body.setCallbackConf(callbackConf); // 可选。回调配置。
     body.setWorkflowParameter("{" +
     "\"BgfillParam\":{" +
     "\"Model\":3," +
     "\"Top\":0.1," +
     "\"Bottom\":0.1," +
     "\"Left\":0.1," +
     "\"Right\":0.1" +
     "}" +
    "}");  // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
     body.setWorkflowTemplateId("system_workflow_ai_bgfill"); // 必选。模板 ID。固定取值。
    
        try {
            CreateImageAITaskRes resp = service.createImageAITask(body);
            System.out.println(resp);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

通过以下任一方式获取图像处理结果。

回调通知：如果您在上一步设置了回调地址，则当任务完成后，veImageX 会向该回调地址发送回调消息。详见回调。

主动查询：如果您未设置回调地址，需主动获取图像处理结果。接口参数说明详见 GetImageAIDetails。

package com.volcengine.example.imagex.v2.api;

import com.volcengine.model.imagex.v2.*;
import com.volcengine.service.imagex.v2.ImagexService;

public class GetImageAIDetailsExample {
    public static void main(String[] args) {
        ImagexService service = ImagexService.getInstance();
        // 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
        // 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
        service.setAccessKey("ak");
        service.setSecretKey("sk");

        GetImageAIDetailsQuery query = new GetImageAIDetailsQuery();
         // 必选参数。
         query.setQueueId("649a9dbc32**064d44cf5b0"); // 队列 ID。
         query.setTaskId("67174744a**54449623155b9"); // 任务 ID。
         query.setStartTime(1684713599L); // 查询开始时间。Unix 秒级时间戳。
         query.setEndTime(1684913599L); // 查询结束时间。Unix 秒级时间戳。
         query.setLimit(10L); // 分页条数。取值范围为 (0, 100]。
         query.setServiceId("5s****fo"); // 服务 ID。  

         // 可选参数。
         query.setStatus("Success"); // 任务执行状态。默认返回所有任务。
         query.setSearchPtn("test"); // 图片 URI 或 URL 关键字。默认返回所有任务。
         query.setOffset(0L); // 分页偏移量。
       
        try {
            GetImageAIDetailsRes resp = service.getImageAIDetails(query);
            System.out.println(resp);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

前提条件

调用接口前，请先完成 PHP SDK 的安装及初始化操作。

同步处理

提交一条 URL 或 URI 资源执行同步 AI 图像处理任务。详见同步处理。

<?php
include_once(__DIR__ . '../../../../vendor/autoload.php');

use Volc\Service\ImageX\V2\Imagex;

$client = Imagex::getInstance();

// 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
// 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
$client->setAccessKey("ak");
$client->setSecretKey("sk");

$body = [
     "ServiceId" => "91**2g", // 必选。服务 ID。
     "WorkflowTemplateId" => "system_workflow_ai_bgfill", // 必选。模板 ID。固定取值。
     "WorkflowParameter" => "{\"Input\":{\"ObjectKey\":\"example.webp\",\"DataType\":\"uri\"},\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}" // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
];
$query = [];

$response = $client->AIProcess($query, $body);
print_r($response);

异步处理

创建批量处理任务。接口参数说明详见 CreateImageAITask。

<?php
include_once(__DIR__ . '../../../../vendor/autoload.php');

use Volc\Service\ImageX\V2\Imagex;

$client = Imagex::getInstance();

// 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
// 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
$client->setAccessKey("ak");
$client->setSecretKey("sk");

$body = [
     "ServiceId" => "5s****fo", // 必选。服务 ID。
     "QueueId" => "649a9dbc32**064d44cf5b0", // 必选。队列 ID。 
     "DataType" => "uri", // 必选。图片地址类型，支持取值 uri 和 url。
     "DataList" => ["a.png", "uridemo.png"], // 必选。图片 URI 或 URL 列表（URI 不包含 tos-*-i-* 前缀）。
     "CallbackConf" => [ // 可选。回调配置。
         "Method" => "HTTP", // 必选。回调方式，取值固定为 HTTP。
         "Endpoint" => "https://demo.com", // 必选。回调地址，用于接收处理结果。
         "DataFormat" => "JSON", // 可选。回调数据格式，支持取值 XML 和 JSON。
         "Args" => "productid", // 可选。业务自定义回调参数。
         "Type" => "task" // 可选。回调触发类型，支持取值 task 和 entry。默认值为 entry。
     ],
     "WorkflowParameter" => "{\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}", // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
     "WorkflowTemplateId" => "system_workflow_ai_bgfill" // 必选。模板 ID。固定取值。
];
$query = [];

$response = $client->CreateImageAITask($query, $body);
print_r($response);

通过以下任一方式获取图像处理结果。

回调通知：如果您在上一步设置了回调地址，则当任务完成后，veImageX 会向该回调地址发送回调消息。详见回调。

主动查询：如果您未设置回调地址，需主动获取图像处理结果。接口参数说明详见 GetImageAIDetails。

<?php
include_once(__DIR__ . '../../../../vendor/autoload.php');

use Volc\Service\ImageX\V2\Imagex;

$client = Imagex::getInstance();

// 强烈建议不要把 ak 和 sk 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
// 本示例通过从环境变量中读取 ak 和 sk，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 ak 和 sk。
$client->setAccessKey("ak");
$client->setSecretKey("sk");

$query = [
     "QueueId" => "649a9dbc32**064d44cf5b0", // 必选。队列 ID。
     "TaskId" => "67174744a**54449623155b9", // 必选。任务 ID。
     "StartTime" => 1684713599, // 必选。查询开始时间。Unix 秒级时间戳。
     "EndTime" => 1684913599, // 必选。查询结束时间。Unix 秒级时间戳。
     "Status" => "Success", // 可选。任务执行状态。默认返回所有任务。
     "SearchPtn" => "test", // 可选。图片 URI 或 URL 关键字。默认返回所有任务。
     "Limit" => 10, // 必选。分页条数。取值范围为 (0, 100]。
     "Offset" => 0, // 可选。分页偏移量。
     "ServiceId" => "5s****fo" // 必选。服务 ID。
];

$response = $client->GetImageAIDetails($query);
print_r($response);

前提条件

调用接口前，请先完成 Node.js SDK 的安装及初始化操作。

同步处理

提交一条 URL 或 URI 资源执行同步 AI 图像处理任务。详见同步处理。

import { imagex } from "@volcengine/openapi";

export async function AIProcessDemo() {
  try {
    const Client = new imagex.ImageXService({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY。
      accessKeyId: process.env.VOLC_ACCESSKEY,
      secretKey: process.env.VOLC_SECRETKEY,
    });

    const requestParam = {
      ServiceId: "91**2g", // 必选。服务 ID。
      WorkflowTemplateId: "system_workflow_ai_bgfill",   // 必选。模板 ID。固定取值。
      WorkflowParameter: "{\"Input\":{\"ObjectKey\":\"example.webp\",\"DataType\":\"uri\"},\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}" // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
    };

    const res = await Client.AIProcess(requestParam);
    console.log("res", res);
  } catch (err) {
    console.error(err);
  }
}

异步处理

创建批量处理任务。接口参数说明详见 CreateImageAITask。

import { imagex } from "@volcengine/openapi";

export async function CreateImageAITaskDemo() {
  try {
    const Client = new imagex.ImageXService({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY。
      accessKeyId: process.env.VOLC_ACCESSKEY,
      secretKey: process.env.VOLC_SECRETKEY,
    });

    const requestParam = {
      ServiceId: "5s****fo", // 必选。服务 ID。
      QueueId: "649a9dbc32**064d44cf5b0", // 必选。队列 ID。 
      DataType: "uri", // 必选。图片地址类型，支持取值 uri 和 url。
      DataList: ["a.png", "uridemo.png"], // 必选。图片 URI 或 URL 列表（URI 不包含 tos-*-i-* 前缀）。
      CallbackConf: { // 可选。回调配置。
        Method: "HTTP", // 必选。回调方式，取值固定为 HTTP。
        Endpoint: "https://demo.com", // 必选。回调地址，用于接收处理结果。
        DataFormat: "JSON",  // 可选。回调数据格式，支持取值 XML 和 JSON。
        Args: "productid",  // 可选。业务自定义回调参数。
        Type: "task",  // 可选。回调触发类型，支持取值 task 和 entry。默认值为 entry。
      },
      WorkflowParameter: "{\"BgfillParam\":{\"Model\":3,\"Top\":0.1,\"Bottom\":0.1,\"Left\":0.1,\"Right\":0.1}}",  // 必选。根据本文模板说明 > 输入参数，设置该参数取值。
      WorkflowTemplateId: "system_workflow_ai_bgfill", // 必选。模板 ID。固定取值。
    };

    const res = await Client.CreateImageAITask(requestParam);
    console.log("res", res);
  } catch (err) {
    console.error(err);
  }
}

通过以下任一方式获取图像处理结果。

回调通知：如果您在上一步设置了回调地址，则当任务完成后，veImageX 会向该回调地址发送回调消息。详见回调。

主动查询：如果您未设置回调地址，需主动获取图像处理结果。接口参数说明详见 GetImageAIDetails。

import { imagex } from "@volcengine/openapi";

export async function GetImageAIDetailsDemo() {
  try {
    const Client = new imagex.ImageXService({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY。
      accessKeyId: process.env.VOLC_ACCESSKEY,
      secretKey: process.env.VOLC_SECRETKEY,
    });

    const requestParam = {
      QueueId: "649a9dbc32**064d44cf5b0", // 必选。队列 ID。
      TaskId: "67174744a**54449623155b9", // 必选。任务 ID。
      StartTime: 1684713599, // 必选。查询开始时间。Unix 秒级时间戳。
      EndTime: 1685913599, // 必选。查询结束时间。Unix 秒级时间戳。
      Status: "Success", // 可选。任务执行状态。默认返回所有任务。
      SearchPtn: "test", // 可选。图片 URI 或 URL 关键字。默认返回所有任务。
      Limit: 10, // 必选。分页条数。取值范围为 (0, 100]。
      Offset: 0, // 可选。分页偏移量。
      ServiceId: "5s****fo", // 必选。服务 ID。
    };

    const res = await Client.GetImageAIDetails(requestParam);
    console.log("res", res);
  } catch (err) {
    console.error(err);
  }
}

方式三：通过控制台操作

在新建模板时，单击附加组件-智能处理 > 智能图像扩展，并完成相关配置。

步骤二：查看结果图

方式一：默认公网加速域名访问结果图

方式二：控制台预览结果图

方式三：手动拼接结果图地址

通过调用服务端 SDK 获取资源地址（推荐）

veImageX 提供了以下编程语言的 SDK，方便您调用 API。详见方式一：通过调用服务端 SDK 获取资源地址（推荐）。

通过控制台获取资源地址

在资源管理页面完成以下操作，获取资源地址。

模板说明

模板 ID

system_workflow_ai_bgfill

输入参数

输入参数需要将 JSON 序列化为字符串后作为 AIProcess 或 CreateImageAITask 接口的 WorkflowParameter 参数传入。

参数	类型	是否必选	示例值	说明
Input	Object	否	-	输入图像的信息。仅在调用同步处理接口 AIProcess 时必选。
BgfillParam	Object	是	-	生成图片参数。

输出参数

veImageX 服务会将输出参数序列化为 JSON 字符串后作为 AIProcess 接口、回调或 GetImageAIDetails 接口的 Output 参数返回。

说明

生成的图像在控制台资源管理页面默认不展示，仅支持通过不包含 tos-*-i-* 前缀的存储 URI 搜索。

参数	类型	示例值	说明
ObjectKey	String	a.webp	生成图像在指定服务 ID 下不包含 `tos--i-` 前缀的存储 URI。
Size	Integer	38656	生成图像的大小，单位为字节。
Format	String	webp	生成图像的格式。

最近更新时间：2026.06.02 19:46:24

这个页面对您有帮助吗？

有用

无用

veImageX

前提条件 #

步骤一：调用 AI 能力 #

方式一：通过 API 调用 #

同步处理

异步处理

方式二：通过服务端 SDK 调用 #

前提条件

同步处理

异步处理

方式三：通过控制台操作 #

步骤二：查看结果图 #

通过调用服务端 SDK 获取资源地址（推荐） #

通过控制台获取资源地址 #

模板 ID #

输入参数 #

输出参数 #

前提条件

步骤一：调用 AI 能力

方式一：通过 API 调用

方式二：通过服务端 SDK 调用

方式三：通过控制台操作

步骤二：查看结果图

通过调用服务端 SDK 获取资源地址（推荐）

通过控制台获取资源地址

模板 ID

输入参数

输出参数