同步转异步接口使用说明--图像技术-火山引擎

文档中心

导航

同步转异步接口使用说明

最近更新时间：2024.12.19 16:48:21首次发布时间：2024.12.17 14:26:02

介绍

当前商品下的能力已支持通过同步转异步接口进行异步调用，整个调用流程分为两个步骤：1. 使用CVSync2AsyncSubmitTask接口提交任务；2. 使用CVSync2AsyncGetResult接口查询任务结果。
如有异步调用的需求，可参考本文档中提交任务与查询任务两个章节的示例进行调用。

能力列表

本商品下的能力都已支持同步转异步接口调用，下方列表中列举了部分能力

序号	能力接口文档
1	风格化接口文档(按量计费)
2	人像保持
3	......

提交任务

提交任务请求参数

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

请求示例

请在能力列表中找到对应能力的接口文档，参考接口文档进行传参。下方示例为参考图像风格化-精致美漫进行传参。
注：在提交任务时无需传入return_url 与logo_info 参数。

{
    "req_key": "img2img_comic_style",
    "sub_req_key": "img2img_comic_style_marvel",
    "image_urls": [
        "https://xxx"
    ]
}

提交任务返回参数

通用返回参数

请参考通用返回字段及错误码

业务输出参数

重点关注data 字段，其他字段为公共返回

字段	类型	说明
task_id	String	任务ID，用于查询结果（task_id有效期为24小时）

返回示例

{
    "code": 10000,
    "data": {
        "task_id": "7418048504813240370"
    },
    "message": "Success",
    "request_id": "2024092411365866C579D2A96A35DA62A9",
    "status": 10000,
    "time_elapsed": "23.099216ms"
}

查询任务

查询任务请求参数

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	算法名称，请在能力列表中找到对应能力的接口文档，参考接口文档中的算法名称进行传参
task_id	必选	String	任务ID，此字段为提交任务接口中返回的task_id
req_json	可选	JSON String	json序列化后的字符串目前支持水印配置和是否以图片链接形式返回，可在返回结果中添加	"{"logo_info":{"add_logo":true,"position":0,"language":0,"logo_text_content":"这里是明水印内容"},"return_url":true}"

ReqJson(序列化后的结果再赋值给req_json)

配置信息

参数	可选/必选	类型	说明
return_url	可选	bool	输出是否返回图片链接（链接有效期为24小时）
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
opacity	Float	否	水印的不透明度，取值范围0-1，1表示完全不透明，默认0.3
logo_text_content	String	否	明水印自定义内容

请求示例

下方示例中req_key参数为参考图像风格化-精致美漫接口文档中的算法名称进行传参。

{
    "req_key": "img2img_comic_style",
    "task_id": "7418049665255653414",
    "req_json":"{\"logo_info\":{\"add_logo\":true,\"position\":0,\"language\":0,\"opacity\":0.3,\"logo_text_content\":\"这里是明水印内容\"},\"return_url\":true}"
}

查询任务返回参数

通用返回参数

请参考通用返回字段及错误码

业务输出参数

重点关注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小时)

返回示例

{
    "code": 10000,
    "data": {
        "algorithm_base_resp": {
            "status_code": 0,
            "status_message": "Success"
        },
        "binary_data_base64": [
            "/9xxx",  //重点关注此返回，转换后的图片Base64
        ],
        "image_urls": [
            "https://xxx" //重点关注此返回，转换后的图片url
        ]
    },
    "message": "Success",
    "request_id": "202405201722544E4A22904AB5C20B42D5",
    "status": 10000,
    "time_elapsed": "5.849820164s"
}

错误码

（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使用说明