HeyGen Image 1 generates portraits that preserve a person’s identity while following the clothing, pose, composition, and background of a reference image. Provide photos of the person and a separate image showing the look you want. The person in the reference image can be someone else.
This is an identity-focused portrait model. The current API requires both image inputs and does not accept a custom text prompt.
The only supported mode is identity_remix. It uses identity photos and one appearance reference to generate portraits. Omit mode to use identity_remix. An unknown value or null returns HTTP 400.
Build with it
Generate images
The following request generates two images from the same identity and reference look:generation_id and use it to poll. Acceptance means the job has been submitted; generation can still fail later.
Retrieve the result
data.status:
Poll every few seconds, backing off on rate limits or temporary errors, until a terminal status is returned. There is no separate
processing status and no partial-result response.
Example completed job:
images is always an array, including when requesting one image. Its order and output IDs remain stable across polls. generation_id identifies the whole job; each image_id identifies one generated output. Poll using the generation ID, not an image ID.
created_at is the job’s creation time in Unix seconds. Download URLs expire; retrieve the job again to obtain usable URLs. Store generation and image IDs for tracking rather than treating a signed URL as a permanent identifier.
Pricing
The standard API price is $0.28 per generated image. The same rate applies to every supported aspect ratio and to jobs with one to five images. There is no batch discount. The base price for a job isnum_images × $0.28:
These are base prices before API-credit rounding. The total credit deduction is rounded up once per request, after multiplying by the number of images. Contract pricing, if applicable, follows your account’s rate card.
Your API balance must cover the whole job. If a charged job fails or is cancelled, its charge is refunded. Reusing an idempotency key for the same job does not create another charge. Check your balance and charges on the API usage page.
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 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
Unknown fields are rejected.
prompt, the singular reference_image field, custom dimensions, and callback fields are not supported.
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. The example above returns 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 need the scopes listed above, and trial API keys are not supported. 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:
Failed and cancelled jobs return no partial images. There is no API endpoint for cancelling a job.
Specs at a glance
Get an API key
Create a key and check your usage.
Upload reference images
Upload identity and reference photos, then use their asset IDs in a request.