One person. Six scenes she was never photographed in. HeyGen Image takes identity photos of a person and one reference image, and returns portraits that keep her face while following the reference’s pose, clothing, light and setting.
From one identity to any scene
Three photos of the HeyGen public avatar Serena went in asidentity_images. Each scene below is one call with one reference_images entry, shown inset at the bottom left of its output. The reference’s person never appears; only her pose, outfit and world do.
The six references are generated images, not photographs of real people. A reference can be a photo you own, a frame from a film, or a product shot with a model in it; it must contain exactly one person, or the job fails with multiple_faces_detected.
The scene, light, clothing and framing come from the reference. The face, hair, expression and gaze come from the identity photos: these three are studio portraits looking at the camera, so every output looks at the camera too. For candid results, use candid identity photos. For video, a still becomes the first frame of a HeyGen Video image_to_video clip; start the prompt with “Keep the person exactly as they appear in the first frame” and describe one camera move.
Build it with an agent
Not technical? Paste this into Claude Code, Codex, or Cursor. Bring a few photos of the person and a few scene photos you own; it generates the set with you.Prompt for your agent
The API
Create
The call behind the train scene above:Retrieve
PollGET /v3/models/images/{generation_id} until the status leaves pending. A completed job lists exactly num_images entries in images, in stable order, each with its image_url, width, height and seed. A failed or cancelled job carries failure_code and failure_message and no partial images. The lookup returns 200 even when the job failed, and there is no callback. Download URLs expire; retrieve the job again for fresh ones, and keep generation_id and image_id as the stable identifiers.
Choose your inputs
identity_images: one to five photos of the person whose identity should appear in the result. Use clear photos where their face is visible. These are multiple views of one identity, not separate generation requests.reference_images: an array with exactly one image showing the desired clothing, pose, composition, and background. It guides the look of every output in the job.
asset_id, an HTTPS url, or inline base64 with a media_type, and you can mix them within a request.
Uploaded assets must be images owned by the calling workspace. Use the returned asset_id from the asset upload API, not a generated output’s image_id.
URL inputs must be publicly accessible HTTPS URLs pointing directly to an image; redirects are not followed. Image downloads are limited to 16 MiB. Inline base64 inputs are limited to 5 MiB of decoded image data.
Parameters
The full field list is in the API reference.model accepts only heygen-image-1, and mode defaults to identity_remix. reference_images takes exactly one image; an empty array is rejected. num_images runs 1 to 5 (default 1), and seed from 0 to 4,294,967,295. Omit aspect_ratio or send null to match the reference image after EXIF orientation. Unknown fields are rejected, including prompt, a singular reference_image, custom dimensions and callback fields.
Output
Useaspect_ratio to choose the output shape, or omit it to follow the reference image. Identity images do not determine output shape. When inferring from the reference, its width-to-height ratio must be between 1:4 and 4:1.
The model chooses its native canvas using its 4K training policy and then center-crops a narrow border to deliver the requested ratio. There is no output upscaling. Explicit presets have exact ratios; inferred ratios round to the nearest pixel. Returned dimensions do not have to be multiples of 32.
Always read
width and height from each output. An aspect override changes the generation canvas and may change composition; it is not just a crop of the reference photo. All images in one job share the chosen output shape.
Retries and seeds
Use a uniqueIdempotency-Key for each new job, and reuse that key with the same body when retrying a submission after a timeout. While the idempotency record is retained, the retry resumes or returns the original job. Use a new key when you want a new generation, even if the inputs are the same. The header is optional, but omitting it allows retries to create additional jobs.
seed controls the first output. Later outputs use seed + 1, seed + 2, and so on. With seed: 42 and num_images: 2, the outputs report seeds 42 and 43. Each output reports its actual seed; later seeds can exceed the request field’s maximum. Different seeds provide variation, but do not guarantee visibly different images. A seed is not an idempotency key or a guarantee of identical results across model updates.
Errors
Request errors use the standard HeyGen error format. An invalid field or unsupported image count returns HTTP 400. A generation that is missing or belongs to another workspace returns HTTP 404. API keys must be paid keys with the scopes listed above. Insufficient API credits return HTTP 402 (insufficient_credit). A temporary billing or service failure can return HTTP 503; retry with the same idempotency key.
The default rate limits are 30 creation requests per minute and 300 retrieval requests per minute. Workspace limits can differ. If a request returns HTTP 429, follow Retry-After.
A generation failure is different from an HTTP request error. A successful status lookup returns HTTP 200 with a terminal status and these fields:
Jobs run to completion once submitted; there is no API endpoint for cancelling one.

