Skip to content

API > Core Products API > Multiswap

How to use our Multiswap endpoints

This guide explains how to use our MultiSwap image-generation endpoints, including both Realistic (v5) and Stylized (v1) modes. It covers filter-based generation, self-prompting, and status retrieval.

Access Endpoint & Documentation

1. Choosing Your Mode

Before generating an image, decide which MultiSwap engine you want to use.

Realistic Mode (v5)

Best for high-fidelity likeness and photorealistic swaps.

Purpose – Endpoint

  • Ready-to-use filters → POST /v5/run/multi_swap
  • Self-prompting → POST /v5/run/multi_swap_self_prompt
  • Status → POST /v5/status_multi_swap/{job_id}

Stylized Mode (v1)

Best for artistic, creative, exaggerated, or design-driven outputs.

Purpose – Endpoint

  • Ready-to-use filters → POST /v1/run/stylized_multi_swap
  • Self-prompting → POST /v1/run/stylized_multi_swap_self_prompt
  • Status → POST /v1/status_stylized_multi_swap/{job_id}

Tip

  • Use v5 (Realistic) when accuracy and likeness are your top priority.
  • Use v1 (Stylized) for artistic, experimental, or aesthetic-heavy results.

2. MultiSwap Workflow (All Modes)

Regardless of version or method, the process is always the same:

1. Run

  • Call the appropriate run endpoint (matching your mode + filter vs. self-prompt) with required parameters:

  • filter_id (for filters)

  • prompt (for self-prompt)
  • input images
  • API key

2. Get job_id

The run endpoint returns something like:

{ "id": "your-job-id", "status": "QUEUED" }
  • Save id → this is your job_id

3. Check Status

  • Poll the corresponding status endpoint using the job_id
  • Status values may include: QUEUED, RUNNING, COMPLETED, FAILED

4. Receive the Final Image

  • When status = COMPLETED, the response contains a base64-encoded image
  • Decode to obtain your final output

3. Receiving MultiSwap Filter IDs

Use this method if you're generating images using filter-based MultiSwap.

  • Navigate to GET /v4/multi_swap_styles/ in the API docs
  • Open endpoint details
  • Click Try it out
  • Click Execute

The response includes:

  • Example cURL request
  • The requested URL
  • A list of available filter IDs

Record the integer value of the filter ID.

Example snippet:

[
  { "id": "3", "name": "Cinematic Portrait" },
  { "id": "9", "name": "Painterly Oil Style" }
]

4. Generate an Image Using a MultiSwap Filter ID

  • Navigate to POST /v4/multi_swap_styles/
  • Expand endpoint
  • Click Try it out
  • Set payload:
{ "filter_id": 3, "input_images": [...], ... }
  • Modify optional fields as needed
  • Click Execute

Server returns:

{ "id": "job-12345", "status": "QUEUED" }

Save the id.

5. Retrieve an Image Generated via MultiSwap Filter ID

  • Open POST /v1/status_multi_swap/{job_id} (or use the matching version for v5 or stylized mode)
  • Click Try it out
  • Enter job_id
  • Click Execute

You will see something like:

{
  "id": "job-12345",
  "output": { "images": [ "some-base-64-image" ] },
  "status": "COMPLETED"
}
  • If still running → continue polling
  • Stop once COMPLETED

6. Decode Your Base64 Image

Once completed:

  • Copy output.images[0]

  • Decode using any standard base64 decoder such as:

  • Base64.guru

  • Built-in libraries (Buffer, base64.b64decode, etc.)
  • Save or display the decoded image
  • Enjoy your final MultiSwap photo!