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": "Worldcup Activation",
    "description": "Celebrating team win of the worldcup.",
    "visibility_status": "1",
    "image_urls": ["https://distribution.vimmerse.net/presets/image/blonde.jpg"],
    "template_id": "vim_wc26_team",
    "options": {
        "team": "Brazil",
        "aspect_ratio": "3:4",
        "pipeline_mode": "video"
    },
    "event_id": "campaign_2026_q3"
}

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": "Worldcup Activation",
    "description": "Celebrating team win of the worldcup.",
    "visibility_status": "1",
    "image_urls": ["https://distribution.vimmerse.net/presets/image/blonde.jpg"],
    "template_id": "vim_wc26_team",
    "options": {
        "team": "Brazil",
        "aspect_ratio": "3:4",
        "pipeline_mode": "video"
    },
    "event_id": "campaign_2026_q3"
}

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:
    step_id = step.get("id") or step.get("flow")
    step_results = step.get("result", [])
    print(f"- {step_id}: {len(step_results)} output(s)")

Returns the template list-price credits for POST /v2/workflow given template_id and options. No authentication required. When a template defines both image and video list prices, options.pipeline_mode (image or video) selects which applies. Actual runtime charges may include per-step metering and cloud fees beyond this estimate.

Returns the workflow template catalog for building UIs, customer scripts, and API playgrounds.

Requires X-Api-Key. Templates are scoped to the customer tied to your API key (plus product defaults). Inactive templates are omitted.

Response shape

• detail=false (default) — summary rows: template_id, inputs, label, credits, thumbnails, description, category, etc.
• detail=true — full template definition (available_options, steps, outputs, and related metadata).

Filters

• category — optional; e.g. sport, marketing, general, utility, healthcare. Omit to return all categories you can access.
• template_ids — optional; return only specific template IDs (must be in your catalog).

Examples

GET /v2/workflow/templates
GET /v2/workflow/templates?category=sport
GET /v2/workflow/templates?detail=true
GET /v2/workflow/templates?template_ids=vim_wc26_team&detail=true

Re-fetch after deploy when templates or options change.

Create or update a custom workflow template (JSON body). Requires authentication.

Step types, option component types, and substitution rules for the template editor UI.

Validate a template definition without saving (step types, ids, dependency graph).

Dry-run a template JSON: validation, active execution layers (respecting when / preview options), skipped steps, active outputs, and per-step credit estimate.

Read a workflow template by ID (system or custom). Requires authentication.

Soft-delete a custom workflow template. Requires authentication.

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.