Layer Decomposition API Documentation

The layer decomposition service provides two capabilities: General layer decomposition and Poster layer decomposition. Both services use the same asynchronous workflow: call submit_task to submit a task and obtain task_id, then call query_task to retrieve the result. To generate initial detection boxes before submission, call object_detect.

Service capability comparison

Common request headers

Header	Type	Required	Description
accept	string	Yes	Always application/json
Content-Type	string	Yes	Always application/json
Authorization	string	Yes	Bearer your_key

Image input requirements

input is an image input array in which each item represents one image with the following structure: { "type": "input_image", "image_url": "image_data" }.

Images support image_url input https://xxx.jpg; you can also use data:image/png;base64,base64_str input. URL input currently supports image URLs that begin with HTTP or HTTPS, use a domain name rather than an IP address, and end in jpg, jpeg, png, or bmp. The image’s shortest side must be at least 128 pixels. It must also satisfy the following condition: aspect_ratio the aspect ratio must not exceed 5.0, so extremely elongated images are not supported.

Bounding-box coordinates

image_boxes Use a two-dimensional array in the format [[x1, y1, x2, y2], [x3, y3, x4, y4]]. Coordinates use the image’s upper-left corner as the origin. x1,y1 is the upper-left point and x2,y2 is the lower-right point.

1. Submit a task with submit_task

Submit a layer decomposition task. Once accepted, the service returns task_id, which the client uses to query task status and results.

Request Method

POST /submit_task

Request Body

General layer decomposition request example

{
  "model": "reveal_layer",
  "version": "v2.3.4",
  "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
}

Poster layer decomposition request example

{
  "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

Field	Type	Description
version	string	Same as the input version
model	string	Same as the input model name
timestamp	int	Response timestamp in milliseconds
task_id	string	Task ID used for subsequent queries
message	string	success on success; otherwise, a specific error message
response_status	int	0 on success; -1 on failure

2. Query a task with query_task

Use task_id to query task status.When the task completes, the output field returns layer images, detection boxes, and processed supporting images.

Request Method

POST /query_task

Request Body

Parameter	Type	Required	Description
model	string	Yes	Use reveal_layer for general decomposition and ecommerce_layer for poster decomposition.
version	string	Yes	General layer decomposition传 v2.3.4; Poster layer decomposition传 v1.1
task_id	string	Yes	The exact task ID returned by submit_task

Response

Field	Type	Description
version	string	Same as the input version
model	string	Same as the input model name
timestamp	int	Response timestamp in milliseconds
task_id	string	Task ID being queried
message	string	success on success; otherwise, a specific error message
response_status	int	0 on success; -1 on failure
generation_time	int	Task processing time in seconds; normally greater than 0 after successful completion
remaining_time	float	Estimated remaining processing time in seconds
status	string	Task status; see the status reference below
usage	object	Billing data containing prompt_tokens and total_tokens
output	object/null	Layer decomposition result after completion

status values

Status	Description
done	Processing completed with the expected result
generating	The task is running on the GPU service
in_queue	The task is queued
not_found	Task not found. It may have been lost, submitted more than one month ago, or referenced with an invalid task_id.
failed	The task failed. See message for the reason.

output fields

3. Detect objects with object_detect

Submit an image to receive detection boxes directly. Use this to generate initial boxes before submitting decomposition with boxes.

Request Method

POST /object_detect

Request Body

Parameter	Type	Required	Description
version	string	Yes	通用物体检测传 v2.3.4; 海报物体检测传 v1.1
model	string	Yes	Use reveal_layer for general object detection and ecommerce_layer for poster object detection.
input	object[]	Yes	Image input array using the same item structure as the submit_task input field

General object detection example

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

Poster object detection example

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

Response

Field	Type	Description
version	string	Same as the input version
model	string	Same as the input model name
image_boxes	number[][]	Detected image boxes using the same format as submit_task image_boxes
original_bbox_image	string	URL of the user image with image_boxes overlaid
usage	object	Billing data containing prompt_tokens and total_tokens
message	string	success on success; otherwise, a specific error message
response_status	int	0 on success; -1 on failure