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"
    ],
    "tag": "user_abc123"
  }'
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,
    "output_format": "jpg"
  }'
The response contains the output images as base64-encoded strings (default response_mode: "bytes"):
{
  "images": ["/9j/4AAQ...", "/9j/4AAQ..."],
  "download_urls": [],
  "known_subjects": {
    "counts": {
      "abc123": 2
    }
  }
}
You can control the output aspect ratio (e.g. "9:16"), resolution (up to "4K"), and output_format ("png" or "jpg") on every request. Set response_mode: "urls" to receive signed CDN download URLs instead of base64 bytes.
To get download URLs instead of base64 bytes, set response_mode: "urls":
curl
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"],
    "resolution": "4K",
    "num_output_images": 2,
    "output_format": "jpg",
    "response_mode": "urls"
  }'

{
  "images": [],
  "download_urls": [
    "https://cache-cdn.photalabs.com/20260408/abc123.jpg?token=...&expires=...",
    "https://cache-cdn.photalabs.com/20260408/def456.jpg?token=...&expires=..."
  ],
  "known_subjects": {
    "counts": {
      "abc123": 2
    }
  }
}
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,
    "output_format": "jpg"
  }'
The response format is the same as /edit:
{
  "images": ["/9j/4AAQ...", "/9j/4AAQ..."],
  "download_urls": [],
  "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,
    "output_format": "jpg"
  }'

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