Workflow (Legacy)

Overview (Legacy)

This is the legacy Workflow API. For new integrations, use the Workflow API (JSON-based, /v2/workflow).

The legacy API enables you to create sophisticated video transformations by applying multi-step processing pipelines to your images. Workflows automate complex video production tasks through predefined templates that handle multiple processing steps automatically.

How Workflows Work

1. Upload Images - Provide one or more images as input
2. Select Template - Choose a workflow template that defines the processing steps
3. Configure Options - Customize template-specific options (backgrounds, prompts, motion types)
4. Process - The workflow automatically executes all steps in sequence
5. Get Results - Retrieve the final processed video and intermediate step results

Templates in use

Workflow Processing Steps

Each template follows a specific processing pipeline that may include:

• Content cropping and alpha channel replacement
• Image-to-image transformation
• Background replacement
• Face swapping
• Video animation creation
• Upscaling and enhancement
• Video composition

Quick Start Example

import requests
import json
import time

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"

# Step 1: Create workflow
url = f"{BASE_URL}/workflow"
headers = {"X-Api-Key": API_KEY}

# Prepare options for vim_new_year_2026
options = {
    "aspect_ratio": "16:9",
    "pipeline_mode": "video"
}

payload = {
    "title": "My Workflow Video",
    "description": "Animated overlay video",
    "template_id": "vim_new_year_2026",
    "options": json.dumps(options),
    "visibility_status": "1",
    "image_urls": ["https://example.com/image.png"]
}

try:
    response = requests.post(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    workflow_data = result["data"]
    workflow_id = workflow_data["id"]

    print(f"✓ Workflow created! ID: {workflow_id}")
    print(f"  Status: {workflow_data['processing_status']}")

except requests.exceptions.RequestException as e:
    print(f"✗ Error creating workflow: {e}")
    exit(1)

# Step 2: Poll for completion
print("\nPolling for workflow completion...")
max_attempts = 120  # Maximum 60 minutes
attempt = 0
poll_interval = 30  # Check every 30 seconds

def get_workflow_status(workflow_id):
    """Retrieve the current status of a workflow."""
    url = f"{BASE_URL}/workflow/{workflow_id}"
    headers = {"X-Api-Key": API_KEY}

    try:
        response = requests.get(url, headers=headers, timeout=30)
        response.raise_for_status()
        return response.json()["data"]
    except requests.exceptions.RequestException as e:
        print(f"  Warning: Error retrieving status: {e}")
        return None

while attempt < max_attempts:
    workflow_data = get_workflow_status(workflow_id)

    if not workflow_data:
        print(f"  Attempt {attempt + 1}/{max_attempts}: Failed to retrieve status, retrying...")
        time.sleep(poll_interval)
        attempt += 1
        continue

    status = workflow_data.get("processing_status")
    progress = workflow_data.get("progress_percentage", 0)

    print(f"  Attempt {attempt + 1}/{max_attempts}: Status={status}, Progress={progress}%")

    if status == "success":
        results = workflow_data.get("result", [])
        if results:
            print(f"\n✓ Workflow completed successfully!")
            for result_item in results:
                video_url = result_item.get("url")
                content_type = result_item.get("content_type")
                print(f"  Result: {content_type} - {video_url}")
        break
    elif status == "fail":
        print(f"\n✗ Workflow processing failed.")
        print(f"  Workflow ID: {workflow_id}")
        exit(1)

    time.sleep(poll_interval)
    attempt += 1

if attempt >= max_attempts:
    print(f"\n⚠ Timeout: Workflow processing is taking longer than expected.")
    print(f"  Workflow ID: {workflow_id}")
    print(f"  Please check the status later using: GET {BASE_URL}/workflow/{workflow_id}")

Webhook Integration

Instead of polling, you can configure a webhook URL to receive notifications when workflow processing completes.

Setting Up Webhooks

Include the webhook_url parameter when creating a workflow (if supported by the template):

payload = {
    "template_id": "vim_new_year_2026",
    "options": json.dumps(options),
    "webhook_url": "https://your-domain.com/api/webhooks/workflow-complete",
    # ... other parameters
}

Note: Webhook support varies by template. Check template-specific documentation for webhook availability.

This is the legacy Workflow API. For new integrations, use the Workflow API (JSON-based, /v2/workflow).

The legacy API enables you to create sophisticated video transformations by applying multi-step processing pipelines to your images. Workflows automate complex video production tasks through predefined templates that handle multiple processing steps automatically.

1. Upload Images - Provide one or more images as input
2. Select Template - Choose a workflow template that defines the processing steps
3. Configure Options - Customize template-specific options (backgrounds, prompts, motion types)
4. Process - The workflow automatically executes all steps in sequence
5. Get Results - Retrieve the final processed video and intermediate step results

Each template follows a specific processing pipeline that may include:

• Content cropping and alpha channel replacement
• Image-to-image transformation
• Background replacement
• Face swapping
• Video animation creation
• Upscaling and enhancement
• Video composition

import requests
import json
import time

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"

# Step 1: Create workflow
url = f"{BASE_URL}/workflow"
headers = {"X-Api-Key": API_KEY}

# Prepare options for vim_new_year_2026
options = {
    "aspect_ratio": "16:9",
    "pipeline_mode": "video"
}

payload = {
    "title": "My Workflow Video",
    "description": "Animated overlay video",
    "template_id": "vim_new_year_2026",
    "options": json.dumps(options),
    "visibility_status": "1",
    "image_urls": ["https://example.com/image.png"]
}

try:
    response = requests.post(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    workflow_data = result["data"]
    workflow_id = workflow_data["id"]

    print(f"✓ Workflow created! ID: {workflow_id}")
    print(f"  Status: {workflow_data['processing_status']}")

except requests.exceptions.RequestException as e:
    print(f"✗ Error creating workflow: {e}")
    exit(1)

# Step 2: Poll for completion
print("\nPolling for workflow completion...")
max_attempts = 120  # Maximum 60 minutes
attempt = 0
poll_interval = 30  # Check every 30 seconds

def get_workflow_status(workflow_id):
    """Retrieve the current status of a workflow."""
    url = f"{BASE_URL}/workflow/{workflow_id}"
    headers = {"X-Api-Key": API_KEY}

    try:
        response = requests.get(url, headers=headers, timeout=30)
        response.raise_for_status()
        return response.json()["data"]
    except requests.exceptions.RequestException as e:
        print(f"  Warning: Error retrieving status: {e}")
        return None

while attempt < max_attempts:
    workflow_data = get_workflow_status(workflow_id)

    if not workflow_data:
        print(f"  Attempt {attempt + 1}/{max_attempts}: Failed to retrieve status, retrying...")
        time.sleep(poll_interval)
        attempt += 1
        continue

    status = workflow_data.get("processing_status")
    progress = workflow_data.get("progress_percentage", 0)

    print(f"  Attempt {attempt + 1}/{max_attempts}: Status={status}, Progress={progress}%")

    if status == "success":
        results = workflow_data.get("result", [])
        if results:
            print(f"\n✓ Workflow completed successfully!")
            for result_item in results:
                video_url = result_item.get("url")
                content_type = result_item.get("content_type")
                print(f"  Result: {content_type} - {video_url}")
        break
    elif status == "fail":
        print(f"\n✗ Workflow processing failed.")
        print(f"  Workflow ID: {workflow_id}")
        exit(1)

    time.sleep(poll_interval)
    attempt += 1

if attempt >= max_attempts:
    print(f"\n⚠ Timeout: Workflow processing is taking longer than expected.")
    print(f"  Workflow ID: {workflow_id}")
    print(f"  Please check the status later using: GET {BASE_URL}/workflow/{workflow_id}")

Instead of polling, you can configure a webhook URL to receive notifications when workflow processing completes.

Setting Up Webhooks

Include the webhook_url parameter when creating a workflow (if supported by the template):

payload = {
    "template_id": "vim_new_year_2026",
    "options": json.dumps(options),
    "webhook_url": "https://your-domain.com/api/webhooks/workflow-complete",
    # ... other parameters
}

Note: Webhook support varies by template. Check template-specific documentation for webhook availability.