FLUX-Makeup API Documentation

FLUX-Makeup provides asynchronous image editing: AI Makeup. Use an asynchronous flow: call submit_task to submit a task and receive a task_id, then use query_task to retrieve its status and generated images.

Capabilities

Common Request Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <YOUR_TOKEN>
accept	string	Optional for makeup	Recommended: application/json
Content-Type	string	Yes	Must be application/json

Image Requirements

AI makeup uses source_image_url and template_image_url.

• image_url supports HTTP/HTTPS image URLs.
• For URLs, use a domain name rather than an IP address and a jpg, jpeg, png or bmp extension.
• Maximum input size: 1024 x 1024. Use a well-lit portrait with one unobstructed face.
• Makeup requires a source portrait and a makeup reference image.

1. Submit a task with submit_task

Submit an image editing task. The server returns a task_id, which the client uses to query the task status and results.

Request Method

POST /v1/submit_task

Request Body

Image Field Mapping

The public makeup API uses source_image_url and template_image_url; no need to supply the input array. The table below shows the corresponding upstream image types.

Public field	Equivalent input entry	Applies to	Description
source_image_url	{ "type": "input_image", "image_url": "..." }	AI Makeup	Source portrait.
template_image_url	{ "type": "template_image", "image_url": "..." }	AI Makeup	Makeup reference image.

Makeup Request Example

{
  "model": "makeup",
  "time_out": 3600,
  "post_level": 1,
  "seed": 42,
  "source_image_url": "https://p0.ssl.qhimg.com/d/inn/0f8fe14174ba/23.png",
  "template_image_url": "https://p3.ssl.qhimg.com/d/inn/2457abe9177f/2ref.png"
}

Response

Platform responses may be wrapped in data. The main fields for a successful submission are listed below.

Field	Type	Description
version	string	The makeup service returns its actual version, v4.8.
model	string	The makeup service returns makeup_transfer.
task_id	string	Task ID used to query results.
message	string	success on success; an error description on failure.
response_status	int	0 on success; -1 on failure.

2. Query a task with query_task

Use task_id to query task status. When complete, output contains the resulting images.

Request Method

POST /v1/query_task

Request Body

Parameter	Type	Required	Description
request_id	string	Optional for makeup	Unique query request ID; UUID4 is recommended. Generated by the platform when omitted, or forwarded when supplied.
model	string	Recommended for makeup	Match the submitted task: makeup (makeup_transfer is also accepted).
task_id	string	Yes	The exact task ID returned by submit_task.

Query Request Example

{
  "model": "makeup",
  "task_id": "flux-task-makeup-xxxxxxxx"
}

Response

Platform responses may be wrapped in data. The main query response fields are listed below.

Field	Type	Description
version	string	The makeup service returns its actual version, v4.8.
model	string	The makeup service returns makeup_transfer.
task_id	string	Task ID being queried.
message	string	success on success; an error description on failure.
response_status	int	0 on success; -1 on failure.
generation_time	number	Generation time in seconds; usually greater than 0 on success.
remaining_time	number	Estimated remaining processing time in seconds.
status	string	Task status; see the descriptions below.
image_urls	string[]	List of result image URLs when the task completes.
usage	object	Usage fields, including prompt_tokens and total_tokens.
output	string[]	Returns string[], matching image_urls.

Task Status

Status	Description
done	Task completed successfully.
generating	GPU inference is in progress.
in_queue	Task is queued.
not_found	Task not found. It may be missing, older than one month, or have an invalid task_id.
failed	Task failed. See message for details such as a timeout, GPU service error or invalid image.

Output

Capability	Type	Description
AI Makeup	string[]	Matches image_urls: URLs of images with transferred makeup. Default: 1 image.