Portraits and enhancement

Two calls make the image an avatar or a clip starts from. Both return up to four square options, one from each of Atmee's image providers, so you can pick the best.

Which one to useCopy Anchor Link

• You have no image, and the character is invented: generate portraits from a description.
• You have a photo, and it's close but flawed (poor light, an odd crop, low resolution): enhance it, with no prompt.
• You have a photo, and want the same person in a new look, scene or style: restyle it, with a prompt such as "as a 1920s detective, film noir lighting" or "as a watercolour painting".
• You need a real person: always start from their own photo, with their permission. Never describe a real person to the portraits call.

Generate only when you need to: when you have no portrait yet, or when a portrait is the reason an avatar animates badly.

Generate portraitsCopy Anchor Link

curl -X POST https://api.atmanity.us/v1/generation/portraits \
  -H "X-Api-Key: $ATMEE_API_KEY" \
  -H "Idempotency-Key: 9a7c1e52-4b3d-4f6a-8e21-5c0d9b7a3f14" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A professional woman in her 30s, navy blazer, warm smile, lips slightly parted, half-body from the waist up, hands visible, neutral background."
  }'

Write a specific description: age, gender, expression, clothing, style and, when you want one, the framing. Framing is your choice: on Atmee V2, close-ups, half-body and full-body shots all work, and the avatar moves what the portrait shows.

• Photorealistic, half-body: "A professional woman in her 30s, navy blazer, warm smile, lips slightly parted, half-body from the waist up, hands visible, neutral background."
• Stylised, full body: "A friendly cartoon character with big eyes, colourful outfit, cheerful expression, standing, full body, facing the camera."
• Too vague: "a friendly avatar". Decide on a style first.

Keep the face toward the camera with the lips slightly parted, and the whole figure inside the avatar's frame: Atmee keeps the middle of the image, square unless the avatar uses a portrait or landscape frame. In a full-body shot the face gets small, so check that it stays wider than about a fifth of the frame.

Want one thing different? Generate again with that change written into the same description, such as a lighter background or a closed collar. It's a new call, charged again.

Enhance or restyle a photoCopy Anchor Link

curl -X POST https://api.atmanity.us/v1/generation/enhancements \
  -H "X-Api-Key: $ATMEE_API_KEY" \
  -H "Idempotency-Key: 2e8d4f61-7a9b-4c3e-b5d2-1f0a6c8e9b37" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "upload:5d3c2b1a-0f9e-4d8c-a7b6-e5f4d3c2b1a0",
    "prompt": "in a chef'\''s whites in a bright kitchen"
  }'

image is a public https link (jpg, png or webp, up to 10 MB) or upload:<uploadId> of a portrait upload, which stays usable afterwards: if you pick the original photo after all, pass the same upload to the create, within its hour.

• Without prompt the result is an enhanced version of the photo that keeps the person.
• With prompt it is restyled as the prompt asks. The person is kept unless the prompt asks otherwise, so write any change to the person itself (an older age, other hair, a cartoon animal) into the prompt on purpose.

A restyle costs the same as an enhancement. A changed prompt is a new request, with a new Idempotency-Key.

Check what comes backCopy Anchor Link

{
  "portraits": [
    {
      "upload": "upload:7f6e5d4c-3b2a-4190-8f7e-6d5c4b3a2918",
      "url": "https://…/portrait.png",
      "expiresAt": "2026-11-05T09:12:44Z",
      "preview": "/9j/4AAQSkZJRg…",
      "provider": "…",
      "unavailable": false
    }
  ],
  "failedProviders": [],
  "replayed": false
}

Each portrait has an upload, a short-lived url to the full-size image, and a small base64 JPEG preview to show without fetching url. failedProviders names the providers that returned nothing usable, so you may get fewer than four.

Before you use one:

• Run it past the negative examples. A generated or restyled portrait can still have its face turned away, covered or too small. See Avatar 101: Negative examples.
• For an enhanced or restyled photo, check it's still the same person: face shape, features, skin tone, apparent age and hair, apart from what the prompt asked to change. If someone who knows them would notice a difference, don't use it.

Pass the chosen upload as it is: assets.image.url in Create an avatar, the JSON form of PUT /appearance, or image in a video clip. It works for one avatar and expires 24 hours after it was made.

Prices, retries and errors are the same for every generation call: see Generation.