Workflow

Creates a new workflow and starts asynchronous processing.

This endpoint accepts an application/json body. Template-specific configuration is passed via the options object.

JSON Request Example (Python)

import requests

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

url = f"{BASE_URL}/v2/workflow"
headers = {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
}

payload = {
    "title": "Campaign Workflow",
    "description": "Astronaut-themed launch campaign video",
    "visibility_status": "1",
    "image_urls": ["https://example.com/input.png"],
    "template_id": "vim_new_year_2026",
    "options": {
        "aspect_ratio": "16:9",
        "pipeline_mode": "video"
    },
    "event_id": "campaign_2026_q1"
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
print(response.json())

Full Example: Create Workflow and Poll Until Complete

Copy and run this script, then replace only YOUR_API_KEY.

import requests
import time

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"
HEADERS = {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
}

# 1) Create workflow
create_url = f"{BASE_URL}/v2/workflow"
create_payload = {
    "title": "Campaign Workflow",
    "description": "Astronaut-themed launch campaign video",
    "visibility_status": "1",
    "image_urls": ["https://example.com/input.png"],
    "template_id": "vim_new_year_2026",
    "options": {
        "aspect_ratio": "16:9",
        "pipeline_mode": "video"
    },
    "event_id": "campaign_2026_q1"
}

create_res = requests.post(create_url, headers=HEADERS, json=create_payload, timeout=60)
create_res.raise_for_status()
workflow_data = create_res.json()["data"]
workflow_id = workflow_data["id"]
print(f"Workflow created: {workflow_id}")
print(f"Initial status: {workflow_data.get('processing_status')}")

# 2) Poll workflow status
status_url = f"{BASE_URL}/v2/workflow/{workflow_id}"
max_attempts = 120
for attempt in range(max_attempts):
    status_res = requests.get(status_url, headers=HEADERS, timeout=30)
    status_res.raise_for_status()
    data = status_res.json()["data"]

    status = data.get("processing_status", "")
    progress = data.get("progress_percentage", 0)
    print(f"Attempt {attempt + 1}: status={status}, progress={progress}%")

    if status == "success":
        print("Workflow completed successfully.")
        break
    if status == "fail":
        raise RuntimeError("Workflow processing failed.")

    time.sleep(10)
else:
    raise TimeoutError("Workflow processing is taking longer than expected.")

# 3) Print final outputs
result_items = data.get("result", [])
completion_items = data.get("completions", [])

print(f"Final results: {len(result_items)} item(s)")
for item in result_items:
    print(f"- {item.get('content_type')}: {item.get('url')}")

print(f"Step completions: {len(completion_items)} step(s)")
for step in completion_items:
    flow = step.get("flow")
    step_results = step.get("result", [])
    print(f"- {flow}: {len(step_results)} output(s)")

Retrieves workflow details including processing status, progress, and generated outputs.

Use this endpoint in polling loops after creation until processing_status is success or fail.