# 一、接口概述通过LUMI发布并接入能力后，可通过本文档对接相关的api服务。本接口为企业级算法服务提供通用接入能力，支持异步任务提交、同步处理请求、任务结果查询、任务取消等核心功能。适用于需要对图片等多媒体数据进行算法处理的业务场景。 LUMI的服务发布教程请参考 [Lumi 一键部署操作手册](https://www.volcengine.com/docs/85128/1587789)。 # 二、基础信息 **接入前准备：** 1、你的AccessKey和你的SecretKey可通过https://console.volcengine.com/iam/keymanage/创建并获取。 2、请提前接入火山引擎sdk，并获取签名密钥进行请求者身份验证，在请求中携带签名信息，接入方法参考：https://www.volcengine.com/docs/6369/67269 ### 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** | |^^|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的方式提交异步任务： ```Shell curl --location 'http://visual.volcengineapi.com?Action=LumiSync2AsyncSubmitTask&Version=2025-06-01' \ --header 'Authorization: 你的Authorization' \ --header 'Region: cn-north-1' \ --header 'ServiceName: cv' \ --header 'Content-Type: application/json' \ --header 'get-svc: 1' \ --data '{ "req_key": "hy_test_lumi_onedeploy_mingxinp_v1", "req_json":{ "input_text": "你好呀", "seed": 1, "input_image": "uri://binary_data?index=0" }, "binary_data": [ "图片1的base64" ] }' ``` 通过data_source的方式提交异步任务： ```Shell curl --location 'http://visual.volcengineapi.com?Action=LumiSync2AsyncSubmitTask&Version=2025-06-01' \ --header 'Authorization: 你的Authorization' \ --header 'Region: cn-north-1' \ --header 'ServiceName: cv' \ --header 'Content-Type: application/json' \ --header 'get-svc: 1' \ --data '{ "req_key": "hy_test_lumi_onedeploy_mingxinp_v1", "req_json":{ "input_text": "你好呀", "seed": 1, "input_image": "uri://binary_data?index=0" }, "data_source": [ { "data_source_type":1, "value":"图片url" } ] }' ``` 命令执行完成后，获得以下结果： ```JSON { "code": 0, "message": "", "data": { "task_id": "14468076912309597066", "resp_json": "" }, "request_id": "202506031700371C156D18803F25334BFC" } ``` ### 3.2 同步处理请求 **LumiProcess** #### 3.2.1 功能描述同步调用算法处理（适用于轻量级任务，响应直接返回结果，默认超时30s，超过30s的任务将会返回失败，请评估自身的资源情况选择调用，推荐选择异步请求的方式）。 #### 3.2.2 请求参数（ProcessReq） | |参数名 |类型 |是否必填 |说明 | |---|---|---|---|---| |**Query**|Action |String |是 |接口名称，值：**LumiProcess** |\ | | | | | | |^^|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的方式提交异步任务： ```Shell curl --location 'http://visual.volcengineapi.com?Action=LumiProcess&Version=2025-06-01' \ --header 'Authorization: 你的Authorization' \ --header 'Region: cn-north-1' \ --header 'ServiceName: cv' \ --header 'Content-Type: application/json' \ --header 'get-svc: 1' \ --data '{ "req_key": "hy_test_lumi_onedeploy_mingxinp_v1", "req_json":{ "input_text": "你好呀", "seed": 1, "input_image": "uri://binary_data?index=0" }, "binary_data": [ "图片1的base64" ] }' ``` 通过data_source的方式提交异步任务： ```Shell curl --location 'http://visual.volcengineapi.com?Action=LumiProcess&Version=2025-06-01' \ --header 'Authorization: 你的Authorization' \ --header 'Region: cn-north-1' \ --header 'ServiceName: cv' \ --header 'Content-Type: application/json' \ --header 'get-svc: 1' \ --data '{ "req_key": "hy_test_lumi_onedeploy_mingxinp_v1", "req_json":{ "input_text": "你好呀", "seed": 1, "input_image": "uri://binary_data?index=0" }, "data_source": [ { "data_source_type":1, "value":"图片url" } ] }' ``` 命令执行完成后，获得以下结果： ```JSON { "code": 0, "message": "", "request_id": "2025060316510263209B2543B40032B4A0", "data": { "binary_data": ["返回的图片1base64","返回的图片2base64",], "resp_json": "{\"output_image\": [\"uri://binary_data?index=0\"], \"comfyui_cost\": 0}" } } ``` ### 3.3 批量获取任务结果 **LumiSync2AsyncBatchGetResults** #### 3.3.1 功能描述通过任务ID批量查询异步任务状态及结果。 #### 3.3.2 请求参数（GetResultReq） | |参数名 |类型 |是否必填 |说明 | |---|---|---|---|---| |**Query** |Action |String |是 |接口名称，值：**LumiSync2AsyncBatchGetResults** | |^^|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 |算法错误信息（失败时返回） | #### 示例通过task_id查询： ```Shell curl --location 'http://visual.volcengineapi.com?Action=LumiSync2AsyncBatchGetResults&Version=2025-06-01' \ --header 'Authorization: 你的Authorization' \ --header 'Region: cn-north-1' \ --header 'ServiceName: cv' \ --header 'Content-Type: application/json' \ --header 'get-svc: 1' \ --data '{ "task_ids": ["14468076912309597066"] }' ``` 命令执行完成后，获得以下结果： ```JSON { "code": 0, "message": "", "data": { "results": [ { "binary_data": [], "resp_json": "{\"output_image\": [\"uri://binary_data?index=0\"], \"comfyui_cost\": 133}", "status": "done", "callback_args": "", "progress": 0, "req_json": "{\"input_image\":\"uri://binary_data?index=0\",\"input_text\":\"你好呀\",\"seed\":13}", "task_id": "14468076912309597066", "submit_timestamp_ms": 1748941238332, "process_start_timestamp_ms": 1748941238388, "process_end_timestamp_ms": 1748941252489, "req_key": "hy_test_lumi_onedeploy_mingxinp_v1", "algo_status_code": 0, "algo_status_message": " <- [返回]消息=Success:Success" } ] }, "request_id": "202506031700531C156D18803F2533520C" } ``` ### 3.4 批量取消任务 **LumiSync2AsyncBatchCancelTasks** #### 3.4.1 功能描述批量取消未开始处理的异步任务。 #### 3.4.2 请求参数（CancelTaskReq） | |参数名 |类型 |是否必填 |说明 | |---|---|---|---|---| |**Query** |Action |String |是 |接口名称，值：**LumiSync2AsyncBatchCancelTasks** | |^^|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查询： ```Shell curl --location 'http://visual.volcengineapi.com?Action=LumiSync2AsyncBatchCancelTasks&Version=2025-06-01' \ --header 'Authorization: 你的Authorization' \ --header 'Region: cn-north-1' \ --header 'ServiceName: cv' \ --header 'Content-Type: application/json' \ --header 'get-svc: 1' \ --data '{ "task_ids": ["14468076912309597066"] }' ``` 命令执行完成后，获得以下结果： ```JSON { "code": 0, "message": "", "data": { "failed_task_ids": [] }, "request_id": "202506031713241DA91B56FDF0AA32030D" } ``` # 四、请求规范 ### 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|Invalid Param |参数错误 |\ |30432| | |\ |30400 | | | |30404 |FeatNotFound |能力不存在 | |21001|Image Decode Error |图片解码错误 |\ |30431 | | | |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=\*

智能视觉服务