VibesAI-api 1.3.2__py3-none-any.whl

vibes_api/ingredients.py

@@ -0,0 +1,206 @@
+"""
+Ingredient helpers — build the payload objects that the Vibes generation
+endpoints expect for applying (or inline-creating) characters, styles,
+and scenes.
+
+There are three ingredient types in Vibes:
+
+  - CHARACTER  (UI label: "Character")  → attaches via ``orefImageHandle``
+  - STYLE      (UI label: "Style")      → attaches via ``srefImageHandle``
+  - SETTING    (UI label: "Scene")      → attaches via ``settingImageHandles``
+
+For each, there are three ways to reference the ingredient in a generation:
+
+  1. By existing ingredient ID (use ``IngredientRef.by_id()``).
+     → goes in the ``ingredients`` array on the request body.
+
+  2. By image entity ID of an uploaded image (use ``CreateIngredient.by_image_ent_id()``).
+     → goes in the ``createIngredients`` array. The server creates a new
+       ingredient record on the fly and attaches it.
+
+  3. By name only (use ``CreateIngredient.by_name()``).
+     → also goes in ``createIngredients``. The server uses the prompt-
+       generated image as the ingredient image.
+
+These helpers build the correct dict shape so you don't have to remember
+the snake_case / camelCase quirks of the API.
+
+Example
+-------
+    from vibes_api import VibesClient, IngredientType
+    from vibes_api.ingredients import IngredientRef, CreateIngredient
+
+    client = VibesClient(meta_session="...")
+
+    # Use an existing character from your library
+    character = IngredientRef.by_id(
+        ingredient_id="800957099700717",
+        ingredient_type=IngredientType.CHARACTER,
+        name="Valdrin",
+        image_url="https://...",
+    )
+
+    # Create a new style on-the-fly from an uploaded image
+    style = CreateIngredient.by_image_ent_id(
+        image_ent_id="1177...",
+        ingredient_type=IngredientType.STYLE,
+        name="Cyberpunk neon",
+        image_url="https://...",
+    )
+
+    batch = client.generate_video(
+        project_id=project["id"],
+        prompt="...",
+        ingredients=[character],
+        create_ingredients=[style],
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+from .models import IngredientType
+
+
+def _coerce_type(t: Union[str, IngredientType]) -> str:
+    """Coerce IngredientType enum to its string value."""
+    if hasattr(t, "value"):
+        return t.value
+    return str(t)
+
+
+class IngredientRef:
+    """Builder for an EXISTING ingredient reference (by ingredientId).
+
+    Use this when you've already saved an ingredient in your library
+    (via the Vibes UI or via ``client.create_ingredient()``).
+    """
+
+    @staticmethod
+    def by_id(
+        *,
+        ingredient_id: str,
+        ingredient_type: Union[str, IngredientType],
+        name: str,
+        image_url: str,
+    ) -> dict:
+        """Reference an existing ingredient by its ID.
+
+        Parameters
+        ----------
+        ingredient_id : str
+            The ``ingredientId`` from ``client.list_ingredients()``.
+        ingredient_type : str | IngredientType
+            One of CHARACTER, STYLE, SETTING.
+        name : str
+            Display name (matches the ingredient's name in the library).
+        image_url : str
+            URL of the ingredient's image. Used as a thumbnail.
+        """
+        return {
+            "ingredientId": ingredient_id,
+            "ingredientType": _coerce_type(ingredient_type),
+            "name": name,
+            "imageUrl": image_url,
+        }
+
+
+class CreateIngredient:
+    """Builder for an INLINE ingredient creation (no pre-existing ingredient).
+
+    Use this when you want the server to create a new ingredient on-the-fly
+    during generation. There are two flavors:
+
+    - ``by_image_ent_id()`` — create from an already-uploaded image
+      (you've called ``client.upload_image()`` first).
+    - ``by_name()`` — create by name only; the server uses the prompt-
+      generated image as the ingredient image.
+    """
+
+    @staticmethod
+    def by_image_ent_id(
+        *,
+        image_ent_id: str,
+        ingredient_type: Union[str, IngredientType],
+        name: str,
+        image_url: str,
+    ) -> dict:
+        """Create a new ingredient from an uploaded image.
+
+        Parameters
+        ----------
+        image_ent_id : str
+            The ``imageEntId`` from ``client.upload_image()`` or
+            ``client.upload_image_file()``.
+        ingredient_type : str | IngredientType
+            CHARACTER, STYLE, or SETTING.
+        name : str
+            Display name for the new ingredient.
+        image_url : str
+            URL of the uploaded image (returned alongside imageEntId).
+        """
+        return {
+            "sourceImageEntId": image_ent_id,
+            "ingredientType": _coerce_type(ingredient_type),
+            "name": name,
+            "imageUrl": image_url,
+        }
+
+    @staticmethod
+    def by_name(
+        *,
+        ingredient_type: Union[str, IngredientType],
+        name: str,
+    ) -> dict:
+        """Create a new ingredient by name only.
+
+        The server will use the image generated by the prompt as the
+        ingredient image. This is the simplest form — useful for the
+        timeline chat assistant.
+        """
+        return {
+            "ingredientType": _coerce_type(ingredient_type),
+            "name": name,
+        }
+
+
+def build_ingredient_payload(
+    *,
+    ingredients: Optional[list] = None,
+    create_ingredients: Optional[list] = None,
+    character: Optional[dict] = None,
+    style: Optional[dict] = None,
+    scene: Optional[dict] = None,
+) -> dict:
+    """Convenience builder: combine character/style/scene refs into a payload.
+
+    Pass either ``ingredients=[...]`` and ``create_ingredients=[...]``
+    (already-built payload dicts), or the convenience parameters
+    ``character=...``, ``style=...``, ``scene=...`` (each can be either
+    an ``IngredientRef`` or ``CreateIngredient`` dict — this function
+    will route it to the correct array based on its keys).
+
+    Returns
+    -------
+    dict
+        ``{"ingredients": [...], "createIngredients": [...]}`` —
+        ready to spread into a generation request body.
+    """
+    final_ingredients = list(ingredients or [])
+    final_create = list(create_ingredients or [])
+
+    for ing in (character, style, scene):
+        if ing is None:
+            continue
+        if "ingredientId" in ing:
+            final_ingredients.append(ing)
+        else:
+            final_create.append(ing)
+
+    payload: dict = {}
+    if final_ingredients:
+        payload["ingredients"] = final_ingredients
+    if final_create:
+        payload["createIngredients"] = final_create
+    return payload

vibes_api/models.py

@@ -0,0 +1,165 @@
+"""
+Enums and constants for the Vibes API client.
+
+All values are taken directly from the vibes.ai Next.js bundles.
+"""
+
+from enum import Enum
+
+
+class AspectRatio(str, Enum):
+    """Supported aspect ratios for image / video generation.
+
+    Only three ratios are actually supported by the server (verified live):
+    1:1, 9:16, and 16:9. Other values will be rejected with
+    ``GENERATION_FAILED``.
+    """
+
+    SQUARE = "1:1"       # 1280x1280 for images
+    PORTRAIT = "9:16"    # 720x1280 (default in UI)
+    LANDSCAPE = "16:9"   # 1280x720
+
+
+class Resolution(str, Enum):
+    """Supported output resolutions (shown under "Advanced" in the UI)."""
+
+    P480 = "480p"
+    P720 = "720p"
+
+
+class VideoModel(str, Enum):
+    """Available video generation models.
+
+    Selecting the right model is important — different generation types
+    require different models:
+
+    - ``midjen-short``  → text-to-video (t2v) and image-to-video (i2v)
+    - ``midjen-extend`` → video extension (auto/manual extend)
+    - ``midjen-video-edit`` → video-to-video editing (v2v)
+    - ``lipsync`` family → lip-sync generation
+    """
+
+    SHORT = "midjen-short"
+    EXTEND = "midjen-extend"
+    VIDEO_EDIT = "midjen-video-edit"
+    LIPSYNC = "lipsync"
+    LIPSYNC_ASYNC = "midjen-lipsync-async"
+    LIPSYNC_EXP = "midjen-lipsync-exp"
+    LIPSYNC_DIRECT = "midjen-lipsync-direct"
+
+
+class ImageModel(str, Enum):
+    """Available image generation models."""
+
+    BASE = "midjen-base"
+
+
+class PromptModel(str, Enum):
+    """LLM used for prompt enhancement / parsing."""
+
+    GEMINI_FLASH = "gemini-2.5-flash"
+
+
+class GenerationType(str, Enum):
+    """Generation type discriminator (sent in the ``config.generationType`` field).
+
+    The server uses this to route the request to the correct pipeline:
+
+    - ``t2v``  → text-to-video
+    - ``t2i``  → text-to-image
+    - ``i2v``  → image-to-video (start frame uploaded or selected)
+    - ``extend`` → extend an existing video clip (auto or manual)
+    - ``v2v``  → video-to-video editing
+    - ``lipsync`` → lip-sync generation
+    """
+
+    TEXT_TO_VIDEO = "t2v"
+    TEXT_TO_IMAGE = "t2i"
+    IMAGE_TO_VIDEO = "i2v"
+    EXTEND = "extend"
+    VIDEO_TO_VIDEO = "v2v"
+    LIPSYNC = "lipsync"
+
+
+class IngredientType(str, Enum):
+    """Type of studio ingredient.
+
+    The three types map to UI sections in the Ingredients panel:
+    Characters, Styles, Scenes (internally "SETTING").
+    """
+
+    CHARACTER = "CHARACTER"
+    STYLE = "STYLE"
+    SETTING = "SETTING"  # "Scene" in the UI
+
+
+class OwnerFilter(str, Enum):
+    """Filter for /api/studio/ingredients."""
+
+    LIBRARY = "LIBRARY"  # User's saved ingredients
+    VIEWER = "VIEWER"    # Ingredients visible to current viewer
+
+
+class VoicePreset(str, Enum):
+    """Built-in TTS voices.
+
+    41 voices are available — these are the most common. Use
+    ``client.list_voices()`` to get the full up-to-date list.
+    """
+
+    MARISOL = "play_ai_Marisol"
+    GEORGE_WASHINGTON = "play_ai_1P_George_Washington"
+    ABRAHAM_LINCOLN = "play_ai_1P_Abraham_Lincoln"
+    JANE_AUSTEN = "play_ai_1P_Jane_Austen"
+    SERAPHINE = "play_ai_1P_Seraphine"
+    CELESTE = "play_ai_Celeste"
+    NIGEL = "play_ai_Nigel"
+    CONOR = "play_ai_Conor"
+
+
+class TextOverlayPreset(str, Enum):
+    """Effect presets for text overlays on the timeline."""
+
+    FADE = "fade"
+    SLIDE_UP = "slide-up"
+    SURROUND = "surround"
+    STRANGE = "strange"
+    FLASH = "flash"
+    SLIDE = "slide"
+    CINEFADE = "cinefade"
+    GLOW = "glow"
+    TYPEWRITER = "typewriter"
+    HIGHLIGHT = "highlight"
+    GLITCH = "glitch"
+
+
+class TextOverlayPosition(str, Enum):
+    """Position presets for text overlays on the timeline."""
+
+    CENTER = "center"
+    TOP = "top"
+    BOTTOM = "bottom"
+    LEFT = "left"
+    RIGHT = "right"
+    TOP_LEFT = "top-left"
+    TOP_RIGHT = "top-right"
+    BOTTOM_LEFT = "bottom-left"
+    BOTTOM_RIGHT = "bottom-right"
+
+
+class SyncMode(str, Enum):
+    """Modes used by the /api/sync endpoint (server-sent events).
+
+    The UI uses these to coordinate real-time collaboration. ``polling``
+    falls back to GET requests; ``sse`` opens an EventSource stream.
+    """
+
+    POLLING = "polling"
+    SSE = "sse"
+
+
+class EntityType(str, Enum):
+    """Entity types accepted by /api/share-links, /api/sync, /api/collaborators."""
+
+    PROJECT = "project"
+    CONTENT_ITEM = "content-item"