Workflow

The Workflow 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

Overlay Templates

overlay_gray_5443 (Recommended)

• Creates overlay videos with grayscale background replacement
• Includes upscaling for higher quality output
• Best for: Professional product showcases, marketing videos

overlay_gray_5442

• Basic overlay with grayscale background
• Faster processing, lower quality than 5443
• Best for: Quick previews, simple overlays

overlay_only_1025

• Simple overlay without background processing
• Requires pre-animated video input
• Best for: Combining existing animations with backgrounds

Specialized Templates

vim_new_year_2026 - Transforms person into astronaut in microgravity scene vim_dancing_santa - Creates space jump scene with astronaut suit transformation vim_birthday - Simulates moonwalk on lunar surface with astronaut suit vim_instagramframeescape_0226 - Ceremonial flag planting on lunar surface vim_dreamcareer_0226 - Career transformation scenes vim_ces_show - Trade show presentations vim_amazonia - Nature and adventure scenes vim_arctic - Arctic exploration themes vim_sketch_me - Artistic sketch transformations vim_product_showcase - Product demonstration videos each_explodedloop_0226 - Exploded view animations each_ugcproduct_0226 - User-generated content product videos

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 overlay video template
options = {
    "background_urls": "https://example.com/background1.mp4,https://example.com/background2.mp4",
    "prompt": "Person is joyfully smiling and walking backward while still looking forward.",
    "motion_type": "Auto"
}

payload = {
    "title": "My Workflow Video",
    "description": "Animated overlay video",
    "template_id": "overlay_gray_5443",
    "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": "overlay_gray_5443",
    "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.