Headshot API

Generate Portrait

POST /api/generate-portrait

Description: Generate portrait photos based on input images and prompts.

Request:

{
  "apiKey": "string", // API key used for authentication
  "prompt": "string", // Text prompt used to guide image generation
  "seed": "number", // Random seed (integer > 0). Using the same seed will likely produce similar images. Default is -1 (random)
  "sampleNumber": "number", // Number of images to generate (integer, range: 1–8). Default is 1
  "identityScale": "number", // Similarity strength (float, range: 0–1). Higher values preserve identity more. Default is 0.8
  "inputImages": [ // Base64-encoded input images. Only one image is supported as the primary reference.
    "data:image/jpeg;base64,..."
  ],
  // Recommended output image pixel size: 1:1 (768×768), 3:4 (768×1024)
  "outputImageWidth": "number", // Output image width in pixels (range: 512–2024). Default is 768
  "outputImageHeight": "number" // Output image height in pixels (range: 512–2024). Default is 1024
}

Response:

{
  "outputImages": [ // Generated images in Base64 format. The number of images matches sampleNumber
    "data:image/jpeg;base64,...",
    "data:image/jpeg;base64,..."
  ]
}

Consistent Styles with Fixed Prompt & Seed

When generating a portrait, you can pass a seed value alongside your prompt. The key behavior: the same prompt and seed will always produce the same visual style, regardless of who is in the photo. Different people, same consistent result.

This means once you find a style you like — a particular lighting, background, or look — you can reuse that exact prompt + seed pair as a reusable style preset for all your users.

How to use this:

1. Generate portraits and experiment with prompts until you find a style you're happy with.
2. Save the prompt and seed you used.
3. Use that same prompt + seed in future API calls to apply the same style to any photo.

Building Your Own Template Library

Once you have a prompt + seed pair that produces the style you want, you can save it and treat it as a named template — for example, "corporate-headshot" or "linkedin-profile". When your users want a specific look, pick the corresponding template and pass its prompt and seed to the API.

This gives you full control to build and manage your own style library without any extra setup on our side.