Skip to navigation
API referenceHair

Submit a Hair color try-on Job

Draft color try-on. Request names one source image Asset and a two-stop color gradient; the server finds the hair in the photo and recolours only that. A caller with its own segmentation may add one hair_mask Asset instead: it must match source dimensions, zero pixels mean background and nonzero pixels mean hair. No haircut style, length or shape transfer is performed. Every input is snapshotted into the job. Idempotency semantics match Makeup try-on.

Authentication

X-API-Keystring

API key for one environment of your account. Keep server-side; never expose in browser clients.

Headers

Idempotency-Keystring or nullOptional

Request

This endpoint expects an object.
color_gradientobjectRequired

Two-stop palette mapped against source hair luminance.

inputslist of objectsRequired

Response headers

Cache-ControlstringOptional
API responses are private to the caller and not cacheable
Idempotency-ReplayedenumOptional
True when this response reuses an existing job
Allowed values:
LocationstringOptional
Relative URL of the created or replayed job
RateLimitstringOptional

The state of each policy in RateLimit-Policy: "submit";r=59;t=1, r remaining and t seconds until whole again.

RateLimit-LimitintegerOptional

Quota of the most restrictive policy (draft-07 form).

RateLimit-PolicystringOptional

The limits this request consumed, as an RFC 8941 list (draft-ietf-httpapi-ratelimit-headers): "submit";q=60;w=60. Policies are submit, upload and daily. Sent only while rate-limit headers are on.

RateLimit-RemainingintegerOptional

Remaining quota of the most restrictive policy (draft-07 form).

RateLimit-ResetintegerOptional
Seconds until the most restrictive policy is whole again.
Retry-AfterstringOptional

Delay before retrying, expressed as delta-seconds

X-Request-IdstringOptional
Request correlation identifier

Response

Idempotent replay of the job the first submission created
completed_atdatetime or null
created_atdatetime
errorobject or null
expires_atdatetime or null
idstring
inputslist of objects
operationenum

What a job does: the operation’s authorization scope.

An operation is not its output’s type: OPERATION_OUTPUT_TYPE is the one place the two meet.

Allowed values:
outputobject or null
statusenum
Allowed values:
updated_atdatetime
livemodebooleanOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
410
Gone Error
413
Content Too Large Error
429
Too Many Requests Error
503
Service Unavailable Error