Agent

APIs for creating/editing media via agent orchestration and managing sessions with comprehensive control over user requests. The Agent Orchestration enables iterative creation and editing with context understanding. The agent translates plain conversational requests into actions and orchestrates calls to vimmerse tools and generate the required media accordingly.

1. Engage an agent with prompt request in new or current session - prompt the agent to perform certain action using optional media input
2. Retrieve results from the session - get a conversational response along with the generated media
3. Continue editing within the session - build up on the previous results within the context window and iterate to hit your targets

• Product Videos: Create marketing briefs and photoshot product images for marketing campaigns
• Storytelling and Shorts: Create storyboard of multiple scenes, define element images of characters objects and settings, use elements in scene images, feed all to create shorts and story videos
• Social Media Content: Perform retouches, reframing, and edits to ready content for social platforms
• Ideation: Ask agent with propose prompts and make variants of images and videos
• Tool testing: Compare generation results of different image and video models side by side
• Automation: Let agent handle the orchestration on your behalf so it picks the right tools and methods and build up on your context iterations

All requests require your API key in the X-Api-Key header:

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

Example 1: Make a product advertisement video

import requests
import json

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

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

try:
    # 1. Create first images in a new session
    payload = {
        "agent_name": "vimi",
        "title": "Product ads",
        "prompt": "Create two vertical images using GPTImage of the person in the uploaded photo drinking from the strawberry can in the other photo. Make them appear as if taken in a photoshoot session for a marketing poster.",
        "image_urls": ["https://asset.vimmerse.net/vimmerse-product/ai_images/upload_ed66297ff41e467f.jpeg","https://asset.vimmerse.net/vimmerse-product/ai_images/upload_88a364d0a8ca4d28.png"],
        "new_session": True
    }
    response = requests.post(url, headers=headers, data=payload, timeout=120)
    response.raise_for_status()
    result = response.json()
    session_id = result["session_id"]
    print(f"Session created successfully! ID: {session_id}")
    print(f"Response: {result['response']}")
    # Example Response
    # {
    #     "session_id": "b9ebe782-da5d-43ee-8297-1959965a2917",
    #     "agent_name": "vimi",
    #     "title": "Product ads",
    #     "user_id": "basel",
    #     "customer_id": "vimmerse-test-user",
    #     "response": "The two marketing poster images have been generated:

* [Image 1](https://asset.vimmerse.net/vimmerse-test-user/db8352a9-fb57-4a09-bc4c-443cf3d17cf7/create_image/3142b191-ffe6-4115-b660-9f1d52518320.png)
* [Image 2](https://asset.vimmerse.net/vimmerse-test-user/db8352a9-fb57-4a09-bc4c-443cf3d17cf7/create_image/e7445ad6-ab9c-4055-b05c-01d40e95db62.png)

**Credits Consumed:** 32",
    #     "credits_consumed_this_turn": 32,
    #     "total_session_credits_consumed": 32
    # }

    # 2. Edit one of the image generations further in same session
    payload = {
        "agent_name": "vimi",
        "session_id": "b9ebe782-da5d-43ee-8297-1959965a2917",
        "prompt": "take the second photo and add floating strawberries around the person as it was showing in the original strawberry can photo.",
        "new_session": False
    }
    response = requests.post(url, headers=headers, data=payload, timeout=120)
    response.raise_for_status()
    result = response.json()
    print(f"Response: {result['response']}")
    # Example Response
    # {
    #     "session_id": "b9ebe782-da5d-43ee-8297-1959965a2917",
    #     "agent_name": "vimi",
    #     "title": "Product ads",
    #     "user_id": "basel",
    #     "customer_id": "vimmerse-test-user",
    #     "response": "The updated marketing poster featuring floating strawberries around the person has been generated:

* [Floating Strawberries Marketing Poster](https://asset.vimmerse.net/vimmerse-test-user/25112c57-85d9-4ec8-8494-73e441257531/create_image/35bc5121-a8e8-4c36-9508-90c7d5528c67.png)

**Credits Consumed:** 16",
    #     "credits_consumed_this_turn": 16,
    #     "total_session_credits_consumed": 48
    # }

    # 3. Animate the resulted image into a video in same session
    payload = {
        "agent_name": "vimi",
        "session_id": "b9ebe782-da5d-43ee-8297-1959965a2917",
        "prompt": "animate the image into 10 sec video using Google Omni search that it appears as a professional marketing video for the product have the person feeling refreshed and energetic as she is drinking the can.",
        "new_session": False
    }
    response = requests.post(url, headers=headers, data=payload, timeout=600)
    response.raise_for_status()
    result = response.json()
    print(f"Response: {result['response']}")
    # Example Response
    # {
    #     "session_id": "b9ebe782-da5d-43ee-8297-1959965a2917",
    #     "agent_name": "vimi",
    #     "title": "Product ads",
    #     "user_id": "basel",
    #     "customer_id": "vimmerse-test-user",
    #     "response": "Your 10-second commercial marketing video has been generated:

* [Watch the Video](https://asset.vimmerse.net/vimmerse-test-user/b11a2dc6-ce1b-4bd2-9bc2-238aa1adb081/batch/1/GoogleOmni/b11a2dc6-ce1b-4bd2-9bc2-238aa1adb081.mp4)

**Credits Consumed:** 160",
    #     "credits_consumed_this_turn": 160,
    #     "total_session_credits_consumed": 208
    # }

except requests.exceptions.HTTPError as e:
    print(f"HTTP Error: {e}")
    if e.response is not None:
        print(f"Response: {e.response.text}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Example 2: Create a story video of a kid dreaming to become a professional soccer player

import requests
import json

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

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

try:
    # 1. Create storyboard, character image, and the 3 scene images in a new session
    payload = {
        "agent_name": "vimi",
        "title": "Kid Dream",
        "prompt": "create a storyboard of 3 scenes for a kid dreaming about becoming a professional soccer player in pixar style. Create the character image then use it along with the scene prompts to create the 3 scene images.",
        "new_session": True
    }
    response = requests.post(url, headers=headers, data=payload, timeout=300)
    response.raise_for_status()
    result = response.json()
    session_id = result["session_id"]
    print(f"Session created successfully! ID: {session_id}")
    print(f"Response: {result['response']}")
    # Example Response
    # {
    #     "session_id": "ac585e41-0b81-4b87-9d92-ad10392b6e7e",
    #     "agent_name": "vimi",
    #     "title": "Kid Dream",
    #     "user_id": "basel",
    #     "customer_id": "vimmerse-test-user",
    #     "response": "Here is your 3-scene Pixar-style storyboard of a young boy's dream to become a professional soccer player:

---

### 🌟 **Character Design Sheet: Leo the Dreamer**
*An enthusiastic 8-year-old boy with messy brown hair, expressive hazel eyes, and a heart full of passion for soccer.*

- **Character Image**: [View Character Concept](https://asset.vimmerse.net/vimmerse-test-user/efa45147-e27f-48a4-bb45-838d5432f57b/create_image/5f813dac-8244-4d0e-b38f-b19f88bcf711.png)

---

### 🎬 **Storyboard Scenes**

#### **Scene 1: The Bedroom Daydream**
> **Description:** In his cozy bedroom late at night, Leo hugs his favorite soccer ball tight in bed. Warm moonlight and starry ceiling decals illuminate his room, which is adorned with posters of soccer legends and trophies, sparking his imagination.
> 
> **Image**: [View Scene 1](https://asset.vimmerse.net/vimmerse-test-user/64bc269d-879c-41cc-afab-a96653a57f6c/create_image/047c6b27-5002-4680-8a74-0d3052bcd276.png)

---

#### **Scene 2: Sunset Practice & Dedication**
> **Description:** During golden hour at a local park, Leo trains relentlessly. With glowing sun flares and swirling dust, he winds up a determined, powerful kick toward a makeshift cone goal, radiating pure joy and focus.
> 
> **Image**: [View Scene 2](https://asset.vimmerse.net/vimmerse-test-user/944022dd-c979-46cc-96cd-36eb62aa5d86/create_image/058373c9-729e-4d65-ac6f-c955d9477428.png)

---

#### **Scene 3: The Grand Stadium Dream**
> **Description:** The dream comes alive—Leo steps onto the lush green pitch of a colossal, roaring international stadium under brilliant floodlights and raining confetti, ready to take the decisive championship kick.
> 
> **Image**: [View Scene 3](https://asset.vimmerse.net/vimmerse-test-user/be4ce053-95cc-42d7-8db8-3e63a9681cff/create_image/e65308d4-e8ee-4a4b-9127-b50137ac12bd.png)

---

### 💳 **Credit Usage Summary**
- **Character Design**: 8 credits
- **Scene 1**: 8 credits
- **Scene 2**: 8 credits
- **Scene 3**: 8 credits
- **Total Credits Consumed**: **32 credits**",
    #     "credits_consumed_this_turn": 32,
    #     "total_session_credits_consumed": 32
    # }

    # 2. Use all 3 scene images in reference-to-video call to make 10 sec video in the same session
    payload = {
        "agent_name": "vimi",
        "session_id": "ac585e41-0b81-4b87-9d92-ad10392b6e7e",
        "prompt": "Use these 3 scene images in reference-2-video call to make 10sec video using GoogleOmni. The video starts by the dream scene and ends with the celebration on the playground after all the hard work.",
        "new_session": False
    }
    response = requests.post(url, headers=headers, data=payload, timeout=600)
    response.raise_for_status()
    result = response.json()
    print(f"Response: {result['response']}")
    # Example Response
    # {
    #     "session_id": "ac585e41-0b81-4b87-9d92-ad10392b6e7e",
    #     "agent_name": "vimi",
    #     "title": "Kid Dream",
    #     "user_id": "basel",
    #     "customer_id": "vimmerse-test-user",
    #     "response": "Here is your 10-second Pixar-style animated video bringing Leo's soccer dream to life:

---

### ⚽ **"The Dream to Victory" Animated Short**
> **Synopsis:** Starting from the serene, moonlit bedroom where young Leo dreams with his soccer ball, the animation fluidly transitions into intense golden hour training on the pitch, and culminates in an ecstatic, heartwarming celebration as all his hard work pays off.

- 🎥 **Video Link**: [Watch Video](https://asset.vimmerse.net/vimmerse-test-user/ai_videos/9751b022-6f42-4a77-ae71-a9590a979264/k1vl4cn.mp4)
- 🖼️ **Thumbnail**: [View Thumbnail](https://asset.vimmerse.net/vimmerse-test-user/ai_videos/9751b022-6f42-4a77-ae71-a9590a979264/k1vl4cn_thumbnail.png)

---

### 💳 **Credit Usage Summary**
- **Tool**: GoogleOmni (10s Reference-to-Video)
- **Credits Consumed**: **160 credits**",
    #     "credits_consumed_this_turn": 160,
    #     "total_session_credits_consumed": 192
    # }

except requests.exceptions.HTTPError as e:
    print(f"HTTP Error: {e}")
    if e.response is not None:
        print(f"Response: {e.response.text}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Example 3: List all sessions of a particular user

import requests
import json
import time

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

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

try:
    response = requests.get(url, headers=headers, timeout=60)
    response.raise_for_status()
    result = response.json()
    sessions = result["sessions"]
    print(f" sessions: {sessions}")
    # Example Response
    # {
    #     "user_id": "basel",
    #     "sessions": [
    #         {
    #             "session_id": "b9ebe782-da5d-43ee-8297-1959965a2917",
    #             "agent_name": "vimi",
    #             "title": "Product Ads",
    #             "updated_at": "2026-08-21T22:54:43.128823+00:00",
    #             "total_credits": 208
    #         },
    #         {
    #             "session_id": "ac585e41-0b81-4b87-9d92-ad10392b6e7e",
    #             "agent_name": "vimi",
    #             "title": "Kid Dream",
    #             "updated_at": "2026-08-21T05:52:12.026459+00:00",
    #             "total_credits": 192
    #         }
    #     ]
    # }

except requests.exceptions.HTTPError as e:
    print(f"✗ HTTP Error: {e}")
    if e.response is not None:
        print(f"  Response: {e.response.text}")
    exit(1)
except requests.exceptions.RequestException as e:
    print(f"✗ Request failed: {e}")
    exit(1)