Skip to main content
This guide walks you through the core Phota API workflow: authenticate, create a profile, wait for training, and run your first edit, generation, and enhancement.
Prerequisites: You need an API key from the Developer Portal. All requests require the X-API-Key header.
1

Authenticate

Every request must include your API key in the X-API-Key header. Verify your key works by listing your profiles:
curl https://api.photalabs.com/v1/phota/profiles/ids \
  -H "X-API-Key: YOUR_API_KEY"
You should receive a JSON response with your profiles (empty if you haven’t created any yet):
{
  "profiles": []
}
2

Create a profile

A profile represents a subject whose identity you want to preserve across edits and generations. Provide to publicly accessible image URLs of the subject (person, dog, or cat):
curl -X POST https://api.photalabs.com/v1/phota/profiles/add \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_urls": [
      "https://example.com/photo1.jpg",
      "https://example.com/photo2.jpg",
      "https://example.com/photo3.jpg"
    ]
  }'
The response includes the new profile ID:
{
  "profile_id": "abc123"
}
Training starts immediately and runs asynchronously. The profile is not ready for use until training completes. See the Profiles guide for tips on choosing good training photos.
3

Poll for training status

Check the profile status until it reaches READY:
curl https://api.photalabs.com/v1/phota/profiles/abc123/status \
  -H "X-API-Key: YOUR_API_KEY"
Possible status values:
StatusMeaning
IN_PROGRESSTraining is still running. Poll again in a few seconds.
READYTraining completed. The profile is ready for edits.
ERRORTraining failed. Check the message field for details.
4

Edit an image

Once the profile is READY, you can reference it in an edit request. Provide input images as base64 strings or public URLs, along with a text prompt. Pass the user’s profile IDs in the profile_ids field so the API knows which identities to preserve. You can also use [[profile_id]] in the prompt to reference a specific profile explicitly:
curl -X POST https://api.photalabs.com/v1/phota/edit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Make [[abc123]] smile wider",
    "images": ["https://example.com/photo.jpg"],
    "profile_ids": ["abc123"],
    "aspect_ratio": "1:1",
    "resolution": "4K",
    "num_output_images": 2
  }'
The response contains the generated images as base64-encoded PNGs:
{
  "images": ["iVBORw0KGgo...", "iVBORw0KGgo..."],
  "known_subjects": {
    "counts": {
      "abc123": 2
    }
  }
}
You can control the output aspect ratio (e.g. "9:16") and resolution (up to "4K") on every request.
5

Generate an image

You can also generate images from scratch — no input image needed. Reference profiles directly in the prompt using [[profile_id]] syntax:
curl -X POST https://api.photalabs.com/v1/phota/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A professional portrait shot of [[abc123]] on a tropical beach at sunset",
    "num_output_images": 2
  }'
The response format is the same as /edit:
{
  "images": ["iVBORw0KGgo...", "iVBORw0KGgo..."],
  "known_subjects": {
    "counts": {
      "abc123": 2
    }
  }
}
Generation is non-deterministic — request multiple variations with num_output_images and let the user pick the best one.
The /generate endpoint does not accept images or profile_ids. Reference profiles in the prompt with [[profile_id]] syntax instead. If you need to transform an existing photo, use /edit.
6

Enhance an image

Enhancement improves a photo automatically — no prompt needed:
curl -X POST https://api.photalabs.com/v1/phota/enhance \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/photo.jpg",
    "profile_ids": ["abc123"],
    "num_output_images": 2
  }'

​
Next steps

Authentication

Learn about API key management and best practices.

Use cases

See detailed examples of each capability with visual previews.

Profiles guide

Deep-dive into profiles, identity preservation, and prompt syntax.