# API V2 to V3 Migration Guide - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/guides/model-apis-v2-to-v3-migration

# API V2 to V3 Migration Guide

##

[​](#text-to-image)

Text to Image

###

[​](#request-body-parameter-mapping)

Request Body Parameter Mapping

V2V3Descriptionextraobjectextraobjectenable_nsfw_detection
booleanenable_nsfw_detection
booleannsfw_detection_level
Enum: `0, 1, 2`nsfw_detection_level
Enum: `0, 1, 2`enable_progress_infoDeprecatedresponse_image_type
Enum: `png`, `jpeg`response_image_type
Enum: `png, webp, jpeg`V3 adds support for `webp`image formatrequestobjectNew Field
All image generation parameters must be passed via the `request`in V3promptstring
<lora:$sd_name:$weight>promptstringMoved Insidelorasobject[]Moved Inside
Migrate LoRA usage: From `prompt` to `request.loras` parametermodel_namestringNew Field
Name of lora, retrieve the corresponding sd_name_in_api value by invoking the [Get Model API](https://novita.ai/docs/api-reference/model-apis-get-model) endpoint with filter.types=lora as the query parameter.strengthnumber(float32)New Field
The strength value of lora. The larger the value, the more biased the effect is towards lora, Range [0, 1]negative_promptstringnegative_promptstringMoved Insidesampler_namestringsampler_namestringMoved Insidebatch_sizeintegerimage_numintegerChanged
`num_images` → `request.image_num`n_iterDeprecatedstepsstringstepsstringMoved Insidecfg_scaleintegerguidance_scale
number(float32)Changed
`cfg_scale`→ `request.guidance_scale`seedintegerseedintegerMoved InsideheightintegerheightintegerMoved Inside
Range Change: [128, 2048].widthintegerwidthintegerMoved Inside
Range Change: [128, 2048].model_namestringmodel_namestringMoved Inside
This parameter specifies the name of the model checkpoint. Retrieve the corresponding sd_name value by invoking the [Query Model](https://novita.ai/docs/api-reference/model-apis-get-model) API with filter.types=checkpoint as the query parameter.restore_facesboolrestore_facesboolMoved Insiderestore_faces_modelDeprecatedsd_vaestringsd_vaestringMoved Insideclip_skipintegerclip_skipintegerMoved Insideenable_hrbooleanhires_fixobjectChanged
`enable_hr`→ `request.hires_fix`hr_upscaler
Enum:
`Latent`, `ESRGAN_4x`, `R-ESRGAN 4x+`, `R-ESRGAN 4x+ Anime6B`upscaler
Enum: `RealESRGAN_x4plus_anime_6B`, `RealESRNet_x4plus,Latent`Changed
`hr_upscaler`→`request.hires_fix.upscaler`hr_scalenumberDeprecatedhr_resize_xintegertarget_widthintegerChanged
`hr_resize_x`→ `request.hires_fix.target_width`hr_resize_yintegertarget_heightintegerChanged
`hr_resize_y`→ `request.hires_fix.target_height`img_expire_ttlintegerDeprecated
Default 3600ssd_refinerobjectrefinerobjectChanged
`sd_refiner`→ `request.refiner`checkpointstringDeprecatedswitch_at
number(float32)switch_at
number(float32)Changed
`sd_refiner.switch_at`→ `request.refiner.switch_at`controlnet_unitsobject[]Deprecated
`img2img` Only

###

[​](#response-parameter-mapping)

Response Parameter Mapping

V2V3DescriptioncodeDeprecatedmsgDeprecateddataDeprecatedtask_idtask_idChanged
`data.task_id`→ `task_id`warnDeprecated

###

[​](#example)

Example

## Text to Image V2

- Request

```
curl --location "https://api.novita.ai/v2/txt2img" \
--header "Authorization: Bearer {{API Key}}" \
--header "Content-Type: application/json" \
--data '{
"extra": {
"enable_nsfw_detection": false,
"nsfw_detection_level": 0,
"response_image_type": "jpeg"
},
"prompt": "(masterpiece, best quality, ultra-detailed:1.3), , 1girl, mecha armor, futuristic city background, glowing neon lights, dynamic pose, cyberpunk style, intricate mechanical details, (floating holographic interface:1.2), sparkling blue eyes, wind-blown hair, (steam and energy particles:1.1), cinematic lighting",
"negative_prompt":"(worst quality, low quality:1.4), (deformed, distorted:1.3), disfigured, blurry, bad anatomy, extra limbs, (mutated hands:1.2), (text, watermark:1.5),
overexposed, underexposed, (cartoonish:1.2), (simplistic background:1.3),
grainy, (traditional drawing:1.2), (realistic:1.4), (noisy:1.3)",
"sampler_name":"DPM++ 2M Karras",
"batch_size": 1,
"n_iter": 1,
"steps": 25,
"cfg_scale": 7,
"seed": 65531,
"height": 512,
"width": 512,
"model_name": "sd_xl_base_1.0.safetensors",
"restore_faces": false,
"restore_faces_model": "",
"sd_vae": "",
"clip_skip": 1,
"enable_hr": true,
"hr_upscaler": "Latent",
"hr_scale": 2,
"hr_resize_x": 1024,
"hr_resize_y": 1024,
"img_expire_ttl": 3600
}'
```

- Response

```
{
"code": 0,
"msg": "",
"data": {
"task_id": "12905b6a-d436-4010-b199-d800130c0aab"
}
}
```

## Text to Image V3

- Reqeust

```
curl --location 'https://api.novita.ai/v3/async/txt2img' \
--header 'Authorization: Bearer {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
"extra": {
"enable_nsfw_detection": false,
"nsfw_detection_level": 0,
"response_image_type": "jpeg"
},
"request": {
"prompt": "(masterpiece, best quality, ultra-detailed:1.3), 1girl, mecha armor, futuristic city background, glowing neon lights, dynamic pose, cyberpunk style, intricate mechanical details,(floating holographic interface:1.2), sparkling blue eyes, wind-blown hair, (steam and energy particles:1.1), cinematic lighting",
"negative_prompt": "(worst quality, low quality:1.4), (deformed, distorted:1.3), disfigured,blurry, bad anatomy, extra limbs, (mutated hands:1.2), (text, watermark:1.5),overexposed, underexposed,(cartoonish:1.2), (simplistic background:1.3), grainy, (traditional drawing:1.2),(realistic:1.4), (noisy:1.3)",
"model_name": "sd_xl_base_1.0.safetensors",
"width": 512,
"height": 512,
"image_num": 1,
"steps": 25,
"seed": 65531,
"restore_faces": false,
"clip_skip": 1,
"sampler_name":"DPM++ 2M Karras",
"guidance_scale": 7,
"hires_fix": {
"target_width": 1024,
"target_height": 1024,
"strength": 0.8,
"upscaler": "Latent"
},
"loras": [
{
"model_name": "AnimeStyle_XL_v1_AutoRunMech_103883",
"strength": 0.8
}
]
}
}'
```

- Repspone

```
{
"task_id":"0696ce57-22df-4a89-9efc-80c386a82dbd"
}
```

##

[​](#image-to-image)

Image to Image

###

[​](#request-body-parameter-mapping-2)

Request Body Parameter Mapping

V2V3Descriptionextraobjectextraobjectenable_nsfw_detection
booleanenable_nsfw_detection
booleannsfw_detection_level
Enum: `0, 1, 2`nsfw_detection_level
Enum: `0, 1, 2`enable_progress_infoDeprecatedresponse_image_type
Enum: `png`, `jpeg`response_image_type
Enum: `png, webp, jpeg`V3 adds support for `webp`image formatrequestobjectNew field
All image generation parameters must be passed via the `request`in V3promptstring
<lora:$sd_name:$weight>promptstringMoved Insidelorasobject[]Moved Inside
Migrate LoRA usage: From `prompt` to `request.loras` parametermodel_namestringNew Field
Name of lora, retrieve the corresponding sd_name_in_api value by invoking the [Get Model API](https://novita.ai/docs/api-reference/model-apis-get-model) endpoint with filter.types=lora as the query parameter.strength
number(float32)New Field
The strength value of lora. The larger the value, the more biased the effect is towards lora, Range [0, 1]negative_promptstringnegative_prompt
stringMoved Insidesampler_namestringsampler_namestringMoved Insidebatch_sizeintegerimage_numintegerChanged
`batch_size`→ `request.image_num`n_iterintegerDeprecatedstepsstringstepsstringMoved Insidecfg_scaleintegerguidance_scale
number(float32)Changed
`cfg_scale`→ `request.guidance_scale`seedintegerseedintegerMoved InsideheightintegerheightintegerMoved Inside
Range Change: [128, 2048].widthintegerwidthintegerMoved Inside
Range Change: [128, 2048].model_namestringmodel_namestringMoved Inside
This parameter specifies the name of the model checkpoint. Retrieve the corresponding sd_name value by invoking the [Query Model](https://novita.ai/docs/api-reference/model-apis-get-model) API with filter.types=checkpoint as the query parameter.init_imagesstring[]image_base64stringChanged
`init_images`→ `request.image_base64`denoising_strength
number(float)strength
number(float)Changed
`denoising_strength`→ `request.strength`restore_facesboolDeprecatedsd_vaestringsd_vaestringMoved Insideclip_skipintegerclip_skipintegerMoved InsidemaskstringDeprecated
Recommendation: Use V3 Inpainting APImask_blurintegerDeprecated
Recommendation: Use V3 Inpainting APIresize_modeintegerDeprecatedimage_cfg_scaleintegerDeprecatedinpainting_fillintegerDeprecated
Recommendation: Use V3 Inpainting APIinpaint_full_resintegerDeprecated
Recommendation: Use V3 Inpainting APIinpaint_full_res_padding
integerDeprecated
Recommendation: Use V3 Inpainting APIinpainting_mask_invert
integerDeprecated
Recommendation: Use V3 Inpainting APIinitial_noise_multiplier
number(float32)Deprecatedimg_expire_ttlintegerDeprecated
Default 3600ssd_refinerobjectrefinerobjectChanged
`sd_refiner`→ `request.refiner`checkpointDeprecatedswitch_at
number(float32)switch_at
number(float32)Moved InsidecontrolnetobjectNew Fieldcontrolnet_unitsobject[]unitsobject[]Changed
`controlnet_units`→ `request.controlnet.units`modelstringmodel_name
stringChanged
`controlnet_units.model`→
`request.controlnet.units.model_name`weightnumberstrength
number(float32)Changed
`controlnet_units.weight`→
`request.controlnet.units.strength`input_imagestringimage_base64
stringChanged
`controlnet_units.input_image`→
`request.controlnet.units.image_base64`modulestring,Enumpreprocessor
string,EnumChanged
`controlnet_units.module`→
`request.controlnet.units.preprocessor`control_modeDeprecatedmaskDeprecated
Recommendation: Use V3 Inpainting APIresize_modeDeprecatedprocessor_resDeprecatedthreshold_aDeprecatedthreshold_bDeprecatedguidance_start
number(float32)guidance_start
number(float32)Moved Insideguidance_end
number(float32)guidance_end
number(float32)Moved Insidepixel_perfectDeprecated

###

[​](#response-parameter-mapping-2)

Response Parameter Mapping

V2V3DescriptioncodeDeprecatedmsgDeprecateddataDeprecatedtask_idtask_idChanged
`data.task_id`→ `task_id`warnDeprecated

###

[​](#example-2)

Example

## Image to Image V2

- Request

```
curl --request POST \
--url https://api.novita.ai/v2/img2img \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"extra": {
"enable_nsfw_detection": false,
"nsfw_detection_level": 0,
"response_image_type": "png"
},
"prompt": "realistic, photograph, (masterpiece), 8k quality, (detailed eyes:1.2), (highest quality:1.1), highly detailed, majestic, top quality, best quality, newest, ai-generated, (intricate details:1.1), extremely beautiful, elegant, majestic, immersive background+, (detailed face, perfect face), In the heart of a vibrant garden, a girl with red hair and brown eyes sits in contemplation of the nature around her.",
"negative_prompt": "(worst quality:1.5), (low quality:1.5), (normal quality:1.5), anime, cartoon, painting, drawing, illustration, manga, sketch, nudity, young, child, hairband, headband, horns, lowres, bad anatomy, bad hands, multiple eyebrow, (cropped), extra limb, missing limbs, deformed hands, long neck, long body, long torso, (bad hands), signature, username, artist name, conjoined fingers, deformed fingers, ugly eyes, imperfect eyes, skewed eyes, unnatural face, unnatural body, error, grain, jpeg artifacts",
"sampler_name":"DPM++ 2M Karras",
"batch_size": 1,
"n_iter": 1,
"steps": 25,
"cfg_scale": 7.5,
"seed": 765824,
"height": 768,
"width": 512,
"model_name": "cyberrealistic_v31_62396.safetensors",
"init_images": [
""
],
"denoising_strength": 0.8,
"restore_faces": false,
"clip_skip": 1,
"img_expire_ttl": 3600,
"controlnet_units": {
"model": "control_v11p_sd15_lineart",
"weight": 1,
"input_image": "",
"module": "lineart",
"guidance_start": 0,
"guidance_end": 1
}
}'
```

- Response

```
{
"code": 0,
"msg": "",
"data": {
"task_id": "a1b0d99b-2ef0-4b20-8eeb-c641ae84ed45"
}
}
```

## Image to Image V3

- Request

```
curl --request POST \
--url https://api.novita.ai/v3/async/img2img \
--header 'Authorization: ' \
--header 'Content-Type: ' \
--data '{
"extra": {
"enable_nsfw_detection": false,
"nsfw_detection_level": 0,
"response_image_type": "png"
},
"request": {
"prompt": "realistic, photograph, (masterpiece), 8k quality, (detailed eyes:1.2), (highest quality:1.1), highly detailed, majestic, top quality, best quality, newest, ai-generated, (intricate details:1.1), extremely beautiful, elegant, majestic, immersive background+, (detailed face, perfect face), In the heart of a vibrant garden, a girl with red hair and brown eyes sits in contemplation of the nature around her.",
"negative_prompt": "(worst quality:1.5), (low quality:1.5), (normal quality:1.5), anime, cartoon, painting, drawing, illustration, manga, sketch, nudity, young, child, hairband, headband, horns, lowres, bad anatomy, bad hands, multiple eyebrow, (cropped), extra limb, missing limbs, deformed hands, long neck, long body, long torso, (bad hands), signature, username, artist name, conjoined fingers, deformed fingers, ugly eyes, imperfect eyes, skewed eyes, unnatural face, unnatural body, error, grain, jpeg artifacts",
"sampler_name": "DPM++ 2M Karras",
"image_num": 1,
"steps": 25,
"guidance_scale": 7.5,
"seed": 765824,
"height": 768,
"width": 512,
"model_name": "cyberrealistic_v31_62396.safetensors",
"image_base64": "",
"strength": 0.8,
"clip_skip": 1,
"controlnet": {
"units": [
{
"model_name": "control_v11p_sd15_lineart",
"strength": 1,
"image_base64": "",
"preprocessor": "lineart",
"guidance_start": 0,
"guidance_end": 1
}
]
}
}
}'
```

- Response

```
{
"task_id": "9490dde7-cd28-493e-9db0-8a38a65bf5e6"
}
```

Last modified on April 9, 2025