Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.photalabs.com/llms.txt

Use this file to discover all available pages before exploring further.

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"],
  "tag": "user_abc123"
}
The tag field is optional. Use it to group profiles by your own identifiers (e.g., end-user usernames) so you can filter them later with GET /profiles/ids?tag=user_abc123. See Tagging profiles below.
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.

​
Tagging profiles

Tags let you group profiles by your own identifiers — for example, your end-user’s username or account ID. This is useful when your API key manages profiles for many end-users and you need to list only the profiles belonging to a specific one.

​
Setting a tag

Pass the optional tag field when creating a profile: 
{
  "image_urls": ["https://example.com/photo1.jpg", "..."],
  "tag": "user_abc123"
}
Tags are free-form strings up to 128 characters. A profile can have at most one tag, and multiple profiles can share the same tag.

​
Filtering by tag

Use the tag query parameter on GET /profiles/ids to retrieve only profiles with a specific tag: 
curl https://api.photalabs.com/v1/phota/profiles/ids?tag=user_abc123 \
  -H "X-API-Key: YOUR_API_KEY"
Omitting the tag parameter returns all profiles.

​
Referencing profiles in requests

There are two mechanisms for referencing a profile: the profile_ids request field and inline [[profile_id]] prompt syntax. In most cases you pick one, not both. If you do use both, the API merges them automatically — there’s no benefit to duplicating the same ID in both places.
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_ids field (edit and enhance)

This array tells the API which profiles are available as candidates for the request — typically all profiles belonging to a single end-user. The API matches the people in the input photo to these candidates automatically, so you don’t have to name anyone in the prompt: 
{
  "prompt": "Make the sun shine through the trees",
  "images": ["https://example.com/photo.jpg"],
  "profile_ids": ["abc123", "def456"]
}

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

Inline [[profile_id]] in the prompt attaches a profile to a specific phrase, so the model knows exactly which person the prompt is talking about. This works with any number of subjects — a single reference is perfectly fine: 
{
  "prompt": "Make [[abc123]] smile wider",
  "images": ["https://example.com/photo.jpg"]
}
It’s also the only way to reference profiles in generation (which has no profile_ids field) and the clearest way to refer to multiple people in one prompt: 
{
  "prompt": "A photo of [[abc123]] and [[def456]] at a dinner party"
}

{
  "prompt": "Change [[abc123]]'s clothes to red, and add [[def456]] standing next to them",
  "images": ["https://example.com/photo.jpg"]
}
When [[profile_id]] appears in an edit prompt, it’s automatically merged into the profile_ids candidate list — you don’t need to list the same ID in both places.

​
Which should I use?

EndpointPrompt doesn’t name the subjectPrompt refers to a specific subject
/editprofile_ids[[profile_id]] in the prompt (profile_ids optional)
/generateN/A — use [[profile_id]][[profile_id]] in the prompt (no profile_ids field exists)
/enhanceprofile_idsN/A — /enhance has no prompt
Either mechanism is enough on its own for /edit. If you use both, the API merges them, so there’s no need to list the same ID in both places.

​
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.