Headshot API

Generate professional portrait variations from a reference image and a text prompt. A fixed prompt and seed can be reused to create a consistent visual style for different subjects.

Headshot generation is a creative portrait workflow. It does not produce or validate a passport, visa, or identity-document photo. Use the Passport Photo API for document-photo processing.

Access and the service base URL are provided separately. Use the base URL assigned to your integration.

Generate a portrait

POST /api/generate-portrait

Request

Field	Type	Required	Default	Description
apiKey	string	Yes	—	API key enabled for Headshot generation.
prompt	string	Yes	—	Describes the desired lighting, background, clothing, and photographic style.
seed	integer	No	-1	Positive fixed value for repeatable style behaviour; -1 selects a random seed.
sampleNumber	integer	No	1	Number of output images, from 1 to 8.
identityScale	number	No	0.8	Identity-preservation strength from 0 to 1.
inputImages	array of strings	Yes	—	Base64 reference images. Currently one primary reference image is supported.
outputImageWidth	integer	No	768	Output width in pixels, from 512 to 2024.
outputImageHeight	integer	No	1024	Output height in pixels, from 512 to 2024.

Recommended output sizes include 768 × 768 for a square portrait and 768 × 1024 for a 3:4 portrait.

{
  "apiKey": "your-api-key",
  "prompt": "Professional studio headshot, neutral background, soft even lighting, business attire",
  "seed": 18421,
  "sampleNumber": 2,
  "identityScale": 0.8,
  "inputImages": [
    "data:image/jpeg;base64,..."
  ],
  "outputImageWidth": 768,
  "outputImageHeight": 1024
}

Response

{
  "outputImages": [
    "data:image/jpeg;base64,...",
    "data:image/jpeg;base64,..."
  ]
}

The number of entries in outputImages follows sampleNumber.

Build reusable styles

The prompt controls the requested visual direction, while the seed helps keep a similar style across calls. Once you find a useful combination:

1. Save the prompt and positive seed in your application.
2. Give the combination a name such as corporate-headshot.
3. Reuse it with different reference images.
4. Review outputs before delivery; generated results may still vary between subjects and inputs.

A fixed prompt and seed improve style consistency but do not guarantee pixel-identical composition.

Input and output guidance

• Use a clear, front-facing reference portrait with one subject.
• Avoid small faces, severe blur, heavy occlusion, and extreme poses.
• Keep the API key and source images on your server.
• Base64 images can make responses large; set an appropriate request timeout and avoid logging full payloads.
• Review identity preservation and visual artifacts before presenting or storing an output.
• Generated headshots should not be represented as official identity-document photos.