> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protoface.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Source images

> Portrait requirements for a successful avatar build.

export const Shot = ({src, alt, verdict}) => <div style={{
  aspectRatio: "1 / 1",
  border: `2px solid ${verdict === "Good" ? "#16a34a" : "#dc2626"}`,
  borderRadius: "12px",
  overflow: "hidden",
  position: "relative"
}}>
    <div style={{
  background: verdict === "Good" ? "#16a34a" : "#dc2626",
  borderRadius: "999px",
  color: "white",
  fontSize: "12px",
  fontWeight: 700,
  left: "12px",
  padding: "4px 10px",
  position: "absolute",
  top: "12px",
  zIndex: 1
}}>
      {verdict}
    </div>
    <img src={src} alt={alt} style={{
  display: "block",
  height: "100%",
  objectFit: "cover",
  width: "100%"
}} />
  </div>;

An avatar builds from a single still: a real person, an animated or
generated character, a mascot, or something synthetic. What decides
whether the build succeeds is not realism but whether face detection can
find a complete set of features.

## Requirements

Upload a PNG or JPEG meeting all of the following.

* One face in the frame, with nothing else competing for attention.
* A face or face-like structure looking directly at the camera, with both
  eyes visible.
* A distinct nose or nose bridge, and a visible mouth, chin, cheeks, and
  forehead.
* A face large enough to inspect, with room around the head so nothing is
  cut off.
* Even lighting across the face.
* A clean image, without UI, stickers, text, or a watermark over it.

Stylized, mascot, and synthetic subjects qualify on the same terms: two
eyes, a nose area, a mouth, a chin or jaw, and a head near the middle of
the frame.

## What works

<Columns cols={2}>
  <Frame caption="Distinct centered face">
    <Shot verdict="Good" src="/images/avatar-source-guide/good.webp" alt="Centered forward-facing real portrait with even lighting" />
  </Frame>

  <Frame caption="Distinct stylized face">
    <Shot verdict="Good" src="/images/avatar-source-guide/good-animated.png" alt="Centered forward-facing animated character with visible eyes, nose, mouth, chin, and forehead" />
  </Frame>

  <Frame caption="Clear face features">
    <Shot verdict="Good" src="/images/avatar-source-guide/good-animal.png" alt="Centered forward-facing mascot with a clear face-like structure" />
  </Frame>

  <Frame caption="Distinct synthetic face">
    <Shot verdict="Good" src="/images/avatar-source-guide/good-synthetic.png" alt="Centered forward-facing synthetic character with distinct eyes, nose, mouth, chin, and forehead" />
  </Frame>
</Columns>

## What fails

Each of these hides the face in a different way, and any one of them is
enough to stop a build.

<Columns cols={2}>
  <Frame caption="Face cropped or covered">
    <Shot verdict="Avoid" src="/images/avatar-source-guide/bad-cropped.webp" alt="Cropped portrait with the face partially obscured" />
  </Frame>

  <Frame caption="Face turned away">
    <Shot verdict="Avoid" src="/images/avatar-source-guide/bad-side-profile.jpg" alt="Side-profile portrait where the face is turned away" />
  </Frame>

  <Frame caption="Face in shadow">
    <Shot verdict="Avoid" src="/images/avatar-source-guide/bad-harsh-lighting.jpg" alt="Portrait with harsh backlighting and deep face shadows" />
  </Frame>

  <Frame caption="Face too small to read">
    <Shot verdict="Avoid" src="/images/avatar-source-guide/bad-animal-full-body.png" alt="Full-body animal side view with no distinct front-facing face" />
  </Frame>

  <Frame caption="No normal face features">
    <Shot verdict="Avoid" src="/images/avatar-source-guide/bad-screen-face.png" alt="Synthetic character with a screen face and no distinct nose, mouth, chin, or forehead" />
  </Frame>

  <Frame caption="Multiple unclear faces">
    <Shot verdict="Avoid" src="/images/avatar-source-guide/bad-animated-multiple.png" alt="Animated image with multiple faces, cropped faces, and covered facial features" />
  </Frame>
</Columns>

## By subject

Each kind of subject meets those requirements differently.

### Real people

Use a head-and-shoulders portrait with the person centered and looking
forward. The eyes, nose, mouth, chin, and forehead should all be visible,
and a neutral or slightly smiling expression works best. Avoid sunglasses,
masks, hands on the face, heavy hair over the eyes, strong backlight,
motion blur, and tight crops.

### Animated or generated characters

Animated and AI-generated characters work well when they are composed like
a portrait photo. Use one character, front-facing and centered, with clear
eyes, nose, mouth, chin, forehead, and a symmetrical head shape. Avoid
action scenes, crowd shots, partial faces, dramatic camera angles, and
props covering the face.

### Animal or mascot characters

Animal and mascot avatars work best as a human-like mascot portrait rather
than a normal pet photo. Use a front-facing character with large visible
eyes, a centered snout or nose, a clear mouth, cheeks, a chin or jaw
shape, and a head-and-shoulders crop. Avoid full-body animals, side views,
tiny faces, busy outdoor backgrounds, and pets holding toys in their
mouth.

### Synthetic characters

Synthetic characters work best with a human-like or mascot-like face
layout. Use a character with two visible eyes, a nose bridge or nose-like
shape, a mouth, chin, forehead, and a symmetrical head. Avoid screen-only
faces, black visors, helmets with no visible facial structure, reflective
masks, and abstract heads.

## If a build fails

An avatar at `status: "failed"` carries the reason on `failure_reason`.
When no face was detected, the fix is usually a clearer front-facing
source with stronger facial structure, not a different subject.

For stylized, mascot, and synthetic characters, make each attempt more
portrait-like: visible eyes, a nose area, a mouth, a chin, and a
forehead, with nothing hiding or competing with the face.

When an image qualifies, upload it with
[Create an avatar](/guides/avatars#create-an-avatar).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.