Atmee.aiDocs
APIAPI referenceGeneration

Enhance a portrait

POST
/v1/generation/enhancements

Crops your photo to a square and returns two enhanced portraits, one from Gemini and one from Grok, that keep the subject's identity. With prompt, they restyle the photo as the prompt asks ("this person as a 1920s detective"), keeping the person unless the prompt says otherwise.

  • Input: image is a portrait upload (upload:<uploadId>, still usable afterwards) or a public https link to a jpg, png or webp of at most 10 MB. The prompt and the photo are moderated first.
  • Consent: if the photo shows a real person other than you, get their permission first.
  • Output, billing and idempotency: as for POST /v1/generation/portraits.
  • Scopes: generation:write and avatars:write.

Authorization

headerX-Api-Key<token>

Your secret API key (sk_atmee_...; older keys start sk_live_), sent as X-Api-Key. Keep it on your server and never send it to a browser.

Header Parameters

Idempotency-Key*string

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.

Lengthlength <= 255

Request Body

application/json
  1. body
image*string

The photo to enhance, upload:<uploadId> or a public https link (jpg, png or webp, at most 10 MB).

Length1 <= length <= 2048
prompt?string

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.

Lengthlength <= 2000
engine?string

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.

Value in"v1""v2""v2hd""v2pro"
avatarId?string

An existing avatar whose photo this replaces. Its own engine is used, so leave engine out (a different one is invalid_input). An avatar the account does not have is 404 avatar_not_found, and one outside an avatar-scoped key is 403 avatar_not_allowed; neither is charged.

Formatuuid
Lengthlength <= 36

Response Body

The enhanced or restyled portraits (or the replayed first result).

application/json
  1. response
portraits*array<>
Items1 <= items <= 4
microcreditsCharged*integer

What this call charged to credits (100 microcredits = 1 credit), after the plan's free generation allowance; 0 on a replay. The call's price is microcreditsCharged + microcreditsFree.

microcreditsFree*integer

The part of the price the plan's free generation allowance covered (pricing.generation.freeAllowance on GET /v1/account); 0 on a replay and when none is left.

replayed*boolean

True when an earlier call with the same Idempotency-Key was replayed.

failedProviders*array<string>

The providers that returned nothing usable.

Example Request
curl -X POST 'https://api.atmanity.us/v1/generation/enhancements' \  -H 'Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "image": "string"}'
Example Response
{  "portraits": [    {      "upload": "upload:3f1c2a9e-8d4b-4f6a-9c2e-1b7d5a0e4c11",      "url": "http://example.com",      "expiresAt": "2019-08-24T14:15:22Z",      "preview": "string",      "provider": "string",      "unavailable": true    }  ],  "microcreditsCharged": 0,  "microcreditsFree": 0,  "replayed": true,  "failedProviders": [    "string"  ]}