{"uid":"cap__eEKiXOC5iKXa12hIZ30H","slug":"agents-vimmerse-net-vimmerse-create-workflow-6f335f0b","name":"Vimmerse Create Workflow","description":"Creates a new workflow and starts asynchronous processing.\n\nThis endpoint accepts an `application/json` body. Template-specific configuration is passed via the `options` object.\n\n## JSON Request Example (Python)\n\n```python\nimport requests\n\nBASE_URL = \"https://api.vimmerse.net\"\nAPI_KEY = \"YOUR_API_KEY\"\n\nurl = f\"{BASE_URL}/v2/workflow\"\nheaders = {\n    \"X-Api-Key\": API_KEY,\n    \"Content-Type\": \"application/json\",\n}\n\npayload = {\n    \"title\": \"Worldcup Activation\",\n    \"description\": \"Celebrating team win of the worldcup.\",\n    \"visibility_status\": \"1\",\n    \"image_urls\": [\"https://distribution.vimmerse.net/presets/image/blonde.jpg\"],\n    \"template_id\": \"vim_wc26_team\",\n    \"options\": {\n        \"team\": \"Brazil\",\n        \"aspect_ratio\": \"3:4\",\n        \"pipeline_mode\": \"video\"\n    },\n    \"event_id\": \"campaign_2026_q3\"\n}\n\nresponse = requests.post(url, headers=headers, json=payload, timeout=60)\nresponse.raise_for_status()\nprint(response.json())\n```\n\n## Full Example: Create Workflow and Poll Until Complete\n\nCopy and run this script, then replace only `YOUR_API_KEY`.\n\n```python\nimport requests\nimport time\n\nBASE_URL = \"https://api.vimmerse.net\"\nAPI_KEY = \"YOUR_API_KEY\"\nHEADERS = {\n    \"X-Api-Key\": API_KEY,\n    \"Content-Type\": \"application/json\",\n}\n\n# 1) Create workflow\ncreate_url = f\"{BASE_URL}/v2/workflow\"\ncreate_payload = {\n    \"title\": \"Worldcup Activation\",\n    \"description\": \"Celebrating team win of the worldcup.\",\n    \"visibility_status\": \"1\",\n    \"image_urls\": [\"https://distribution.vimmerse.net/presets/image/blonde.jpg\"],\n    \"template_id\": \"vim_wc26_team\",\n    \"options\": {\n        \"team\": \"Brazil\",\n        \"aspect_ratio\": \"3:4\",\n        \"pipeline_mode\": \"video\"\n    },\n    \"event_id\": \"campaign_2026_q3\"\n}\n\ncreate_res = requests.post(create_url, headers=HEADERS, json=create_payload, timeout=60)\ncreate_res.raise_for_status()\nworkflow_data = create_res.json()\nworkflow_id = workflow_data[\"id\"]\nprint(f\"Workflow created: {workflow_id}\")\nprint(f\"Initial status: {workflow_data.get('processing_status')}\")\n\n# 2) Poll workflow status\nstatus_url = f\"{BASE_URL}/v2/workflow/{workflow_id}\"\nmax_attempts = 120\nfor attempt in range(max_attempts):\n    status_res = requests.get(status_url, headers=HEADERS, timeout=30)\n    status_res.raise_for_status()\n    data = status_res.json()\n\n    status = data.get(\"processing_status\", \"\")\n    progress = data.get(\"progress_percentage\", 0)\n    print(f\"Attempt {attempt + 1}: status={status}, progress={progress}%\")\n\n    if status == \"success\":\n        print(\"Workflow completed successfully.\")\n        break\n    if status == \"fail\":\n        raise RuntimeError(\"Workflow processing failed.\")\n\n    time.sleep(10)\nelse:\n    raise TimeoutError(\"Workflow processing is taking longer than expected.\")\n\n# 3) Print final outputs\nresult_items = data.get(\"result\", [])\ncompletion_items = data.get(\"completions\", [])\n\nprint(f\"Final results: {len(result_items)} item(s)\")\nfor item in result_items:\n    print(f\"- {item.get('content_type')}: {item.get('url')}\")\n\nprint(f\"Step completions: {len(completion_items)} step(s)\")\nfor step in completion_items:\n    step_id = step.get(\"id\") or step.get(\"flow\")\n    step_results = step.get(\"result\", [])\n    print(f\"- {step_id}: {len(step_results)} output(s)\")\n```","url":"https://agents.vimmerse.net/v2/workflow?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"CreateWorkflowRequest","properties":{"id":{"type":"string","title":"Workflow ID","default":"","description":"Optional client-provided UUID. If empty, a new id is generated."},"title":{"type":"string","title":"Title","default":""},"options":{"type":"object","title":"Options","description":"Workflow options object.","additionalProperties":true},"event_id":{"type":"string","title":"Event ID","default":"no_event","description":"Event ID of the workflow."},"image_urls":{"type":"array","items":{"type":"string"},"title":"Image URLs","description":"Input image URLs for workflow generation."},"description":{"type":"string","title":"Description","default":""},"template_id":{"type":"string","title":"Template ID","default":"vim_wc26_team","description":"Template ID of the workflow."},"visibility_status":{"type":"string","title":"Visibility Status","default":"1","description":"Workflow visibility status."},"payment_session_id":{"type":"string","title":"Payment Session ID","default":"","description":"Stripe Checkout session id when the event requires guest payment."}}},"responseSchema":{"type":"object","title":"WorkflowResponse","properties":{"id":{"type":"string","title":"ID","default":""},"model":{"type":"string","title":"Template ID","default":""},"title":{"type":"string","title":"Title","default":""},"images":{"type":"array","items":{"type":"string"},"title":"Images"},"rating":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rating"},"result":{"type":"array","items":{"type":"object","title":"WorkflowOutputItem","properties":{"url":{"type":"string","title":"URL","default":""},"content_type":{"type":"string","title":"Content Type","default":""}},"additionalProperties":true},"title":"Result"},"options":{"type":"object","title":"Options","additionalProperties":true},"event_id":{"type":"string","title":"Event ID","default":""},"media_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Media ID"},"created_at":{"type":"string","title":"Created At","default":""},"history_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"History ID"},"posted_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Posted URL"},"updated_at":{"type":"string","title":"Updated At","default":""},"completions":{"type":"array","items":{"type":"object","title":"WorkflowCompletionResponse","properties":{"id":{"type":"string","title":"Step ID","default":""},"flow":{"type":"string","title":"Flow","default":""},"result":{"type":"array","items":{"type":"object","title":"WorkflowOutputItem","properties":{"url":{"type":"string","title":"URL","default":""},"content_type":{"type":"string","title":"Content Type","default":""}},"additionalProperties":true},"title":"Result"},"outputs":{"type":"object","title":"Outputs","additionalProperties":true},"payload":{"type":"object","title":"Resolved step payload","additionalProperties":true},"duration":{"type":"integer","title":"Duration","default":0},"used_credits":{"type":"integer","title":"Used Credits","default":0}},"additionalProperties":true},"title":"Completions"},"customer_id":{"type":"string","title":"Customer ID","default":""},"description":{"type":"string","title":"Description","default":""},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"error_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Detail"},"media_result":{"type":"array","items":{"type":"object","title":"WorkflowMediaResultItem","properties":{"url":{"type":"string","title":"URL","default":""},"size":{"type":"integer","title":"Size","default":0},"updated_at":{"type":"string","title":"Updated At","default":""}},"additionalProperties":true},"title":"Media Result"},"used_credits":{"type":"integer","title":"Used Credits","default":0},"total_duration":{"type":"integer","title":"Total Duration","default":0},"primary_user_id":{"type":"string","title":"Primary User ID","default":""},"event_submission":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Event Submission"},"processing_status":{"type":"string","title":"Processing Status","default":""},"visibility_status":{"type":"string","title":"Visibility Status","default":""},"progress_percentage":{"type":"integer","title":"Progress Percentage","default":0}},"description":"Workflow API response.","additionalProperties":true},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"3","displayCostAsset":"USD","priceDynamic":true,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"dynamic","summary":"$3/call (dynamic — varies by input)","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":"3","per":"call","confidence":"exact"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":"3","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_qWrh-AC4yRFYw4g61x1KT","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"3","costPer":"request","priority":0,"asset":"usd","unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.vimmerse.net","brandSlug":"agents-vimmerse-net-x402","brandBaseUrl":"https://agents.vimmerse.net","brandDocsUrl":null,"whatItDoes":"Creates a new template-driven workflow (e.g. branded video or image generation) and starts asynchronous processing, returning a workflow ID for polling.","exampleAgentPrompt":"Use Vimmerse to create a World Cup activation workflow using template 'vim_wc26_team', with a photo of my athlete at https://distribution.vimmerse.net/presets/image/blonde.jpg, team set to Brazil, aspect ratio 3:4, pipeline mode video, titled 'Worldcup Activation', and tag it under event 'campaign_2026_q3'.","exampleUseCases":[{"title":"World Cup team activation campaign","prompt":"Kick off a Vimmerse workflow for our World Cup campaign — use template 'vim_wc26_team', the player image at https://distribution.vimmerse.net/presets/image/blonde.jpg, set team to Brazil, aspect ratio 3:4, video pipeline mode, title it 'Worldcup Activation', and attach it to event 'campaign_2026_q3'."},{"title":"Brand event personalized video generation","prompt":"Create a Vimmerse workflow for our product launch event using template 'vim_event_promo', input image at https://cdn.mybrand.com/hero.jpg, title it 'Spring Launch 2026', set visibility to public, and associate it with event 'launch_2026_spring' — I want a 9:16 video output."},{"title":"Guest-paid activation at live venue","prompt":"Start a Vimmerse workflow for a fan at our stadium booth: template is 'vim_stadium_selfie', their photo URL is https://uploads.vimmerse.net/fans/abc123.jpg, title 'Fan Moment', pipeline mode photo, and use payment session 'cs_live_abc456xyz' so the guest covers the cost."}],"resultDescription":"Returns a WorkflowResponse JSON object containing the new workflow's ID, template model used, title, input images array, array of result output items (each with URL and content_type), step-by-step completions with durations and credits used, event ID, media ID, history ID, posted URL, visibility status, customer ID, and created/updated timestamps. Processing is asynchronous — poll the workflow by ID until the result array is populated.","failureModes":["Invalid or unknown template_id returns a 400 or 422 validation error","Missing or inaccessible image_urls cause processing failure or empty results","Invalid API key returns 401 Unauthorized","Insufficient credits or unpaid event without a valid payment_session_id returns 402 Payment Required","Malformed options object for the given template may cause silent misconfiguration or processing errors","Network timeout on the POST itself (use a 60s+ timeout and rely on polling rather than waiting for completion)","Workflow stuck in processing — poll by ID and implement a max-retry backoff strategy"],"whenToPreferThis":"Choose this endpoint when you need to run a template-driven, multi-step media generation pipeline on Vimmerse — particularly for branded campaign activations, event-specific video or image generation, or any workflow that requires template configuration via an options object. Prefer this over the raw media or image endpoints when a named Vimmerse template (e.g. vim_wc26_team) encapsulates the desired pipeline logic. Use the estimate endpoint first if you want to preview credit cost before committing.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T00:42:17.744Z","isFirstParty":false,"canonicalSlug":"agents-vimmerse-net-vimmerse-create-workflow-6f335f0b"}