图层分解 API 文档

图层分解服务通过统一异步任务入口提供整图自动分解和指定区域分解能力。客户端准备图片并选择分解模式，通过 submit_task 提交异步任务，再通过 query_task 查询分层结果。

分解模式

两种模式使用同一个创建接口，沿用当前环境的图层分解单价。模式与框数组必须对应：all 不能携带非空框数组，crop 不能使用空数组。官网会根据是否画框自动选择模式。

请求地址

请求体使用 JSON。成功响应直接返回 task_id、status、output 等字段，读取时无需额外套用 data 层级。

服务能力

公共请求头

图片输入规范

input 为图片输入数组，每次提交一张图片，元素结构为 { "type": "input_image", "image_url": "data:image/png;base64,..." }。

图片支持 JPG、JPEG、PNG、BMP、WEBP。input[].image_url 可填写 HTTP/HTTPS 图片 URL，或完整的 Base64 Data URI，例如 data:image/png;base64,...；不能仅填写本地文件路径。

官网本地上传及图片 URL 均限制为 10MB。API Key 调用不设图片业务大小限制，URL 和 Base64 均支持；仍受网关请求体大小、读取超时及服务资源保护约束。Base64 会增大请求体，请根据网关上限控制编码后的请求大小。

使用图片 URL 时，请提供可读取的 HTTP/HTTPS 图片直链；使用 Base64 时，需携带与图片格式一致的 MIME 前缀，并将示例占位文本替换为真实编码。

坐标框规范

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

有框分解（crop）需提供 1–20 个框，坐标为原始图片上的像素坐标；左上角坐标非负，右下角必须大于左上角。无框分解（all）将 image_boxes 设为 []。

服务端按原图最长边等比缩放至 1024 像素的比例缩放画框；缩放后的每个框最短边须不小于 8 像素，否则报错。

输入框会经过 IoU（交并比）阈值为 0.8 的过滤，因此返回框的数量或顺序可能与输入不同。output.image_boxes 使用原图坐标，output.resized_image_boxes 使用前处理后的图片坐标；output.boxes_mapping_index 在服务返回时给出保留框与输入框的下标映射。

1. 图层分解（创建任务）

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

Request Method

POST /v1/submit_task

Request Body

input.image_url 支持 HTTP/HTTPS 图片 URL 或完整 Base64 Data URI，格式与大小规则见“图片输入规范”。调用方需显式传入分解模式与对应的 image_boxes：无框传 []，有框传 1–20 个坐标框。

请求示例

图层分解（创建任务：无框）

{
  "model": "reveal_layer",
  "request_id": "requestId-xxxxxxxx",
  "input": [
    {
      "type": "input_image",
      "image_url": "data:image/png;base64,REPLACE_WITH_IMAGE_BASE64"
    }
  ],
  "pipeline_type": "all",
  "image_boxes": [],
  "steps": 10,
  "seed": 42
}

图层分解（创建任务：有框）

{
  "model": "reveal_layer",
  "request_id": "requestId-xxxxxxxx",
  "input": [
    {
      "type": "input_image",
      "image_url": "data:image/png;base64,REPLACE_WITH_IMAGE_BASE64"
    }
  ],
  "pipeline_type": "crop",
  "image_boxes": [
    [
      20,
      20,
      200,
      240
    ]
  ],
  "steps": 10,
  "seed": 42
}

Response

响应示例

{
  "model": "reveal_layer",
  "response_status": 0,
  "message": "success",
  "status": "in_queue",
  "task_id": "taskId-xxxxxxxx",
  "request_id": "requestId-xxxxxxxx",
  "output": {}
}

2. 图层分解（查询任务）

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

Request Method

POST /v1/query_task

Request Body

请求示例

{
  "model": "reveal_layer",
  "task_id": "taskId-xxxxxxxx",
  "request_id": "requestId-xxxxxxxx"
}

Response

status 状态

output 字段

usage 字段

响应示例

{
  "model": "reveal_layer",
  "response_status": 0,
  "message": "success",
  "status": "done",
  "task_id": "taskId-xxxxxxxx",
  "request_id": "requestId-xxxxxxxx",
  "generation_time": 62,
  "remaining_time": 0,
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 10000
  },
  "output": {
    "layers_base_count": 2,
    "layers_base": [
      "https://beijing2.xstore.qihu.com/example/background.png",
      "https://beijing2.xstore.qihu.com/example/layer.png"
    ],
    "layers_aug": [
      "https://beijing2.xstore.qihu.com/example/background_aug.png",
      "https://beijing2.xstore.qihu.com/example/layer_aug.png"
    ],
    "layers_fg_mask": [
      "https://beijing2.xstore.qihu.com/example/mask.png"
    ],
    "resized_bbox_image": "https://beijing2.xstore.qihu.com/example/boxes.png",
    "resized_image": "https://beijing2.xstore.qihu.com/example/input.png",
    "image_boxes": [
      [
        20,
        20,
        200,
        240
      ]
    ],
    "resized_image_boxes": [
      [
        16,
        16,
        160,
        192
      ]
    ],
    "boxes_mapping_index": [
      0
    ]
  }
}

图层分解（物体检测）

检测图片中的可拆分对象，同步返回初始画框；无需轮询此接口。可调整检测框后通过创建任务接口进行分解。检测结果不保证覆盖所有对象，未检测到对象时可手动补框或使用无框分解。

Request Method

POST /v1/object_detect

Request Body

检测无需传入 pipeline_type、image_boxes、steps 或 seed；版本、product 及内部鉴权由服务端按环境配置。

请求示例

{
  "model": "reveal_layer",
  "request_id": "replace-with-a-unique-detect-request-id",
  "input": [
    {
      "type": "input_image",
      "image_url": "data:image/png;base64,REPLACE_WITH_IMAGE_BASE64"
    }
  ]
}

Response

画框使用 [x1, y1, x2, y2] 像素坐标。若返回缩放图片对应的框，应按对应图片尺寸换算到原图再提交；不可直接将缩放图坐标作为原图坐标。创建有框任务最多支持 20 个框，检测框超出时先删除多余画框。

响应示例

{
  "model": "reveal_layer",
  "request_id": "replace-with-a-unique-detect-request-id",
  "response_status": 0,
  "message": "success",
  "output": {
    "original_bbox_image": "https://beijing2.xstore.qihu.com/example/detected.png",
    "image_boxes": [
      [
        20,
        20,
        200,
        240
      ]
    ]
  },
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 100
  }
}