You need to enable JavaScript to run this app.
导航
图像技术
  • 文档首页
    • /图像技术/图像编辑/智能绘图（漫画版）/人像保持接口文档/人像保持异步接口
人像保持异步接口
最近更新时间：2024.12.19 16:49:00首次发布时间：2024.08.22 20:42:14
我的收藏

接口简介

图生图能力，可以保持输出图片的人脸特征与输入「形象图」一致，输出图片风格支持通过「输入图」的风格、「风格图」的风格或文本prompt进行调节。

请求说明

名称

内容

接口地址

https://visual.volcengineapi.com

请求方式

POST

Content-Type

application/json

限制条件

名称

内容

图片要求

  1. 图片格式：JPG(JPEG), PNG, BMP 等常见格式, 建议使用JPG格式.
    最小 128 x 128 像素，最大 4096 x 4096 像素；
  2. base64格式下单张图片最大4.7Mb，2张图最大不超过8Mb.

提交任务

提交任务请求参数

Header参数
完整公共参数列表见 公共参数
本服务Region为cn-north-1； Service为cv
Query参数

拼接到url后的参数，示例：https://visual.volcengineapi.com?Action=CVSync2AsyncSubmitTask&Version=2022-08-31

参数

可选/必选

类型

说明

Action

必选

String

接口名，固定值：
CVSync2AsyncSubmitTask

Version

必选

String

版本号，固定值：2022-08-31

Body参数

业务请求参数，放到request.body中，MIME-Type为application/json

参数

可选/必选

类型

说明

req_key

必选

String

算法名称，取固定值为img2img_anime_accelerated_maintain_id_for_smart_drawing_anime

binary_data_base64

可选

array of String

如果需要传图，与image_urls二选一传入

image_urls

可选

array of String

如果需要传图，与binary_data_base64二选一传入

positive_prompt

可选

String

积极提示词，一般建议预置构图提示词和风格提示词（有特殊要求可联系火山引擎对接同学），同时接收终端用户写入的内容拼接好后传入。
默认值：1girl,beautiful,looking at viewer,portrait,

hyper_switch

可选

加速hyper，文生图加速专用（需要关闭face_switch、facestyle_switch、style_switch），开启后step与cfg失效
默认值：false

seed

可选

int

随机种子，-1为不随机种子；其他为指定随机种子
默认值：-1

step

可选

int

默认值：18

cfg

可选

float

默认值：4.5

face_image

可选

string

输入形象图
格式："uri://binary_data?index=0" （index对应输入图binary_data_base64/image_urls的下标）

未传时
需要关闭face_switch、facestyle_switch、style_switch

style_image

可选

string

输入风格图
格式："uri://binary_data?index=1" （index对应输入图binary_data_base64/image_urls的下标）

未传时
需要关闭style_switch

face_switch

可选

bool

形象图人脸学习开关，打开则学习形象图的人脸特征
默认值：false

facestyle_switch

可选

bool

形象图风格学习开关，打开则学习形象图的风格。facestyle_switch与style_switch强烈建议二选一，否则效果互有干扰且延迟长。
默认值：false

style_switch

可选

bool

风格图的风格学习开关，打开则学习风格图的风格。风格图强烈不建议传入真人图片，可传入动漫人物或风格化明显的图片。
默认值：false

width

可选

int

生成图像的宽
默认值：1000
取值范围[600-1500]

height

可选

int

生成图像的高
默认值：1000
取值范围[600-1500]

提交任务返回参数

（1）通用返回参数
请参考通用返回字段及错误码
（2）业务返回参数
重点关注data 字段，其他字段为公共返回

字段

类型

说明

task_id

String

任务ID，用于查询结果 （task_id有效期为24小时）

提交任务请求&返回完整示例

请求示例：

{
    "req_key": "img2img_anime_accelerated_maintain_id_for_smart_drawing_anime",
    "positive_prompt": "1girl,beautiful,looking at viewer,portrait,",
    "image_urls": [
        "https://xxx"],
    # "binary_data_base64": [],
    "hyper_switch": True,
    "seed": -1,
    "step": 18,
    "cfg": 4.5,
    "face_image": "uri://binary_data?index=0",
    "style_image": "uri://binary_data?index=1",
    "face_switch": True,
    "facestyle_switch": True,
    # "style_switch": False,
    "width": 1000,
    "height": 1000,
}

返回示例：

{
    "code": 10000,
    "data": {
        "task_id": "7392616336519610409"
    },
    "message": "Success",
    "request_id": "20240720103939AF0029465CF6A74E51EC",
    "status": 10000,
    "time_elapsed": "104.852309ms"
}

查询任务

查询任务请求参数

Header参数
完整公共参数列表见 公共参数
本服务Region为cn-north-1； Service为cv
Query参数

拼接到url后的参数，示例：https://visual.volcengineapi.com?Action=CVSync2AsyncGetResult&Version=2022-08-31

参数

可选/必选

类型

说明

Action

必选

String

接口名，固定值：
CVSync2AsyncGetResult

Version

必选

String

版本号，固定值：2022-08-31

Body参数

业务请求参数，放到request.body中，MIME-Type为application/json

参数

可选/必选

类型

说明

示例

req_key

必选

String

算法名称，取固定值为img2img_anime_accelerated_maintain_id_for_smart_drawing_anime

task_id

必选

String

任务ID，此字段的取值为提交任务接口的返回

req_json

可选

JSON String

json序列化后的字符串
目前支持水印配置和图片链接，可在返回结果中添加

"{"logo_info":{"add_logo":true,"position":0,"language":0,"opacity":0.3,"logo_text_content":"这里是明水印内容"},"return_url":true}"

ReqJson(序列化后的结果再赋值给req_json)
配置信息

参数

可选/必选

类型

说明

return_url

可选

bool

输出是否返回图片链接 （链接有效期为24小时）
注：此字段需要加在req_json里

logo_info

可选

LogoInfo

水印信息

LogoInfo
水印相关信息。

名称

类型

必选

描述

备注

add_logo

Boolean

否

是否添加水印。True为添加，False不添加。默认不添加

position

Int

否

水印的位置，取值如下：
0-右下角
1-左下角
2-左上角
3-右上角
默认0

language

Int

否

水印的语言，取值如下：
0-中文（AI生成）
1-英文（Generated by AI）
默认0

logo_text_content

String

否

明水印自定义内容

查询任务返回参数

（1）通用返回参数
请参考通用返回字段及错误码
（2）业务返回参数
重点关注data 字段，其他字段为公共返回

字段

类型

说明

binary_data_base64

Array of string

返回图片的base64数组。

image_urls

Array of string

返回图片的url数组

response_data

String

算法返回的一些信息，可忽略，是json序列化字符串

status

String

in_queue：任务已提交
generating：任务已被消费，处理中
done：处理完成，成功或者失败，可根据外层code&message进行判断
not_found：任务未找到，可能原因是无此任务或任务已过期(12小时)

查询任务请求&返回完整示例

请求示例：

{
  "req_key":"img2img_anime_accelerated_maintain_id_for_smart_drawing_anime",
  "task_id":"<任务提交接口返回task_id>",
  "req_json":"{\"logo_info\":{\"add_logo\":true,\"position\":0,\"language\":0,\"opacity\":0.3,\"logo_text_content\":\"这里是明水印内容\"},\"return_url\":true}"
}

返回示例：

{
    "code": 10000,
    "data": {
        "algorithm_base_resp": {
            "status_code": 0,
            "status_message": "Success"
        },
        "binary_data_base64": ["xxx"],
        "image_urls": [""],
        "request_id": ""
    },
    "message": "Success",
    "request_id": "2024061214082851989A35E4283DB7C8AD",
    "status": 10000,
    "time_elapsed": "16.52978614s"
}

错误码

（1）通用错误码
请参考通用返回字段及错误码
（2）业务错误码

HttpCode

错误码

错误消息

描述

200

10000

无

请求成功

400

50411

Pre Img Risk Not Pass

输入图片前审核未通过

400

50511

Post Img Risk Not Pass

输出图片后审核未通过

400

50412

Text Risk Not Pass

输入文本前审核未通过

400

50512

Post Text Risk Not Pass

输出文本后审核未通过

400

50413

Post Text Risk Not Pass

输入文本NER、IP、Blocklist等拦截

SDK使用说明

请参考SDK使用说明