Skip to main content
Profiles are the core concept that makes Phota different from generic image generation. A profile teaches the API what a specific person looks like, so their identity is preserved across all edits and generations.

​
What is a profile?

A profile is a learned representation of a specific person’s appearance. You create one by uploading – reference photos of the same person. Phota processes these photos to learn the subject’s facial features, hair, skin tone, and overall appearance. Once a profile is trained, you can use it across unlimited edit, generate, and enhance requests. The API preserves the person’s identity even through dramatic transformations — placing them on a beach, changing their outfit, or restyling the entire scene.

Training photosUpload – reference photos to create a profile. Group shots are OK as long as your intended subject is the most common one across all photos.

​
How profiles work

Profiles work in two phases:
  1. Training — you upload reference photos and the API learns the subject’s appearance (facial features, hair, skin tone, etc.).
  2. Inference — when you call /edit, /generate, or /enhance, the API recognizes people in the input image (or described in the prompt) and decides which profiles from the candidate profiles to use to preserve their identities in the output. The fewer candidate profiles you pass, the easier it is for the API to match the right one. If a profile is not provided in the candidate profiles, the API will not consider it when matching.
A typical integration: your user uploads photos -> you call the profile training endpoint -> you get back a profile_id -> you pass that profile in every edit or generation you run for them. Multi-person scenes work too — reference multiple [[profile_id]] values in a single prompt.
Profiles are opt-in per request. If you don’t pass any profile IDs, the API will not attempt to preserve anyone’s identity, even if trained profiles exist in your account. For anything where the subject needs to look like a specific person, include the relevant profile IDs.

​
Profile creation

Creating and using a profile follows this flow:
1

Create the profile

Send the reference image URLs to POST /profiles/add. Training starts immediately and runs asynchronously. You receive a profile_id right away.
{
  "image_urls": ["https://example.com/photo1.jpg", "https://example.com/photo2.jpg", "https://example.com/photo3.jpg"]
}
2

Poll for training status

Call GET /profiles/{profile_id}/status until the status is READY. Training typically takes ~20 minutes.
StatusMeaning
VALIDATINGImages are being validated and prepared. Poll again in 10-30 seconds.
QUEUINGTraining job is queued. Poll again in 10-30 seconds.
IN_PROGRESSModel is actively training. Expected to finish within ~20 minutes. Poll again in 10-30 seconds.
READYTraining completed. The profile is ready for use.
ERRORTraining failed. Check the message field for details.
3

Use the profile

Once ready, reference the profile in any edit, generate, or enhance request. See Referencing profiles in requests below.

​
Referencing profiles in requests

There are two ways to tell the API about profiles, and they serve different purposes:

​
The profile_ids field (edit and enhance)

Every edit and enhance request accepts a profile_ids array in the request body. This tells the API which profiles are available as “models” for the request — typically all profiles belonging to a single end-user. The API needs this list to know which identities it can draw from, even if the prompt does not explicitly mention every profile. For edits and enhancements, profile_ids is often all you need. The API will match the people in the input photo to the provided profiles automatically. 
{
  "prompt": "Make the sun shine through the trees",
  "images": ["https://example.com/photo.jpg"],
  "profile_ids": ["abc123", "def456"]
}
Your developer account holds all profiles, but only pass the ones belonging to the end-user whose photo is being processed. This ensures correct identity matching and billing.

​
The [[profile_id]] prompt syntax (edit and generate)

In the prompt field of edit and generate requests, you can reference a profile inline using double brackets. This tells the model which specific person you are referring to in the prompt. For generation, [[profile_id]] is the only way to specify which profiles to use — the /generate endpoint does not accept a profile_ids field. For edits, [[...]] is optional but useful when you want to reference a specific person in a multi-person scene or add someone who isn’t in the input photo. Generation example: 
{
  "prompt": "A photo of [[abc123]] and [[def456]] at a dinner party"
}
Edit example — when you use [[profile_id]] in an edit prompt, the API automatically merges it with the profile_ids list, so you don’t need to list the same ID in both places: 
{
  "prompt": "Add [[def456]] to the group photo",
  "images": ["https://example.com/group.jpg"],
  "profile_ids": ["abc123"]
}
For enhancements, just pass profile_ids — there is no prompt.

​
Image requirements for training

  • Minimum: images
  • Maximum: images
  • Format: publicly accessible URLs (signed URLs work)

​
Tips for best results

  Clear, well-lit faces
  High-res 1K+ images
  Expressions: neutral, smiling, frowning, surprised
  Angles: front, slight left/right, a profile
  Lighting: indoor, outdoor, sunny, etc.
  Group shots are OK if added person’s face is clear

​
Good photos

well_lit

✅ Well lit and sharp
expression

✅ Diverse expressions and angles
pose

✅ Diverse poses
accessory

✅ Diverse accessories (face visible)

​
Bad photos

extreme_pose

❌ Extreme poses
small_noisy_blur

❌ Small, dark or noisy
occlude_facial_feature

❌ Largely covered and occluded
motion_blur

❌ Blurry from movement

​
Next steps

Quickstart

Walk through the full workflow end to end.