Skip to main content

Instant-ID

Instant-ID

Base URLs:

  • https://api.novita.ai

POST Instant-ID

POST /v3/async/instant-id

Customizing Realistic Human Photos via Stacked ID Embedding, for asynchronous image generation, only a task_id will be returned. You should use the task_id to make a call to the https://novita.ai/reference/task/task.htmlopen in new window endpoint in order to retrieve the image generation results.

Request header parameters

  • AuthorizationstringRequired

Request Body parameters

  • extraobject

    extra infos.

    Show properties

  • model_namestringRequired

    Name of SDXL based model, you can call the /v3/model endpoint with parameter filter.types=checkpoint to retrieve the sd_name_in_api field as the model_name. Recomment model_name: sdxlUnstableDiffusers_v8HEAVENSWRATH_133813.safetensors

  • face_image_assets_ids[string]

    Get asset id with guidance https://novita.ai/reference/face_editor/instant-id.html#get-image-assets-id.

  • face_image_urls[string]

    face_image_urls is the URL for face images. It should allow the HEAD HTTP method to check the file size, and the image size needs to be smaller than 10MB.

  • ref_image_assets_ids[string]

    Get asset id with guidance https://novita.ai/reference/face_editor/instant-id.html#get-image-assets-id.

  • ref_image_urls[string]

    ref_image_urls is the URL for reference images. It should allow the HEAD HTTP method to check the file size, and the image size needs to be smaller than 10MB.

  • promptstringRequired

    Positive prompt word, divided by `,`, Range [1, 512]

  • negative_promptstringRequired

    Negtive prompt word, divided by `,`, Range [1, 512]

  • controlnetobject

    ControlNet Units to use for InstantID.

    Show properties

  • loras[object]

    Lora options, currenlty supports up to 5 Lora, only support SDXL LoRA

    Show properties

  • id_strengthnumber(float)Required

    Identitynet strength ratio (for fidelity), Range [0, 1.5]

  • adapter_strengthnumber(float)Required

    Adapter strength ratio (for detail), Range [0, 1.5]

  • widthintegerRequired

    Width of image, Range [128, 1024]

  • heightintegerRequired

    Height of image, Range [128, 1024]

  • image_numintegerRequired

    images numbers generated in one single generation, Range [1, 8]

  • stepsintegerRequired

    Think of steps as iterations of the image creation process, Range [1, 100]

  • seedintegerRequired

    A seed is a number from which Stable Diffusion generates noise, Minimum -1

  • guidance_scalenumberRequired

    This setting says how close the Stable Diffusion will listen to your prompt, Range [1, 10]

  • sampler_namestringRequired

    This denoising process is called sampling because Stable Diffusion generates a new sample image in each step.

    Enum: Euler a,Euler,LMS,Heun,DPM2,DPM2 a,DPM++ 2S a,DPM++ 2M,DPM++ SDE,DPM fast,DPM adaptive,LMS Karras,DPM2 Karras,DPM2 a Karras,DPM++ 2S a Karras,DPM++ 2M Karras,DPM++ SDE Karras,DDIM,PLMS,UniPC

  • clip_skipinteger

    Clip Skip to use for InstantID, Range [1, 12]

Responses

  • task_idstring

Example

Customizing Realistic Human Photos via Stacked ID Embedding. The returned photos can be access by API /v3/async/task-result with task_id.

Please set the Content-Type header to application/json in your HTTP request to indicate that you are sending JSON data. Currently, only JSON format is supported.

Get image assets id

Request:

curl -X PUT -T "{{image file path}}" 'https://assets.novitai.com/image'

Response:

{
    "assets_id":"cjIvbm92aXRhLWFpLWFzc2V0L2ltYWdlL2lHc2VkR2NOQjRaS000YThRUkQ3MmVoUVo1c0tDelBK"
}

Python Request:

import requests

# Replace the following variables with their respective values:
image_file_path = r"/home/local/test.png"
url = 'https://assets.novitai.com/image'

# Send a PUT request
with open(image_file_path, 'rb') as file:
    response = requests.put(url, data=file)

# Print the response
print(response.text)

Response:

{
    "assets_id":"cjIvbm92aXRhLWFpLWFzc2V0L2ltYWdlL2lHc2VkR2NOQjRaS000YThRUkQ3MmVoUVo1c0tDelBK"
}

Request Instant-ID API

Use image assets id generated from step 20.1 to request API. Current only SDXL based model supported.

Below are the supported models, We recommend using the sdxlUnstableDiffusers_v8HEAVENSWRATH_133813.safetensors model for better results:

albedobaseXL_v04_130099.safetensors
altxl_v60_146691.safetensors
animeArtDiffusionXL_alpha2_91872.safetensors
animeArtDiffusionXL_alpha3_93120.safetensors
animeIllustDiffusion_v04_117809.safetensors
breakdomainxl_V05g_124265.safetensors
brixlAMustInYour_v40Dagobah_145992.safetensors
cinemaxAlphaSDXLCinema_alpha1_107473.safetensors
cineroXLPhotomatic_v12aPHENO_137703.safetensors
clearhungAnimeXL_v10_117716.safetensors
copaxTimelessxlSDXL1_colorfulV2_100729.safetensors
counterfeitxl__98184.safetensors
counterfeitxl_v10_108721.safetensors
crystalClearXL_ccxl_97637.safetensors
dreamshaperXL09Alpha_alpha2Xl10_91562.safetensors
dynavisionXLAllInOneStylized_alpha036FP16Bakedvae_99980.safetensors
dynavisionXLAllInOneStylized_beta0411Bakedvae_109970.safetensors
dynavisionXLAllInOneStylized_release0534bakedvae_129001.safetensors
fenrisxl_145_134980.safetensors
foddaxlPhotorealism_v45_122788.safetensors
formulaxl_v10_104889.safetensors
juggernautXL_version2_113240.safetensors
juggernautXL_version5_126522.safetensors
kohakuXL_alpha7_111843.safetensors
LahMysteriousSDXL_v40_122478.safetensors
leosamsHelloworldSDXLModel_helloworldSDXL10_112178.safetensors
mbbxlUltimate_v10RC_94686.safetensors
moefusionSDXL_v10_114018.safetensors
nightvisionXLPhotorealisticPortrait_beta0681Bakedvae_108833.safetensors
nightvisionXLPhotorealisticPortrait_beta0702Bakedvae_113098.safetensors
nightvisionXLPhotorealisticPortrait_release0770Bakedvae_154525.safetensors
novaPrimeXL_v10_107899.safetensors
pixelwave_v10_117722.safetensors
protovisionXLHighFidelity3D_beta0520Bakedvae_106612.safetensors
protovisionXLHighFidelity3D_release0620Bakedvae_131308.safetensors
protovisionXLHighFidelity3D_release0630Bakedvae_154359.safetensors
realismEngineSDXL_v05b_131513.safetensors
realismEngineSDXL_v10_136287.safetensors
realisticStockPhoto_v10_115618.safetensors
RealitiesEdgeXL_4_122673.safetensors
realvisxlV20_v20Bakedvae_129156.safetensors
riotDiffusionXL_v20_139293.safetensors
roxl_v10_109354.safetensors
sd_xl_base_0.9.safetensors
sd_xl_base_1.0.safetensors
sdxlNijiSpecial_sdxlNijiSE_115638.safetensors
sdxlNijiV3_sdxlNijiV3_104571.safetensors
sdxlNijiV51_sdxlNijiV51_112807.safetensors
sd_xl_refiner_1.0.safetensors
sdxlUnstableDiffusers_v8HEAVENSWRATH_133813.safetensors
sdXL_v10Refiner_91495.safetensors
sdxlYamersAnimeUltra_yamersAnimeV3_121537.safetensors
shikianimexl_v10_93788.safetensors
stable-diffusion-xl-1.0-inpainting-0.1.safetensors
stable-diffusion-xl-base-1.0.safetensors
theTalosProject_v10_117893.safetensors
thinkdiffusionxl_v10_145931.safetensors
voidnoisecorexl_r1486_150780.safetensors
wlopArienwlopstylexl_v10_101973.safetensors
wlopSTYLEXL_v2_126171.safetensors
xl13AsmodeusSFWNSFW_v22BakedVAE_111954.safetensors
xxmix9realisticsdxl_v10_123235.safetensors
zavychromaxl_b2_103298.safetensors
zavychromaxl_v21_129006.safetensors

Request:

curl --location 'https://api.novita.ai/v3/async/instant-id' \
--header 'Authorization: Bearer {{key}}' \
--header 'Content-Type: application/json' \
--data '{
    "extra": {
        "response_image_type": "jpeg"
    },
    "model_name": "sdxlUnstableDiffusers_v11_216694.safetensors",
    "face_image_assets_ids": [
        "cjIvbm92aXRhLWFpLWFzc2V0L2ltYWdlLzR4WUh4SEFyTUV4UlhTTkN5VEtqa2ppZjNoUDQ2ZkVQ"
    ],
    "ref_image_assets_ids": [
        "cjIvbm92aXRhLWFpLWFzc2V0L2ltYWdlL1NITkRUejI3SmREc25hV3l5NU1XUlhySGhLVGp3clFq"
    ],
    "prompt": "a young woman with perfect figure, wearing a floral dress",
    "negative_prompt": "realistic, photo-realistic, bad quality, bad anatomy, worst quality, low quality, lowres, extra fingers, blur, blurry, ugly, wrong proportions, watermark, image artifacts, bad eyes, bad hands, bad arms",
    "loras": [
        {
            "model_name": "BoutXOval_SDXL_dim32-000005_92430.safetensors",
            "strength": 0.8
        }
    ],
    "height": 1024,
    "width": 768,
    "id_strength": 0.8,
    "adapter_strength": 0.8,
    "image_num": 1,
    "steps": 25,
    "seed": -1,
    "guidance_scale": 7.5,
    "sampler_name": "Euler"
}'

Response:

{
    "task_id": "248f525b-edf9-4265-aa8a-8cf4c19bfe67"
}

Use task_id to get images

HTTP status codes in the 2xx range indicate that the request has been successfully accepted, while status codes in the 5xx range indicate internal server errors.

You can get result in images of response.

Request:

curl --location --request GET 'https://api.novita.ai/v3/async/task-result?task_id=248f525b-edf9-4265-aa8a-8cf4c19bfe67' \
--header 'Authorization: Bearer {{key}}'

Response:

{
    "extra": {
        "seed": "1099016411",
        "enable_nsfw_detection": false
    },
    "task": {
        "task_id": "248f525b-edf9-4265-aa8a-8cf4c19bfe67",
        "task_type": "INSTANT_ID",
        "status": "TASK_STATUS_SUCCEED",
        "reason": "",
        "eta": 0,
        "progress_percent": 0
    },
    "images": [
        {
            "image_url": "https://faas-output-image.s3.ap-southeast-1.amazonaws.com/prod/248f525b-edf9-4265-aa8a-8cf4c19bfe67/de995d778d474da5aff3c724553939ff.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASVPYCN6LRCW3SOUV%2F20240224%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20240224T121926Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=8a98b59d44c39b0c82ae31d351f94663ace0cbbf57041e9d073d96d6d0e7c2f5",
            "image_url_ttl": "3600",
            "image_type": "jpeg",
            "nsfw_detection_result": null
        }
    ],
    "videos": []
}