Identities

An identity represents the model/person used by generation jobs and is referenced with identity_code.

There are two ways to add an identity to your library:

• Upload an existing photo of a person. The system validates that it contains exactly one clearly visible face and starts preprocessing automatically.
• Generate a new identity from a brief or a reference image, then promote one of the drafts. See Create an identity for the full walkthrough.

Processing status

Identities move through a preprocessing lifecycle (pending, processing, completed, failed).

Useful fields during and after preprocessing:

Visibility and sharing

Identities can be:

• private: only you can see it
• shared: visible to members of your groups
• default: platform-provided identities available based on your plan

Generating identities

Beyond uploading photos, you can generate brand-owned identities from a brief or a reference image. The flow runs in two stages:

1. Creation job: POST /identity/create accepts a list of structured instructions (or a free-form prompt) and starts an async job that produces N draft images. Drafts are not identities yet: they are returned by the job results endpoint, each carrying an image_result_id. They consume credits but no identity slot.
2. Promotion: pick the draft you want and call POST /identity/promote-generated with its image_result_id. The response returns the new identity_code along with a preprocessing_job_id you can track. This step charges 50 credits and counts toward your identity slot cap.

Once preprocessing completes, the new identity behaves exactly like an uploaded one: usable in Model Swap, Flat-to-Model, and any other job that takes an identity_code.

See Create an identity for the end-to-end walkthrough with Python examples.

API endpoints