图生图--veImageX-火山引擎

文档中心

立即注册

导航

图生图

最近更新时间：2024.11.15 13:53:28首次发布时间：2024.11.08 11:15:13

该接口支持调用豆包大模型中的智能生图 API 能力，并根据豆包模型请求信息生成相应的一张图片。同时您可指定 veImageX 的图片处理模板，对智能生成的图片进行进一步的个性化图片处理，获取同步输出的结果图。

使用说明

本段主要介绍如何获取调用时的参数信息，以及获取后在本接口的具体传参位置。

获取 veImageX 配置信息：服务 IDServiceId、域名Domain、模版配置Template。
根据所选通用 XL pro-图生图模型对应的接口文档，完成 ModelAction、ModelVersion 和 ReqJson 这个三个参数的填写。
根据实际业务需要，指定输出图的文件名Outputs。
指定一张参考图ImageUrl，指定后将优先使用该图和提示词智能生图。

注意事项

前提条件：请确保已完成准备操作。
输入原图限制：
- 支持的原图格式：jpeg、png、webp、bmp、heic、apng、ico、avif
- 支持的图片体积：不超过 35 MB
请求频率：请遵循豆包大模型中的智能绘图的 QPS 限制。
超时时间：超时时间为 30 秒。
服务地址：veImageX 在全球多个区域部署，每个区域有自己对应的 OpenAPI 域名，不支持跨区域调用。具体详情请查看服务地址。

请求说明

请求方式：POST
请求地址：https://imagex.volcengineapi.com/?Action=GetCVImageGenerateResult&Version=2023-05-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

参数类型是否必选示例值描述

Action String 是 GetCVImageGenerateResult 接口名称。当前 API 的名称为 GetCVImageGenerateResult。

Version String 是 2023-05-01 接口版本。当前 API 的版本为 2023-05-01。

参数	类型	是否必选	示例值	描述
Action	String	是	`GetCVImageGenerateResult`	接口名称。当前 API 的名称为 `GetCVImageGenerateResult`。
Version	String	是	`2023-05-01`	接口版本。当前 API 的版本为 `2023-05-01`。
ServiceId	String	是	`serviceid`	指定存储结果图并计量计费的服务 ID。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。

ServiceId

String

是

serviceid

指定存储结果图并计量计费的服务 ID。

您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。
您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。

Body

参数	类型	是否必选	示例值	描述
Domain	String	是	`test.example.com`	服务下绑定的域名，域名状态需正常可用。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取绑定的域名信息。您也可以通过 OpenAPI 的方式获取域名，具体请参考获取服务下全部域名。
Template	String	是	`tplv-serviceid-test.image`	服务下创建的图片处理模板配置（不带~），指定后，将按照模板中的处理配置对豆包大模型生成的图片进行图片处理。您可在 veImageX 控制台的处理配置页面，参考新建模板配置模板并获取模版信息，例如 `tplv-f0****5k-test.image`。
Outputs	Array of String	是	`["demo1"]`	指定输出图片的文件名，输入限制如下所示：数组长度为 1，若指定多个文件名，仅第一个取值生效。不支持空格。不支持以/开头或结尾，不支持/连续出现，最大长度限制为 180 个字节。
Overwrite	Boolean	否	`true`	是否覆盖服务下同名文件，取值如下所示： `true`：覆盖 `false`：（默认）不覆盖说明请确保您已开启重名覆盖上传功能，否则，此处配置无效。
ImageUrl	String	否	`http://app1.cpm/example.jpg`	基于该图片智能生图，支持传入该服务下的图片存储 URI 或公网访问 URL。图片输入限制请参考注意事项。说明指定 `ImageUrl` 后，`ReqJson` 中指定的图片地址无效。
ModelAction	String	是	`Img2ImgXLSft`	通用 XL pro-图生图模型接口的 Action 名称，即 `Img2ImgXLSft`。
ModelVersion	String	是	`2022-08-31`	通用 XL pro-图生图模型接口的 Version 名称，即 `2022-08-31`。
ReqJson	JSON Map	是	详见描述内取值示例	通用 XL pro-图生图模型接口的请求 JSON 字符串。按照豆包图生图的接口文档可知，若仅指定必填参数，那么 ReqJson 传值示例如下所示： `{ "req_key": "i2i_xl_sft", "image_urls": [ "https://xxx" ], "prompt": "黄色的花朵，蝴蝶飞舞" }` 说明您可忽略 `return_url`，该参数的取值并不会影响最终返回的结果图地址的类型。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数类型示例值描述

ImageUrls Array of String ["http://test.example.cn/demo1~tplv-serviceid-image.image"] 最终上传至 veImageX 服务的结果图访问 URL，数量为 1。

StoreUris Array of String ["tos-cn-i-serviceid/demo1"] 最终上传至 veImageX 服务的结果图存储 URI，数量为 1。

参数	类型	示例值	描述
ImageUrls	Array of String	`["http://test.example.cn/demo1~tplv-serviceid-image.image"]`	最终上传至 veImageX 服务的结果图访问 URL，数量为 1。
StoreUris	Array of String	`["tos-cn-i-serviceid/demo1"]`	最终上传至 veImageX 服务的结果图存储 URI，数量为 1。
RespJson	JSON Map	详见描述内取值示例	根据指定的通用 XL pro-图生图模型接口信息，接收的该接口响应的 JSON 数据。豆包文生图的响应参数如下所示： `{ "code": 10000, "data": { "algorithm_base_resp": { "status_code": 0, "status_message": "Success" }, "binary_data_base64": [], "comfyui_cost": 11, ... "style_reference_args.binary_data_index": 0, "style_reference_args.id_weight": 0.2, "style_reference_args.style_weight": 0, "width": 1024 }, "message": "Success", "request_id": "20240809145732F1B86B6E94464D05716A", "status": 10000, "time_elapsed": "12.696326169s" }`

RespJson

JSON Map

详见描述内取值示例

根据指定的通用 XL pro-图生图模型接口信息，接收的该接口响应的 JSON 数据。
豆包文生图的响应参数如下所示：

{
    "code": 10000,
    "data": {
        "algorithm_base_resp": {
            "status_code": 0,
            "status_message": "Success"
        },
        "binary_data_base64": [],
        "comfyui_cost": 11,
        ...
        "style_reference_args.binary_data_index": 0,
        "style_reference_args.id_weight": 0.2,
        "style_reference_args.style_weight": 0,
        "width": 1024
    },
    "message": "Success",
    "request_id": "20240809145732F1B86B6E94464D05716A",
    "status": 10000,
    "time_elapsed": "12.696326169s"
}

请求示例

POST https://imagex.volcengineapi.com/?Action=GetCVImageGenerateResult&Version=2023-05-01&ServiceId=serviceid
{
    "Domain": "test.example.com",
    "Template": "tplv-serviceid-test.image",
    "Outputs": [
        "demo1"
    ],
    "ReqJson": {
        "req_key": "i2i_xl_sft",
        "image_urls": [
            "https://xxx"
        ],
        "prompt": "美女"
    },
    "ModelAction": "Img2ImgXLSft",
    "ModelVersion": "2022-08-31"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "GetCVImageGenerateResult",
        "Version": "2023-05-01",
        "Service": "ImageX",
        "Region": "cn-north-1"
    },
    "Result": {
        "RespJson": {},
        "ImageUrls": [
            "http://test.example.cn/demo1~tplv-serviceid-image.image"
        ],
        "StoreUris": [
            "tos-cn-i-serviceid/demo1"
        ]
    }
}

错误码

本接口无特有的错误码。更多信息请见公共错误码和 veImageX 错误码。

服务端 SDK

veImageX 提供了配套的开发工具集 SDK，支持多种编程语言，帮助您更方便的调用 API。