# Enhance or restyle a portrait photo

URL: https://www.atmee.ai/docs/v2/api/reference/generation/enhancePortrait

`POST /v1/generation/enhancements`

Crops the caller's own photo to a square and returns up to four square
portraits, one per image provider. Without `prompt` they are enhanced
versions that keep the subject's identity. With `prompt` they restyle
the photo as the prompt asks ("this person as a 1920s detective"): the
person is kept unless the prompt asks otherwise. The prompt and the
photo are each moderated before any provider is called. `image` is
`upload:<uploadId>` (a `portrait` upload from `POST /v1/uploads`, which
stays usable afterwards) or a public https link to a jpg, png or webp of
at most 10 MB. If the photo shows a real person other than the creator,
have that person's permission first.

The outputs, price, charging and `Idempotency-Key` work as for
`POST /v1/generation/portraits`. Requires `generation:write` and
`avatars:write`.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | A new UUID minted for this request. Reuse it only to retry the same request: a retry never charges twice and returns the first result. A malformed key, or a key already used with different inputs, gets 400 invalid_input. |

## Request body

- `application/json`: `EnhancePortraitRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | string | yes | The photo to enhance, `upload:<uploadId>` or a public https link (jpg, png or webp, at most 10 MB). |
| `prompt` | string | no | How to restyle the photo ("as a 1920s detective, film noir lighting"). The person in the photo is kept unless the prompt asks otherwise. Absent or blank, the photo is only enhanced. |
| `engine` | string (`v1`, `v2`) | no | The avatar engine the photo is for. `v1` (the default) turns the face to the camera, shoulders up, and blurs the background; `v2` keeps the pose, gaze, hands, framing and background and only improves quality. Pass the engine the avatar will be created with. |
| `avatarId` | string | no | An existing avatar the photo is for, to replace its photo; its own engine is used. Leave `engine` out when this is given (a different `engine` is `invalid_input`). Refused before any charge as `avatar_not_found` (404) when the account has no such avatar, and as `avatar_not_allowed` (403) when an avatar-scoped API key is for another avatar. |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | The enhanced or restyled portraits (or the replayed first result). | `GeneratedPortraitsResponse` |
| `400` | invalid_input (an Idempotency-Key that is not a UUID or was used with different inputs; an input the operation cannot take, or for a clip one the renderer could not use, named as input_failure image or audio) \| moderation_flagged (the description, name, sample text, prompt or photo was flagged; change it) | `ApiErrorResponse` |
| `401` | Missing or invalid API key -- or a user token that is invalid, anonymous, or of a user who may act for no account (invalid_login) | none |
| `402` | insufficient_credits (the balance is below the price; top up, don't retry) \| api_key_spend_cap_reached | `ApiErrorResponse` |
| `403` | insufficient_scope (an API key needs both generation:write and avatars:write) \| account_not_allowed (a user token whose X-Account-Id names an account the user may not act for) \| avatar_not_allowed (an avatar-scoped API key and an `avatarId` of another avatar). Nothing is charged. | `ApiErrorResponse` |
| `404` | avatar_not_found (`avatarId` names no avatar of this account). Nothing is charged. | `ApiErrorResponse` |
| `409` | request_in_progress (a call with this Idempotency-Key is still running, or its charge could not be confirmed; retry it with the same Idempotency-Key after Retry-After and get its one result, charged once -- a new key could charge twice) \| account_ambiguous (a user token of several accounts without X-Account-Id) | `ApiErrorResponse` |
| `422` | Request body failed schema validation, or the Idempotency-Key header is missing. | none |
| `429` | rate_limited -- the account has too many generation calls running, or made too many in the last minute; retry after Retry-After. | `ApiErrorResponse` |
| `502` | provider_failed -- no provider returned a usable output; nothing was charged. | `ApiErrorResponse` |
| `503` | generation_unavailable -- this instance does not offer generation. | `ApiErrorResponse` |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `portraits` | array of `GeneratedPortrait` | yes |  |
| `microcreditsCharged` | integer | yes | What this call charged (100 microcredits = 1 credit); 0 on a replay. |
| `replayed` | boolean | yes | True when an earlier call with the same Idempotency-Key was replayed. |
| `failedProviders` | array of string | yes | The providers that returned nothing usable. |