Multimodal AI

AI Model Swap API

Generate model images by combining a source product image with a model head image, optional masks, scene references, and prompt guidance.

post/api/skill-api/v1/skills/ai-model-swap/run

Request

  • Base URL: https://api.nexscope.ai
  • URL: https://api.nexscope.ai/api/skill-api/v1/skills/ai-model-swap/run
  • Auth: HTTP bearer

Headers

X-Nexscope-Http-Status'legacy' | 'semantic'

Use semantic for HTTP error statuses on run and task-result requests. Without this header v1 retains legacy status behavior. The JSON envelope is unchanged; code 0 means success or acceptance, not asynchronous completion.

Request body

imageUrlstring required

Public URL of the source product or outfit image. The image must be up to 20 MB and between 385 and 8192 pixels in both width and height.

modelHeadImageUrlstring required

Public URL of the target model head image. The image must be up to 5 MB and between 512 and 2048 pixels in both width and height.

imageSegUrlstring

Optional segmentation mask URL for the source image.

sceneImgUrlstring

Optional scene reference image URL. The image must be up to 10 MB and between 768 and 4096 pixels in both width and height.

sceneStrengthnumber

Scene reference strength from 0 to 1. Defaults to 0.7.

modelPromptstring

Comma-separated model appearance terms, such as smile, laugh, sitting, lying, fat, plump, slim, sideways, profile, back, or bald.

customPromptstring

Positive generation prompt, up to 600 characters.

customNegPromptstring

Negative prompt to avoid unwanted artifacts.

genOriResboolean

Whether to generate the original resolution. Defaults to false.

realModelboolean

Whether to prefer a realistic model style.

outputNuminteger

Number of images to generate, from 1 to 4. Defaults to 1.

Example request

{
  "imageUrl": "https://example.com/source-image.jpg",
  "modelHeadImageUrl": "https://example.com/model-reference.jpg",
  "imageSegUrl": "https://example.com/mask.png",
  "sceneImgUrl": "https://example.com/scene.jpg",
  "sceneStrength": 0.7,
  "modelPrompt": "smile, slim",
  "customPrompt": "clean ecommerce catalog photo",
  "customNegPrompt": "blur, distorted hands",
  "genOriRes": false,
  "realModel": true,
  "outputNum": 1
}

Response

Successful response.

codeinteger required

0 means accepted or successful; nonzero is a platform error.

msgstring nullable required
tsstring required

Epoch milliseconds.

timestring required

Server local time: yyyy-MM-dd HH:mm:ss.

coststring required

Elapsed milliseconds, never credits; -1 outside web requests.

traceIdstring nullable required

Changes

No recorded changes to this operation across all 1 revision of this API.