POST
/
v3
/
async
/
instant-id

Customizing realistic human photos via Stacked ID Embedding.

This is an asynchronous API; only the task_id will be returned. You should use the task_id to request the Task Result API to retrieve the image generation results.

​
Request Headers

​
Content-Type
string
required

Enum: application/json

​
Authorization
string
required

Bearer authentication format, for example: Bearer {{API Key}}.

​
Request Body

​
extra
object

Optional extra parameters for the request.

​
model_name
string
required

Name of the SDXL-based model. Retrieve the corresponding sd_name value by invoking the Query Model API with filter.types=checkpoint&filter.is_sdxl=true as the query parameter. Recommended model_name: sdxlUnstableDiffusers_v8HEAVENSWRATH_133813.safetensors.

​
face_image_assets_ids
string[]
required

Get asset ID with guidance from Get image assets ID.

​
ref_image_assets_ids
string[]
required

Get asset ID with guidance from Get image assets ID.

​
prompt
string
required

Text input required to guide the image generation, divided by , . Range [1, 1024].

​
width
integer
required

Width of image. Range [128, 2048].

​
height
integer
required

Height of image. Range [128, 2048].

​
image_num
integer
required

Number of images generated in a single request. Range [1, 4].

​
steps
integer
required

The number of denoising steps. More steps usually can produce higher quality images, but take more time to generate, Range [1, 100].

​
guidance_scale
number(float32)
required

This setting says how close the Stable Diffusion will listen to your prompt, higer guidance forces the model to better follow the prompt, but result in lower quality output. Range [1, 30].

​
sampler_name
string
required

This parameter determines the denoising algorithm employed during the sampling phase of Stable Diffusion. Each option represents a distinct method by which the model incrementally generates new images. These algorithms differ significantly in their processing speed, output quality, and the specific characteristics of the images they generate, allowing users to tailor the image generation process to meet precise requirements. Get reference at A brief introduction to Sampler.
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

​
negative_prompt
string

Text input that specifies what to exclude from the generated images, divided by , . Range [1, 1024].

​
controlnet
object

ControlNet Units to use for InstantID.

​
seed
integer

A seed is a number from which Stable Diffusion generates noise, which, makes generation deterministic. Using the same seed and set of parameters will produce identical image each time, minimum -1. Defaults to -1.

​
id_strength
number(float)

IdentityNet strength ratio (for fidelity), where 0 represents minimal influence and 1.5 indicates maximum intensity. Range [0, 1.5].

​
adapter_strength
number(float)

Adapter strength ratio (for detail), where 0 represents the least detail enhancement and 1.5 ensures the highest level of detail. Range [0, 1.5].

​
loras
object[]

LoRA is a fast and lightweight training method that inserts and trains a significantly smaller number of parameters instead of all the model parameters. Currently supports up to 5 LoRAs.

​
clip_skip
integer

This parameter indicates the number of layers to stop from the bottom during optimization, so clip_skip on 2 would mean, that in SD1.x model where the CLIP has 12 layers, you would stop at 10th layer, Range [1, 12], get reference at A brief introduction to Clip Skip.

​
face_kps_assets_ids
string[]

This optional parameter represents an image with keypoints. If provided, it will be used to enhance the face analysis process, and the size needs to match that of face_image_assets_ids. Get asset ID with guidance from Get image assets ID.

​
control_guidance_start
number(float)

This parameter is a floating-point value that specifies the starting point of the process. It determines when the process should begin. Range [0, 1.0], default is 0.0.

​
control_guidance_end
number(float)

This parameter is a floating-point value that specifies the ending point of the process. It determines when the process should end. Range [0, 1.0], default is 1.0.

​
Response

​
task_id
string

Use the task_id to request the Task Result API to retrieve the generated outputs.

​
Example

Customize realistic human photos via Stacked ID Embedding. The returned photos can be accessed via the API /v3/async/task-result using the 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 {{API 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 {{API 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": []
}

Was this page helpful?

Video Merge FaceGet Images URL