API Documentation

Integrate VistoureAI's world-class generational models natively into your retail, e-commerce, or creative applications in minutes.

Developer Friendly

Predictable asynchronous architecture. Hand off intensive workloads instantly, track status reliably, and get results when ready.

Secure by Design

All REST interactions require encrypted AES Bearer authentication. Your models and clothing IP are rigorously sandboxed.

3-Day Retention

Outputs are intelligently cached via CDN for lightning fast delivery and natively retained on our secure S3 cluster for 3 days.

Authentication

All endpoints under /api/v3/* require your API key passed in the headers. You can generate one inside the Developer API Dashboard.

X-API-KEY: <your_api_key_here>

Unified Execution

Execute a single AI tool or a saved multi-node workflow through a single unified endpoint.

POST/api/v3/run

Initiate an asynchronous generation. Use type='node' for single tools or type='workflow' for saved workflows.

Parameters

Parameter	Type	Description
typeRequired	string	Run type: 'node' (single tool) or 'workflow' (DAG).
targetRequired	string	For type='workflow': Provide the saved workflow name. For type='node': Provide the tool name. Available tools: 'virtual_tryon', 'virtual_tryon_pro', 'virtual_tryon_pro_fit', 'virtual_model', 'fabric', 'sketch_to_dress', 'upscale', 'multipose', 'video', 'background_removal', 'reframe', 'product_shoot'.
inputRequired	object	Required based on target. Provide input parameters or overrides. Note: All image parameters (e.g. 'model_image') must be public URLs or base64 strings. For workflows, format as 'node_name.param_name'. For type='node', format as standard key-value pairs.

Request Body Example

JSON

{
  "type": "workflow",
  "target": "My Custom Model Workflow",
  "input": {
    "User_Garment.garment_image": "https://example.com/new_shirt.jpg"
  }
}

Expected Response

JSON200 OK

{
  "id": "wr_abc123xyz7890123",
  "error": null
}

GET/api/v3/status/{run_id}

Poll for execution results. Returns a detailed map of all nodes and their outputs for workflows.

Expected Response

JSON200 OK

{
  "workflow_run_id": "wr_abc123xyz7890123",
  "overall_status": "succeeded",
  "outputs": {
    "result_tryon": "https://example.com/result.jpg"
  },
  "nodes": {
    "User_Garment": {
      "id": "gen_tryon_123",
      "status": "succeeded",
      "output": [
        "https://example.com/result.jpg"
      ],
      "error": null,
      "model_name": "virtual_tryon"
    }
  }
}

Workflow Discovery

Discover and inspect saved workflow templates programmatically.

GET/api/v3/workflow/{workflow_name}

Discover required, optional, and linked inputs for a saved workflow. Note: The returned 'sample_payload' object contains the exact, pre-formatted JSON payload you need to send to the POST /api/v3/run endpoint to execute this workflow.

Expected Response

JSON200 OK

{
  "name": "My_Workflow",
  "outputs": {
    "result_tryon": "User_Garment.result_image"
  },
  "sample_payload": {
    "type": "workflow",
    "target": "My_Workflow",
    "input": {
      "User_Garment.garment_image": "<image>"
    }
  },
  "inputs": {
    "mandatory": {
      "User_Garment.garment_image": "<type:image , default value : null>"
    },
    "optional": {
      "User_Garment.category": "<type:str , default value : 'tops (upper-body)'>"
    },
    "linked": {}
  }
}

Response Fields Description

Field	Type	Description
name	string	The unique name of the saved workflow.
workflow	object	The backend executing model representation of the complete visual React Flow DAG, detailing executing nodes, parent dependencies, and parameter configurations.
sample_payload	object	A pre-formatted JSON payload ready to copy-paste directly into POST /api/v3/run. Includes all mandatory inputs. You can refer to the 'inputs' field below to discover all available mandatory and optional inputs. To pass optional parameters, simply append standard 'node_id.param_key' pairs (e.g., 'Model_Gen.gender': 'male') to the nested 'input' object.
inputs	object	A comprehensive manifest categorized into: 'mandatory' (required inputs to run the workflow), 'optional' (canvas overrides with default values), and 'linked' (automatically mapped upstream parameter pipelines).
outputs	object	Dictionary mapping user-configured Final Workflow Outputs to their source parameters (e.g., 'result_tryon': 'User_Garment.result_image'). Polling status for this run will return S3/CDN URLs structured under these exact keys.

GET/api/v3/workflows

List all custom workflows saved to your account and global system templates.

Expected Response

JSON200 OK

[
  {
    "id": 12,
    "name": "Professional Studio Portrait",
    "system_workflow": true,
    "created_at": "2024-04-26T12:00:00"
  }
]

Integration Guide (Step-by-Step)

Follow this sequence to implement a robust AI generation pipeline in your application.

STEP 1Discover Requirements

Call the info endpoint to see what inputs are needed for your target workflow.

Request Body Example

JSON

GET /api/v3/workflow/Premium_Studio_V1

Expected Response

JSON200 OK

{
  "name": "Premium_Studio_V1",
  "outputs": {
    "result_tryon": "Vton_Node.result_image"
  },
  "sample_payload": {
    "type": "workflow",
    "target": "Premium_Studio_V1",
    "input": {
      "User_Garment.garment_image": "<image>"
    }
  },
  "inputs": {
    "mandatory": {
      "User_Garment.garment_image": "<type:image , default value : null>"
    },
    "optional": {},
    "linked": {}
  }
}

STEP 2Trigger Execution

Use the payload from Step 1 to start the asynchronous generation.

Request Body Example

JSON

POST /api/v3/run
{
  "type": "workflow",
  "target": "Premium_Studio_V1",
  "input": {
    "User_Garment.garment_image": "https://..."
  }
}

Expected Response

JSON200 OK

{
  "id": "wr_6677889900aabbcc",
  "error": null
}

STEP 3Poll for Completion

Call the status endpoint periodically (every 3-5s) until 'overall_status' is 'succeeded'.

Request Body Example

JSON

GET /api/v3/status/wr_6677889900aabbcc

Expected Response

JSON200 OK

{
  "workflow_run_id": "wr_6677889900aabbcc",
  "overall_status": "succeeded",
  "outputs": {
    "result_tryon": "https://vai-web.s3.us-east-2.amazonaws.com/result.png"
  },
  "nodes": {
    "Vton_Node": {
      "id": "gen_vton_667788",
      "status": "succeeded",
      "output": [
        "https://vai-web.s3.us-east-2.amazonaws.com/result.png"
      ],
      "error": null,
      "model_name": "virtual_tryon"
    }
  }
}

Available Generation Tools (Single Node Mode)

Execute any individual AI model by setting type='node' and target to the tool name. Provide the tool-specific parameters inside the input object. Note: All image parameters must be public URLs or base64 strings.

POST/api/v3/run

Run Virtual Try-On single node tool. Target: 'virtual_tryon'

Parameters

Parameter	Type	Description
typeRequired	string	Must be 'node'
targetRequired	string	Must be 'virtual_tryon'
inputRequired	object	Input object for this specific tool. (Images must be URLs or base64)

Input Object Schema

Field	Type	Description
model_name	select	Model (Beta) Default: Beta
model_imageRequired	image	Model Image (URL/base64)
garment_imageRequired	image	Garment Image (URL/base64)
categoryRequired	select	Category (tops, bottoms, dresses) Default: tops
seed	number	Seed

Request Body Example

JSON

{
  "type": "node",
  "target": "virtual_tryon",
  "input": {
    "model_image": "...",
    "garment_image": "...",
    "category": "..."
  }
}

Expected Response

JSON200 OK

{
  "id": "gen_abc123xyz",
  "error": null
}

Frequently Asked Questions

Common integration questions, design patterns, and platform concepts.

1. Can I pass an optional parameter in the run method?

Yes! You can easily override any optional parameter (e.g., prompt, aspect ratio, gender, or upscale factor) that has a default value on your visual canvas nodes.

⚠️IMPORTANT: All mandatory parameters must still be present in the request body. If any mandatory parameter is missing, the workflow execution will fail immediately.

To pass optional parameters, simply append standard "node_id.param_key" pairs inside the nested "input" dictionary. For example:

{
  "type": "workflow",
  "target": "My Custom Model Workflow",
  "input": {
    "User_Garment.garment_image": "https://example.com/new_shirt.jpg", // Mandatory param
    "Model_Gen.gender": "male" // Custom optional override param!
  }
}

2. Can I update a linked input parameter via the API?

No. Parameters that are linked (piped automatically from upstream parent node outputs) are strictly managed by the DAG orchestrator. Trying to override them in your API input payload will be ignored (with a warning logged in the backend) to protect visual workflow logic integrity.

How to update it: You can load your workflow template inside the visual Workflow Engine web interface, modify or remove the link connectors between the nodes on the canvas, and save your workflow. This will instantly decouple the parameter so it can be passed manually via the API or linked to a different upstream node output.

3. Can I change the output variables or friendly names of a workflow?

Yes! Simply open the workflow template in the visual web builder, click on the Workflow Outputs node, update the friendly output variable name (e.g. changing "result_image" to "my_custom_render"), and save the workflow with the same name. The Discovery and Status APIs will automatically start returning outputs mapped under your newly updated keys. You can also use this same approach to change your custom input variable names!

4. How do I create a user-defined variable for an input?

In the website visual canvas builder, add a Workflow Inputs node. Here, you can define your own custom variable name (e.g. "my_garment") and map it to any number of downstream node input parameters simply by dragging connectors. When executing via the API, just pass "my_garment": "https://..." in the "input" dictionary to automatically distribute that value to all connected fields!

5. What is the difference between Single-Node (type="node") and Workflow (type="workflow") modes?

• Single-Node Mode lets you trigger any individual generator tool (e.g. "upscale" or "virtual_tryon") directly without saving a workflow layout beforehand.

• Workflow Mode executes complex, multi-stage pipelines (e.g. generating a virtual model, running virtual try-on, and upscaling the output) using a template name saved inside the visual canvas builder.

6. How are token costs validated before a workflow run starts?

Before execution begins, the backend builds the DAG and pre-calculates the token costs of all active nodes. If your user account has insufficient tokens, the API immediately returns a 402 Payment Required (InsufficientTokens) error and halts execution, ensuring you are never charged for partial, failing runs.

7. Can independent nodes in my workflow run in parallel?

Yes! The workflow engine operates fully asynchronously. By default, any independent nodes (nodes that don't depend on each other's outputs) will execute in parallel to achieve maximum speed and minimal processing latency.