InstantID by InstantX

InstantID by InstantX

Generates new images of a person from one face photo and a text prompt, keeping the face recognizable. Made for developers and artists who run Stable Diffusion XL pipelines in Python.

Made by InstantX on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: InstantID makes new pictures of one specific person from a single face photo and a text prompt. It needs no extra training for each new face, so you change the style and scene by changing the prompt. This repository holds the model files that plug into a Stable Diffusion XL pipeline.

Who it suits: It suits developers, artists and researchers who generate images in Python and want the result to still look like the person in a reference photo. Use only faces you have the right to use.

Industry | Who uses it | How they use it | Example
Design and art | Illustrators | Start from one reference face and try different looks and moods | A portrait of the same person in a vintage film style
Marketing | Content teams | Make varied pictures of a person who agreed to it, from one photo | Several images of one model in different settings
Software | App developers | Call the pipeline from Python inside an image app | A tool where a user uploads a selfie and picks a style
Research | Machine learning researchers | Study identity-preserving generation and tune its two strength settings | Compare results at different adapter strengths

If you do not write Python, you can skip the local setup and try the hosted demo the card mentions.

Where to use it:

• Python scripts that use the diffusers library
• Windows, macOS or Linux with Python installed
• A machine with a CUDA graphics card, which the card's sample runs on
• A hosted demo in a browser, linked from the card

Use case | Who | What they get back
Keep one face across styles | Artists | New images that still look like the person in your photo
Tune the look | Developers | Images adjusted with the two strength settings
Try it before installing | Anyone | Pictures from the hosted demo, with no local setup

How to set it up: You need Python with pip and a few libraries before the first run.

• Python and pip
• The libraries opencv-python, transformers, accelerate and insightface
• The antelopev2 face encoder files, which you download by hand
• A CUDA graphics card, since the sample moves the pipeline onto it

1. Install the Hugging Face client with pip.
2. Download the whole repository with the hf command, or fetch only the three checkpoint files from Python.
3. Install the libraries the sample imports.
4. Download the antelopev2 face encoder by hand, as the card says, and put it in models/antelopev2.
5. Run the loading code, which prepares the face encoder, the IdentityNet and the adapter.

pip install -U huggingface_hub
hf download InstantX/InstantID

from huggingface_hub import hf_hub_download
hf_hub_download(repo_id="InstantX/InstantID", filename="ControlNetModel/config.json", local_dir="./checkpoints")
hf_hub_download(repo_id="InstantX/InstantID", filename="ControlNetModel/diffusion_pytorch_model.safetensors", local_dir="./checkpoints")
hf_hub_download(repo_id="InstantX/InstantID", filename="ip-adapter.bin", local_dir="./checkpoints")

# !pip install opencv-python transformers accelerate insightface
import diffusers
from diffusers.utils import load_image
from diffusers.models import ControlNetModel

import cv2
import torch
import numpy as np
from PIL import Image

from insightface.app import FaceAnalysis
from pipeline_stable_diffusion_xl_instantid import StableDiffusionXLInstantIDPipeline, draw_kps

app = FaceAnalysis(name='antelopev2', root='./', providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
app.prepare(ctx_id=0, det_size=(640, 640))

face_adapter = f'./checkpoints/ip-adapter.bin'
controlnet_path = f'./checkpoints/ControlNetModel'

controlnet = ControlNetModel.from_pretrained(controlnet_path, torch_dtype=torch.float16)

pipe = StableDiffusionXLInstantIDPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0", controlnet=controlnet, torch_dtype=torch.float16
... )
pipe.cuda()

pipe.load_ip_adapter_instantid(face_adapter)

How to use it: Once the pipeline is loaded, you hand it one face photo and a prompt. The sample reads the face from your photo, then draws the new image. Set prompt to the picture you want first.

image = load_image("your-example.jpg")
face_info = app.get(cv2.cvtColor(np.array(face_image), cv2.COLOR_RGB2BGR))
face_emb = face_info['embedding']
face_kps = draw_kps(face_image, face_info['kps'])
pipe.set_ip_adapter_scale(0.8)
image = pipe(
...     prompt, image_embeds=face_emb, image=face_kps, controlnet_conditioning_scale=0.8
... ).images[0]

Tool | What it does
FaceAnalysis | Finds the face in your photo and returns its embedding and key points
draw_kps | Draws the face key points into an image the pipeline uses as guidance
StableDiffusionXLInstantIDPipeline | Makes the picture from your prompt and the face data
set_ip_adapter_scale | Sets the adapter strength, 0.8 in the sample
controlnet_conditioning_scale | Sets the IdentityNet strength, 0.8 in the sample

Example: You have one clear photo of a friend who agreed to it. You keep the adapter strength at 0.8, write a prompt for an old film-camera look with grain and faded color, and pass in the face data. You get one new image of that same person in the film style.

For newcomers and experts: You give the model one photo of a face and a sentence about the picture you want, and it draws that person in the new scene. The first small thing to try is the hosted demo the card links, before you install anything.

Under the hood, the face encoder pulls an embedding and key points from the photo. A ControlNet named IdentityNet takes the key points, and an IP-Adapter carries the embedding, both attached to the Stable Diffusion XL base model. Two scales set how strong each part is. Stronger identity can raise saturation and weaken how well the prompt steers the result. The sample keeps only the largest face it finds.

Your face photo
Face encoder finds embedding and key points
IdentityNet and adapter guide the base model
Your prompt sets the style and scene
New image of the same person

Good to know:

• Pipeline file: the sample imports a pipeline file the card text does not include, so follow the card's pointer to the project's code repository for it.
• Similarity: if the face does not match enough, raise both the IdentityNet strength and the adapter strength.
• Saturation: if colors look too strong, lower the adapter strength first, then the IdentityNet strength.
• Text control: if the prompt is not followed well, lower the adapter strength.
• Realism: for a more realistic style, the card advises a more realistic base model from the project's code repository.
• License: Apache 2.0, as the model's License line says.
• Cost to run: no API key, account or paid service is named. You run it on your own hardware, and the sample uses a CUDA graphics card.
• Data it reaches: your photo files on disk, and Hugging Face for the model downloads. The face encoder is downloaded by hand.
• Not for: the card tells users to follow local laws and use it responsibly, and says the developers take no responsibility for misuse.

On Hugging Face, 13 November 2026

• Task: text to image
• Library: diffusers
• Formats: Safetensors
• Downloads in the last 30 days: 84,085
• Likes: 895
• License: apache-2.0
• Languages: en
• Tags: diffusers, safetensors, text-to-image

Links

• Model: https://huggingface.co/InstantX/InstantID
• Files: https://huggingface.co/InstantX/InstantID/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download InstantX/InstantID

Then follow the usage in its model card. Nothing in this kit runs by itself.