图层分解 API 文档

图层分解服务提供两类能力：通用图层分解与海报图层分解。两类服务共用一套异步调用流程：通过 submit_task 提交任务获取 task_id，再通过 query_task 查询结果；如需在提交任务前生成初始检测框，可调用 object_detect。

服务能力对照

公共请求头

Header	类型	必填	说明
accept	string	是	固定为 application/json
Content-Type	string	是	固定为 application/json
Authorization	string	是	Bearer your_key

图片输入规范

input 为图片输入数组，每个元素表示一张输入图片，结构为 { "type": "input_image", "image_url": "image_data" }。

图片支持 image_url 形式输入 https://xxx.jpg；也可以 data:image/png;base64,base64_str 形式输入。URL 形式输入目前只支持以 http/https 开头、域名非 IP 地址、以 jpg、jpeg、png 或 bmp 结尾的图片 URL。输入图片最短边的像素需要不小于 128，否则报错；同时需要满足 aspect_ratio 最大值不大于 5.0，即不允许输入长条状图片。

坐标框规范

image_boxes 使用二维数组表示，格式为 [[x1, y1, x2, y2], [x3, y3, x4, y4]]。坐标以图片左上角为原点，x1,y1 为左上点，x2,y2 为右下点。

1. submit_task 提交任务

提交图层分解任务。服务端受理后返回 task_id，客户端使用该 ID 查询任务状态与输出结果。

Request Method

POST /submit_task

Request Body

通用图层分解请求示例

{
  "model": "reveal_layer",
  "version": "v2.3",
  "time_out": 3600,
  "input": [
    {
      "type": "input_image",
      "image_url": "https://example.com/input.jpg"
    }
  ],
  "pipeline_type": "crop",
  "image_boxes": [[137, 224, 590, 1022], [523, 59, 988, 1022]],
  "seed": 42,
  "steps": 10
}

海报图层分解请求示例

{
  "model": "ecommerce_layer",
  "version": "v1.1",
  "time_out": 3600,
  "input": [
    {
      "type": "input_image",
      "image_url": "https://example.com/poster.jpg"
    }
  ],
  "pipeline_type": "all",
  "seed": 42,
  "steps": 28
}

Response

字段	类型	说明
version	string	同输入版本
model	string	同输入模型名
timestamp	int	返回时间戳，单位毫秒
task_id	string	可供查询的任务 ID
message	string	成功为 success，失败为具体原因
response_status	int	成功为 0，失败为 -1

2. query_task 查询任务

根据 task_id 查询任务状态。任务完成后，响应中的 output 字段会返回图层图片、检测框和处理后的辅助图片。

Request Method

POST /query_task

Request Body

参数	类型	必填	说明
model	string	是	通用图层分解传 reveal_layer；海报图层分解传 ecommerce_layer
version	string	是	通用图层分解传 v2.3；海报图层分解传 v1.1
task_id	string	是	submit_task 返回的任务 ID，需要完全一致

Response

字段	类型	说明
version	string	同输入版本
model	string	同输入模型名
timestamp	int	返回时间戳，单位毫秒
task_id	string	查询的任务 ID
message	string	成功为 success，失败为具体原因
response_status	int	成功为 0，失败为 -1
generation_time	int	任务生成耗时，单位秒；任务成功时通常大于 0
remaining_time	float	任务预计剩余处理时间，单位秒
status	string	任务状态，见下方状态说明
usage	object	计费字段，包含 prompt_tokens 和 total_tokens
output	object/null	任务完成后的图层分解结果

status 状态

状态	说明
done	任务处理结束并得到期望结果
generating	任务正在 GPU 服务推理
in_queue	任务正在排队
not_found	任务未找到，可能任务丢失、提交超过一个月或 task_id 不存在
failed	任务失败，具体原因查看 message

output 字段

3. object_detect 物体检测

输入图片并直接返回检测框，可用于在提交有框分解前生成初始画框。

Request Method

POST /object_detect

Request Body

参数	类型	必填	说明
version	string	是	通用物体检测传 v2.3；海报物体检测传 v1.1
model	string	是	通用物体检测传 reveal_layer；海报物体检测传 ecommerce_layer
input	object[]	是	图片输入数组，元素结构同 submit_task 的 input 字段

通用物体检测示例

{
  "version": "v2.3",
  "model": "reveal_layer",
  "input": [
    {
      "type": "input_image",
      "image_url": "https://example.com/input.jpg"
    }
  ]
}

海报物体检测示例

{
  "version": "v1.1",
  "model": "ecommerce_layer",
  "input": [
    {
      "type": "input_image",
      "image_url": "https://example.com/poster.jpg"
    }
  ]
}

Response

字段	类型	说明
version	string	同输入版本
model	string	同输入模型名
image_boxes	number[][]	检测出的图片框，格式同 submit_task 的 image_boxes
original_bbox_image	string	用户输入图片和 image_boxes 融合后的带框图片 URL
usage	object	计费字段，包含 prompt_tokens 和 total_tokens
message	string	成功为 success，失败为具体原因
response_status	int	成功为 0，失败为 -1