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 dispatches an async job that produces N draft images. Drafts are not identities yet: they live as ImageResult rows on a BatchJob of type identity_creation. They consume credits but no identity slot.
2. Promotion: pick the draft you want and call POST /identity/promote-generated on its image_result_id. The API copies the draft image into the canonical identity path, creates the Identity record, and dispatches the standard preprocessing pipeline (POV/augmentation). 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