一、接口概述

通过LUMI发布并接入能力后，可通过本文档对接相关的api服务。本接口为企业级算法服务提供通用接入能力，支持异步任务提交、同步处理请求、任务结果查询、任务取消等核心功能。适用于需要对图片等多媒体数据进行算法处理的业务场景。

LUMI的服务发布教程请参考 Lumi 一键部署操作手册。

二、基础信息

接入前准备：

1、你的AccessKey和你的SecretKey可通过https://console.volcengine.com/iam/keymanage/创建并获取。

2、接入方法参考：https://www.volcengine.com/docs/86081/2179673?lang=zh

2.1 请求域名

visual.volcengineapi.com

2.2 请求方法

POST（所有接口均使用此方法）

三、核心接口说明

3.1 异步提交算法任务 LumiSync2AsyncSubmitTask

3.1.1 功能描述

提交异步处理任务，支持图片Base64或公网可访问资源 url，返回任务ID。

3.1.2 请求参数（SubmitTaskReq）

	参数名	类型	是否必填	说明
Query	Action	String	是	接口名称，值：LumiSync2AsyncSubmitTask
Query		Version	String	是	接口版本，值：2025-06-01
Header	ServiceName	String	是	cv
		Region	String	是	cn-north-1
		Authorization	String	是	签名密钥，签名方法参考：https://www.volcengine.com/docs/6369/67269
		Content-Type	String	是	application/json
Body	req_key	string	是	请求唯一标识（一键部署的自定义的能力名称）
		res_quota_name	string	是	请求资源名称
		binary_data	[]string	否	图片类文件Base64列表（如果有文件的情况下，与data_source二选一，至少传其一） Base64图片限制大小为8M以内，超出大小限制，则会报错：400，Error when parsing request
		req_json	json	是	JSON格式的业务参数，获取方式参考：可以在服务详情接口信息看到开槽的参数，也就是请求 Openapi 需要传入的算法参数。可以在 demo 示例看到 req_json 的示例
		expired_duration	*int64	否	任务过期时间（毫秒，可选，默认根据服务配置处理）
		data_source	[]*common.DataSource	否	数据源链接列表（支持HTTP/HTTPS链接，图片需可下载，否则返回参数错误）

DataSource结构：

参数名	类型	是否必填	说明
data_source_type	int64	是	默认填1
value	string	是	数据来源类型为 url 时，value 为可下载 url；链接黑名单域名请见下方规范。

3.1.3 响应参数（SubmitTaskResp）

参数名	类型	说明
task_id	string	任务ID（用于后续结果查询或取消任务）
resp_json	string	初步响应结果（可能包含算法预处理信息）

示例

通过binary_data的方式提交异步任务：

通过data_source的方式提交异步任务：

命令执行完成后，获得以下结果：

3.2 同步处理请求 LumiProcess

3.2.1 功能描述

同步调用算法处理（适用于轻量级任务，响应直接返回结果，默认超时30s，超过30s的任务将会返回失败，请评估自身的资源情况选择调用，推荐选择异步请求的方式）。

3.2.2 请求参数（ProcessReq）

	参数名	类型	是否必填	说明
Query	Action	String	是	接口名称，值：LumiProcess
Query		Version	String	是	接口版本，值：2025-06-01
Header	ServiceName	String	是	cv
		Region	String	是	cn-north-1
		Authorization	String	是	签名密钥，签名方法参考：https://www.volcengine.com/docs/6369/67269
		Content-Type	String	是	application/json
Body	req_key	string	是	请求唯一标识
		res_quota_name	string	是	请求资源名称
		binary_data	[]string	否	图片Base64列表（与data_source二选一，至少传其一）
		req_json	json	是	JSON格式的业务参数，获取方式参考：可以在服务详情接口信息看到开槽的参数，也就是请求 Openapi 需要传入的算法参数。可以在 demo 示例看到 req_json 的示例
		data_source	[]*common.DataSource	否	数据源链接列表

DataSource结构：

参数名	类型	是否必填	说明
data_source_type	int64	是	默认填1
value	string	是	数据来源类型为 url 时，value 为可下载 url；链接黑名单域名请见下方规范。

3.2.3 响应参数（AlgoResp）

参数名	类型	说明
binary_data	[][]byte	二进制结果（如图像处理后的文件）
resp_json	string	JSON格式的算法结果（核心业务数据）

示例

通过binary_data的方式提交异步任务：

通过data_source的方式提交异步任务：

命令执行完成后，获得以下结果：

3.3 批量获取任务结果 LumiSync2AsyncBatchGetResults

3.3.1 功能描述

通过任务ID批量查询异步任务状态及结果。

3.3.2 请求参数（GetResultReq）

	参数名	类型	是否必填	说明
Query	Action	String	是	接口名称，值：LumiSync2AsyncBatchGetResults
Query		Version	String	是	接口版本，值：2025-06-01
Header	ServiceName	String	是	cv
		Region	String	是	cn-north-1
		Authorization	String	是	签名密钥，签名方法参考：https://www.volcengine.com/docs/6369/67269
		Content-Type	String	是	application/json
Body	task_ids	[]string	是	待查询的任务ID列表

3.3.3 响应参数（BatchGetResultResp）

参数名	类型	说明
results	[]*GetResultRespV2	任务结果列表（按任务ID对应）

GetResultRespV2 字段说明：

参数名	类型	说明
task_id	string	任务ID
status	string	任务状态枚举： in_queue：任务已提交 generating：任务已被消费，处理中 done：处理完成。注意：只有处理完成，才需要根据algo_status_code查看具体结果！！！否则StatusCode无效！！！ not_found：任务未找到，可能原因是无此任务或任务已过期(24小时) expired：任务已达到设置的过期时间 canceled：任务已被取消 over_max_retries：已达到最大重试次数
progress	int64	任务进度（0-100，仅异步任务返回）
req_json	string	提交任务时的原始业务参数
submit_timestamp_ms	int64	任务提交时间（毫秒级时间戳）
process_start_timestamp_ms	int64	任务开始处理时间（毫秒级时间戳）
process_end_timestamp_ms	int64	任务结束时间（毫秒级时间戳，仅任务完成后返回）
algo_status_code	int32	算法状态码（0为成功，非0需参考错误码文档）
algo_status_message	string	算法错误信息（失败时返回）
status_code	int32	错误码（0为成功，非0需参考错误码文档）
status_message	string	状态信息

示例

通过task_id查询：

命令执行完成后，获得以下结果：

3.4 批量取消任务 LumiSync2AsyncBatchCancelTasks

3.4.1 功能描述

批量取消未开始处理的异步任务。

3.4.2 请求参数（CancelTaskReq）

	参数名	类型	是否必填	说明
Query	Action	String	是	接口名称，值：LumiSync2AsyncBatchCancelTasks
Query		Version	String	是	接口版本，值：2025-06-01
Header	ServiceName	String	是	cv
		Region	String	是	cn-north-1
		Authorization	String	是	签名密钥，签名方法参考：https://www.volcengine.com/docs/6369/67269
		Content-Type	String	是	application/json
Body	task_ids	[]string	是	待取消的任务ID列表

3.4.3 响应参数（BatchCancelTaskResp）

参数名	类型	说明
failed_task_ids	[]string	取消失败的任务ID列表（通常因任务已开始处理导致）

示例

通过task_id查询：

命令执行完成后，获得以下结果：

四、请求规范

4.1 数据格式

请求体：使用JSON格式，参数需与接口定义一致（注意字段大小写与文档保持一致，如req_key而非ReqKey）。

文件传输：图片Base64需确保编码正确（不含data:image/...前缀），数据源链接需保证公网可访问。

4.2 错误码解释

成功

StatusCode	StatusMessage	说明
0	Success	成功

内部错误

算法特定错误码通过code返回。

StatusCode	StatusMessage	说明
10000	Internal Error	异常内部错误，主要是网关调算法服务的报错，常见是超时
10001	RPC Internal Error	下游算法服务异常内部错误，如算法服务调其子服务超时、服务崩溃等
10002	Downstream RPC Service No Targets Found Error	网关未发现下游实例导致的报错。请检查自己的res_quota_name是否填写正确。若请求来自于PPE，则只会去发现同机房下游算法实例；若请求来自于非PPE，则只会发现prod环境下游算法实例。
10003	ECRetryInternal	异常内部错误。网关设置了重试，请求打到算法后connect成功但最终因为超时等原因失败报错。
10004		缺少req_key，报错： "message": "input validate failed: Key: 'SubmitTaskReq.ReqKey' Error:Field validation for 'ReqKey' failed on the 'required' tag" 缺少req_json，报错："input validate failed: Key: 'SubmitTaskReq.ReqJson' Error:Field validation for 'ReqJson' failed on the 'required' tag"
30402	ErrCodeBizError	服务异常，请联系客服人员排查问题

限流错误

StatusCode	StatusMessage	说明
11000	Req over limit	请求触发网关限流，一般是因为算法资源不足所以设置限流来保障服务稳定性。
11001	ECReqConFailed	算法单实例BACKLOG限流错误。网关设置重试+算法服务设置单实例BACKLOG后，连接失败（1115等连接错误）。一般是因为算法资源不足所以设置限流来保障服务稳定性。

输入错误

StatusCode	StatusMessage	说明
20000	RPC Process Error: {err_msg}, rpc service err_code={rpc_err_code}	算法服务识别到的非通用输入错误
21000 30432 30400	Invalid Param	参数错误
30404	FeatNotFound	能力不存在
21001 30431	Image Decode Error	图片解码错误
21002	Image Empty	传入图片为空
21003	Invalid Image	传入图片算法无法处理
22000	No Face Detected	图片中没有检测到人脸
22001	No Man Detected	图片中没有检测到人

审核错误

StatusCode	StatusMessage	说明
23001	Pre Img Risk Not Pass	输入图片前审核未通过
23002	Post Img Risk Not Pass	输出图片后审核未通过
23003	Text Risk Not Pass	输入文本前审核未通过
23004	Post Text Risk Not Pass	输出文本后审核未通过
23005	Post Text Risk Not Pass	敏感词服务拦截（一般用于版权词审核）
23006	Pre Video Risk Not Pass	输入视频前审核未通过
23007	Post Video Risk Not Pass	输出视频后审核未通过
23008	Pre Audio Risk Not Pass	输入音频前审核未通过
23009	Post Audio Risk Not Pass	输出音频后审核未通过
23010	Pre Image Copyright Not Pass	输入版权图前审核未通过
23011	Post Image Copyright Not Pass	输出版权图后审核未通过
23100	ECRiskInternal	审核服务异常
23101	ECAntidirtInternal	版权词服务异常
23102	ECImgCopyrightInternal	版权图服务异常

鉴权错误

StatusCode	StatusMessage	说明
24000	Ability Auth failed	能力级别认证未通过
30403	NoFeatAuth	没有能力权限
24001	Application Auth failed	通用认证未通过
24002	Sign Auth failed	签名错误
24003	Authorization failed	访问授权未通过
24004	SignAuth Time Expired	验签时间戳过期

4.3 图片等附件与req_json的顺序对应关系

req_json请求字段中的值uri://binary_data?index=0代表binary_data列表中的索引。如果选择使用data_source传递url作为req_json中某个字段的值，在内部会先转化为binary_data，再匹配对应req_json位置的uri://binary_data?index=*

图像生成大模型