vrex-flow-engine 0.2.0__py3-none-any.whl

flow_engine/bridge/flow_sdk.py

@@ -0,0 +1,1743 @@
+"""Minimal Google Flow SDK wrapper.
+
+Ported from flowkit (`/tmp/flowkit-ref/agent/services/flow_client.py`).
+Trimmed to what Run 4 ships: `create_project` (TRPC) + `gen_image` (api_request
+with IMAGE_GENERATION captcha). Video / upload / upscale / check_async land in
+later runs.
+
+The wrapper intentionally preserves `raw` on every return so callers (and the
+request-worker that persists it to the DB) can inspect Flow's error payload
+when the user's paygate tier or model name drifts.
+"""
+from __future__ import annotations
+
+import logging
+import re
+import time
+import uuid
+from typing import Any, Optional
+
+from flow_engine.bridge.flow_client import FlowClient
+
+logger = logging.getLogger(__name__)
+
+# Endpoints -----------------------------------------------------------------
+
+FLOW_API_BASE = "https://aisandbox-pa.googleapis.com"
+TRPC_CREATE_PROJECT = "https://labs.google/fx/api/trpc/project.createProject"
+TRPC_SEARCH_PROJECTS = "https://labs.google/fx/api/trpc/project.searchUserProjects"
+# Returns the full modelConfig (image/video families + keys + per-tier credit
+# availability), userData (serviceTier/paygateTier/credits), and the preset
+# audio voice list — used to build the model catalog dynamically.
+TRPC_PROJECT_INITIAL_DATA = "https://labs.google/fx/api/trpc/flow.projectInitialData"
+VIDEO_I2V_URL = f"{FLOW_API_BASE}/v1/video:batchAsyncGenerateVideoStartImage"
+# Reference-to-video endpoint: takes referenceImages[] (multi-ref, asset-typed)
+# instead of a single startImage. See gen_video_r2v() for the body assembly.
+VIDEO_R2V_URL = f"{FLOW_API_BASE}/v1/video:batchAsyncGenerateVideoReferenceImages"
+# Text-to-video: same body as r2v minus referenceImages/referenceAudio.
+VIDEO_T2V_URL = f"{FLOW_API_BASE}/v1/video:batchAsyncGenerateVideoText"
+# Extend (continue a Veo clip) and edit (video-to-video) — both take a
+# `videoInput.mediaId` pointing at a source Veo video and return the workflow
+# schema (poll via the new primaryMediaId). Verified from a live labs.google
+# capture (2026-05). NOTE: only Veo-generated videos can be extended.
+VIDEO_EXTEND_URL = f"{FLOW_API_BASE}/v1/video:batchAsyncGenerateVideoExtendVideo"
+VIDEO_EDIT_URL = f"{FLOW_API_BASE}/v1/video:batchAsyncGenerateVideoEditVideo"
+VIDEO_POLL_URL = f"{FLOW_API_BASE}/v1/video:batchCheckAsyncVideoGenerationStatus"
+UPLOAD_IMAGE_URL = f"{FLOW_API_BASE}/v1/flow/uploadImage"
+# Video upload is a resumable, cookie-authed flow against labs.google (NOT
+# aisandbox-pa): a zero-body POST ?action=start returns a session URL, then a
+# binary PUT ?action=upload streams the bytes. Both run inside the extension's
+# browser session (see background.js handleUploadVideo). Afterwards we register
+# the clip's trim window via the TRPC videoFx.updateVideoOffset mutation so Flow
+# treats the upload as a usable workflow media — mirroring the web client.
+UPLOAD_VIDEO_START_URL = "https://labs.google/fx/api/upload-video?action=start"
+UPLOAD_VIDEO_UPLOAD_URL = "https://labs.google/fx/api/upload-video?action=upload"
+TRPC_UPDATE_VIDEO_OFFSET = "https://labs.google/fx/api/trpc/videoFx.updateVideoOffset"
+
+
+# Veo 3.1 reference-to-video (r2v). Verified against a live labs.google web
+# request (2026-05): Flow web dispatches `veo_3_1_r2v_lite_low_priority` to
+# `batchAsyncGenerateVideoReferenceImages` and gets a workflow-mode response
+# (poll via /v1/media/<primaryMediaId>). Duration is fixed by the model
+# (~8s); it is not a request field.
+VEO_R2V_MODEL_KEY = "veo_3_1_r2v_lite_low_priority"
+
+R2V_VALID_ASPECTS: set[str] = {
+    "VIDEO_ASPECT_RATIO_PORTRAIT",
+    "VIDEO_ASPECT_RATIO_LANDSCAPE",
+}
+
+
+def _media_get_url(media_id: str) -> str:
+    """Endpoint that returns inline encoded video bytes for a workflow's
+    primary media. Used to poll Low Priority (workflow-schema) submissions —
+    they have no operation name and don't appear in ``batchCheckAsync``."""
+    return f"{FLOW_API_BASE}/v1/media/{media_id}?clientContext.tool=PINHOLE"
+
+# Image model keys, indexed by the user-facing nickname used in
+# flowkit's models.json. Pro is Flow's premium / higher-quality image
+# model; "Banana 2" (NARWHAL) is the lighter / faster option. The
+# frontend Settings panel lets the user pick which one drives gen_image
+# + edit_image at request time. Update when Google rotates model names.
+IMAGE_MODELS: dict[str, str] = {
+    "NANO_BANANA_PRO": "GEM_PIX_2",
+    "NANO_BANANA_2": "NARWHAL",
+}
+DEFAULT_IMAGE_MODEL_KEY = "NANO_BANANA_PRO"
+
+
+def resolve_image_model(key: Optional[str]) -> str:
+    """Map a nickname (`NANO_BANANA_PRO` / `NANO_BANANA_2`) to the actual
+    Flow model identifier. Falls back to the Pro default for unknown /
+    missing keys so a stale frontend can't break dispatch."""
+    if isinstance(key, str) and key in IMAGE_MODELS:
+        return IMAGE_MODELS[key]
+    return IMAGE_MODELS[DEFAULT_IMAGE_MODEL_KEY]
+
+# Video model keys nested by [tier][quality][aspect]. All values verified
+# against real Flow web request bodies (curl exports from labs.google's
+# Network tab) — do NOT speculate suffixes here, only use observed keys.
+#
+# `quality` is "fast" (default), "lite", "quality", or — Ultra only —
+# "lite_relaxed" / "fast_relaxed" (0-credit low-priority queue).
+#   - Lite (`veo_3_1_i2v_lite`) is shared by Tier 1 and Tier 2; verified
+#     from PRO PLAN and ULTRA PLAN curls (see video_model.md and
+#     video_model_ultra.md). Multi-aspect — same key for both 16:9 and
+#     9:16; the model adapts via the aspectRatio field.
+#   - Quality (`veo_3_1_i2v_s` / `veo_3_1_i2v_s_portrait`) is also shared
+#     across both tiers; the difference is the `userPaygateTier` in
+#     clientContext (rate limits / queue priority), not the model key.
+#   - Tier 2 Fast naming pattern: Tier 1 Fast key + `_ultra` suffix
+#     (e.g. `veo_3_1_i2v_s_fast` → `veo_3_1_i2v_s_fast_ultra`,
+#     `veo_3_1_i2v_s_fast_portrait` → `veo_3_1_i2v_s_fast_portrait_ultra`).
+#   - Tier 2 "low priority" 0-credit models (Ultra-only fallback when the
+#     user wants to keep their daily credit budget): Lite uses the
+#     `_low_priority` suffix (`veo_3_1_i2v_lite_low_priority`); Fast uses
+#     the `_relaxed` suffix on the ultra family (`veo_3_1_i2v_s_fast_ultra_relaxed`).
+#     Verified from ULTRA PLAN curls. PORTRAIT keys for these are not yet
+#     observed — we reuse the LANDSCAPE key for both aspects (Lite is
+#     genuinely multi-aspect; Fast Relaxed portrait will need a real curl
+#     to confirm, but Flow's portrait variants typically follow the
+#     `_portrait` suffix convention if separate keys are required).
+VIDEO_MODEL_KEYS: dict[str, dict[str, dict[str, str]]] = {
+    # Tier 1 (Pro) — three quality levels, all verified from real PRO
+    # PLAN curls (see video_model.md). Lite shares `veo_3_1_i2v_lite`
+    # with Tier 2; Quality shares `veo_3_1_i2v_s` with Tier 2 — paygate
+    # tier in clientContext drives any per-tier difference. No 0-credit
+    # low-priority option here — that's a Tier 2 (Ultra) perk.
+    "PAYGATE_TIER_ONE": {
+        "lite": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_lite",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_lite",
+        },
+        "fast": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_s_fast",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_s_fast_portrait",
+        },
+        "quality": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_s",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_s_portrait",
+        },
+    },
+    # Tier 2 (Ultra) — five quality levels:
+    #   - lite: `veo_3_1_i2v_lite` (5 credits, multi-aspect)
+    #   - fast: `_fast_ultra` family (10 credits, default, balanced)
+    #   - quality: `veo_3_1_i2v_s*` family (highest fidelity, slowest)
+    #   - lite_relaxed: `veo_3_1_i2v_lite_low_priority` (0 credits,
+    #     low-priority queue, Ultra-only)
+    #   - fast_relaxed: `veo_3_1_i2v_s_fast_ultra_relaxed` (0 credits,
+    #     low-priority queue, Ultra-only).
+    #   PORTRAIT keys for the `_relaxed` family are not yet verified
+    #   from a real curl; we reuse the LANDSCAPE key as a best-effort
+    #   fallback. If Flow rejects portrait dispatches, capture a portrait
+    #   curl and add the proper key here.
+    "PAYGATE_TIER_TWO": {
+        "lite": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_lite",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_lite",
+        },
+        "fast": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_s_fast_ultra",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_s_fast_portrait_ultra",
+        },
+        "quality": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_s",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_s_portrait",
+        },
+        "lite_relaxed": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_lite_low_priority",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_lite_low_priority",
+        },
+        "fast_relaxed": {
+            "VIDEO_ASPECT_RATIO_LANDSCAPE": "veo_3_1_i2v_s_fast_ultra_relaxed",
+            "VIDEO_ASPECT_RATIO_PORTRAIT": "veo_3_1_i2v_s_fast_ultra_relaxed",
+        },
+    },
+}
+
+DEFAULT_VIDEO_QUALITY = "fast"
+
+
+def resolve_video_model(
+    paygate_tier: str, aspect_ratio: str, quality: Optional[str] = None
+) -> Optional[str]:
+    """Resolve a Flow video model key from tier + aspect + quality.
+
+    Falls back through (quality → fast) → (tier → TIER_ONE) → None so
+    a stale frontend or unknown tier can't break dispatch silently.
+    """
+    q = (quality or DEFAULT_VIDEO_QUALITY).lower()
+    tier_map = (
+        VIDEO_MODEL_KEYS.get(paygate_tier)
+        or VIDEO_MODEL_KEYS.get("PAYGATE_TIER_ONE")
+        or {}
+    )
+    quality_map = tier_map.get(q) or tier_map.get(DEFAULT_VIDEO_QUALITY) or {}
+    return quality_map.get(aspect_ratio)
+
+# project_id must match the shape Google Flow returns (UUID-ish). Validated at
+# handler boundaries to prevent path traversal into arbitrary API URLs.
+_PROJECT_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+# Flow CDN URLs embed the UUID media_id in the path:
+#   https://flow-content.google/video/<UUID>?Expires=...&Signature=...
+# When the polling response omits `metadata.video.mediaId` (it usually does for
+# video — only `mediaGenerationId` which is a base64 protobuf, NOT a UUID),
+# we recover the UUID from the URL exactly like flowkit does.
+_UUID_IN_URL_RE = re.compile(
+    r"/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})",
+    re.IGNORECASE,
+)
+
+
+def _media_id_from_url(url: Optional[str]) -> Optional[str]:
+    if not isinstance(url, str):
+        return None
+    m = _UUID_IN_URL_RE.search(url)
+    return m.group(1) if m else None
+
+
+def _first_media_entry(resp: Any, mid: str) -> dict[str, Any]:
+    """Pull the media object for ``mid`` from a batchCheckAsync media response.
+
+    The body is either a bare ``[{...}]`` list or ``{media:[{...}]}`` — handle
+    both. Falls back to the first entry when the name doesn't match.
+    """
+    data = resp.get("data") if isinstance(resp, dict) else None
+    media = (
+        data if isinstance(data, list)
+        else (data.get("media") if isinstance(data, dict) else None)
+    )
+    if not isinstance(media, list):
+        return {}
+    for m in media:
+        if isinstance(m, dict) and m.get("name") == mid:
+            return m
+    return media[0] if media and isinstance(media[0], dict) else {}
+
+
+def _media_url_from_entry(m: dict[str, Any]) -> Optional[str]:
+    """Best-effort playable URL from a finished media object (if Flow inlines
+    one in the status payload; otherwise the caller fetches the bytes)."""
+    video = m.get("video") if isinstance(m.get("video"), dict) else {}
+    gen = video.get("generatedVideo") if isinstance(video.get("generatedVideo"), dict) else {}
+    for cand in (
+        video.get("fifeUrl"), gen.get("fifeUrl"),
+        video.get("servingBaseUri"), gen.get("servingBaseUri"),
+        m.get("fifeUrl"),
+    ):
+        if isinstance(cand, str) and cand:
+            return cand
+    return None
+
+
+def _extract_inner_api_error(resp: Any) -> Optional[str]:
+    """Surface a Flow API error if the response envelope indicates one.
+
+    `flow_client.api_request` returns ``{"id", "status", "data"}`` on a
+    completed round-trip even when the underlying call failed — the HTTP
+    status from Google lives on ``resp["status"]`` and the structured error
+    body on ``resp["data"]["error"]``. Top-level ``resp["error"]`` is only
+    set by the client itself for transport-level failures (which we already
+    handle). When ``status >= 400`` or ``data.error.status`` is set, the
+    request must be reported as failed — silently treating an empty
+    ``media_ids`` list as success masked Flow's content-filter rejections
+    (e.g. ``PUBLIC_ERROR_PROMINENT_PEOPLE_FILTER_FAILED``).
+    """
+    if not isinstance(resp, dict):
+        return None
+    status = resp.get("status")
+    data = resp.get("data") if isinstance(resp.get("data"), dict) else None
+    err = data.get("error") if isinstance(data, dict) else None
+    has_status_err = isinstance(status, int) and status >= 400
+    has_data_err = isinstance(err, dict)
+    if not (has_status_err or has_data_err):
+        return None
+    if has_data_err:
+        reasons: list[str] = []
+        for detail in err.get("details") or []:
+            if isinstance(detail, dict):
+                r = detail.get("reason")
+                if isinstance(r, str) and r:
+                    reasons.append(r)
+        msg = err.get("message") or err.get("status") or "API error"
+        return f"{reasons[0]}: {msg}" if reasons else str(msg)
+    return f"API_{status}"
+
+
+def is_valid_project_id(project_id: str) -> bool:
+    return bool(_PROJECT_ID_RE.fullmatch(project_id))
+
+# Captcha action strings recognised by Google Flow.
+CAPTCHA_IMAGE = "IMAGE_GENERATION"
+CAPTCHA_VIDEO = "VIDEO_GENERATION"
+
+# Default max operations to poll in parallel. Conservative; flowkit passes
+# the full list at once.
+_MAX_VIDEO_OPS = 4
+
+# Image variants per dispatch are capped server-side as defence-in-depth — the
+# UI clamps to 4 too. Any value above this is silently coerced down.
+MAX_VARIANT_COUNT = 4
+
+# Minimal static headers that have worked against labs.google in flowkit.
+_TRPC_HEADERS = {
+    "content-type": "application/json",
+    "accept": "*/*",
+}
+_API_HEADERS = {
+    "content-type": "text/plain;charset=UTF-8",
+    "accept": "*/*",
+    "origin": "https://labs.google",
+    "referer": "https://labs.google/",
+}
+
+
+def _client_context(project_id: str, paygate_tier: str) -> dict:
+    """Skeleton clientContext — extension fills in recaptchaContext.token.
+
+    `paygate_tier` is REQUIRED (no default). Pre-v1.1.5 the default was
+    `"PAYGATE_TIER_ONE"` which silently downgraded Ultra users when any
+    upstream code path forgot to pass tier. Now we raise loudly on
+    invalid / unknown values so a code regression can't quietly serve
+    Pro to an Ultra account.
+    """
+    if paygate_tier not in _VALID_TIERS:
+        raise ValueError(
+            f"invalid paygate_tier {paygate_tier!r} — must be one of {sorted(_VALID_TIERS)}"
+        )
+    return {
+        "projectId": str(project_id),
+        "recaptchaContext": {
+            "applicationType": "RECAPTCHA_APPLICATION_TYPE_WEB",
+            "token": "",
+        },
+        "sessionId": f";{int(time.time() * 1000)}",
+        "tool": "PINHOLE",
+        "userPaygateTier": paygate_tier,
+    }
+
+
+def _generate_images_url(project_id: str) -> str:
+    return f"{FLOW_API_BASE}/v1/projects/{project_id}/flowMedia:batchGenerateImages"
+
+
+class FlowSDK:
+    """High-level helpers on top of a FlowClient. Stateless; one per request."""
+
+    def __init__(self, client: Optional[FlowClient] = None) -> None:
+        if client is None:
+            raise ValueError(
+                "FlowSDK requires an explicit FlowClient — the module-level "
+                "singleton has been removed; obtain a client via pool.get_by_api_key()."
+            )
+        self._client = client
+
+    # ── project listing (TRPC search) ──────────────────────────────────────
+    async def search_user_projects(
+        self,
+        cursor: Optional[str] = None,
+        page_size: int = 20,
+        tool: str = "PINHOLE",
+    ) -> dict[str, Any]:
+        """Fetch one page of the user's Flow project list.
+
+        Returns ``{raw, projects, next_page_token}`` on success or
+        ``{raw, error}`` on failure. Each project is a dict with
+        ``project_id`` and ``project_title`` plus optional
+        ``thumbnail_media_key`` and ``creation_time``.
+        """
+        import json as _json
+        from urllib.parse import quote
+
+        input_json: dict[str, Any] = {
+            "json": {
+                "pageSize": page_size,
+                "toolName": tool,
+                "cursor": cursor,
+            },
+        }
+        # TRPC encodes the literal `undefined` cursor via meta on the
+        # first call. Subsequent calls pass a string cursor directly.
+        if cursor is None:
+            input_json["meta"] = {"values": {"cursor": ["undefined"]}}
+
+        url = (
+            f"{TRPC_SEARCH_PROJECTS}?input="
+            + quote(_json.dumps(input_json, separators=(",", ":")))
+        )
+        resp = await self._client.trpc_request(
+            url=url,
+            method="GET",
+            headers=_TRPC_HEADERS,
+            body=None,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+
+        # Response shape (per the canonical TRPC envelope):
+        #   data.result.data.json.result.{projects, nextPageToken}
+        try:
+            inner = resp["data"]["result"]["data"]["json"]["result"]
+        except (KeyError, TypeError):
+            return {"raw": resp, "error": "unexpected_search_response_shape"}
+
+        raw_projects = inner.get("projects") or []
+        projects: list[dict[str, Any]] = []
+        for p in raw_projects:
+            if not isinstance(p, dict):
+                continue
+            pid = p.get("projectId")
+            if not isinstance(pid, str) or not pid:
+                continue
+            info = p.get("projectInfo") if isinstance(p.get("projectInfo"), dict) else {}
+            projects.append({
+                "project_id": pid,
+                "project_title": info.get("projectTitle") or "Untitled",
+                "thumbnail_media_key": info.get("thumbnailMediaKey"),
+                "creation_time": p.get("creationTime"),
+            })
+        return {
+            "raw": resp,
+            "projects": projects,
+            "next_page_token": inner.get("nextPageToken"),
+        }
+
+    async def list_user_projects_all(
+        self, tool: str = "PINHOLE", max_pages: int = 10
+    ) -> dict[str, Any]:
+        """Paginate `search_user_projects` until exhausted (or max_pages).
+
+        Returns ``{projects, truncated}`` — truncated is True when we hit
+        the page cap with a non-null next_page_token still present.
+        """
+        all_projects: list[dict[str, Any]] = []
+        cursor: Optional[str] = None
+        for _ in range(max_pages):
+            page = await self.search_user_projects(cursor=cursor, tool=tool)
+            if page.get("error"):
+                return {
+                    "projects": all_projects,
+                    "truncated": True,
+                    "error": page["error"],
+                }
+            all_projects.extend(page.get("projects") or [])
+            cursor = page.get("next_page_token")
+            if not cursor:
+                return {"projects": all_projects, "truncated": False}
+        return {"projects": all_projects, "truncated": True}
+
+    # ── project creation (TRPC) ────────────────────────────────────────────
+    async def create_project(
+        self, title: str, tool: str = "PINHOLE"
+    ) -> dict[str, Any]:
+        body = {"json": {"projectTitle": title, "toolName": tool}}
+        resp = await self._client.trpc_request(
+            url=TRPC_CREATE_PROJECT,
+            method="POST",
+            headers=_TRPC_HEADERS,
+            body=body,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+
+        project_id = _extract_project_id(resp)
+        out: dict[str, Any] = {"raw": resp}
+        if project_id is None:
+            out["error"] = "no_project_id_in_response"
+        else:
+            out["project_id"] = project_id
+        return out
+
+    # ── model catalog (TRPC) ───────────────────────────────────────────────
+    async def get_project_initial_data(self, project_id: str) -> dict[str, Any]:
+        """Fetch the project's initial data, which carries the full model
+        catalog. Returns ``{raw, data}`` on success (``data`` is the inner
+        ``json`` block with ``modelConfig`` / ``userData`` /
+        ``projectContents.externalReferenceMedia``) or ``{raw, error}``.
+        """
+        import json as _json
+        from urllib.parse import quote
+
+        input_json = {"json": {"projectId": str(project_id)}}
+        url = (
+            f"{TRPC_PROJECT_INITIAL_DATA}?input="
+            + quote(_json.dumps(input_json, separators=(",", ":")))
+        )
+        resp = await self._client.trpc_request(
+            url=url, method="GET", headers=_TRPC_HEADERS, body=None
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        try:
+            data = resp["data"]["result"]["data"]["json"]
+        except (KeyError, TypeError):
+            return {"raw": resp, "error": "unexpected_initial_data_shape"}
+        return {"raw": resp, "data": data}
+
+    # ── video generation (async via operations) ────────────────────────────
+    async def gen_video(
+        self,
+        prompt: str,
+        project_id: str,
+        start_media_id: Optional[str] = None,
+        aspect_ratio: str = "VIDEO_ASPECT_RATIO_LANDSCAPE",
+        paygate_tier: Optional[str] = None,
+        scene_id: Optional[str] = None,
+        start_media_ids: Optional[list[str]] = None,
+        video_quality: Optional[str] = None,
+        model_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Kick off i2v operation(s). Returns ``{raw, operation_names}`` on
+        success or ``{raw, error}`` on failure. Operations are async — the
+        caller polls ``check_async`` until they complete.
+
+        ``start_media_ids`` (optional list) — when provided, dispatch ONE
+        item per source image so a 4-variant upstream image produces 4
+        videos in a single batch (one operation per source). Falls back to
+        ``start_media_id`` (single) if the list is missing/empty.
+
+        ``video_quality`` ("fast" / "lite" / "quality" / "lite_relaxed"
+        / "fast_relaxed") routes to a different Veo checkpoint. Defaults
+        to "fast" — the `_s_fast` family. The first three are available
+        on both Tier 1 (Pro) and Tier 2 (Ultra); the `_relaxed` variants
+        are 0-credit low-priority queues and are Ultra-only. See
+        ``VIDEO_MODEL_KEYS`` for the per-tier mapping.
+
+        ``paygate_tier`` is required. Pre-v1.1.5 it defaulted to
+        ``"PAYGATE_TIER_ONE"`` which silently downgraded Ultra users.
+        Raise loudly instead — the worker should always have a tier
+        from the live extension signal before reaching here.
+        """
+        if paygate_tier is None:
+            raise ValueError("paygate_tier is required — see docs/migrations/clear-polluted-paygate-tier.sql")
+        # Prefer a catalog-resolved key (dynamic, tier-correct); fall back to
+        # the static tier/quality/aspect map only when none was supplied.
+        if not model_key:
+            model_key = resolve_video_model(paygate_tier, aspect_ratio, video_quality)
+        if not model_key:
+            return {
+                "raw": None,
+                "error": (
+                    f"no_video_model_for_tier_{paygate_tier}"
+                    f"_quality_{video_quality or DEFAULT_VIDEO_QUALITY}"
+                    f"_aspect_{aspect_ratio}"
+                ),
+            }
+
+        # Normalise into a non-empty list of source media ids. Single
+        # `start_media_id` is the common case; `start_media_ids` is for
+        # batch-i2v from a multi-variant upstream image.
+        sources: list[str] = []
+        if start_media_ids:
+            sources = [m for m in start_media_ids if isinstance(m, str) and m]
+        if not sources and isinstance(start_media_id, str) and start_media_id:
+            sources = [start_media_id]
+        if not sources:
+            return {"raw": None, "error": "missing_start_media_id"}
+
+        ts = int(time.time() * 1000)
+        ctx = _client_context(project_id, paygate_tier)
+        items: list[dict[str, Any]] = []
+        for i, mid in enumerate(sources):
+            items.append({
+                "aspectRatio": aspect_ratio,
+                # Distinct seed per item so Flow doesn't dedupe.
+                "seed": (ts + i * 9973) % 1_000_000,
+                "textInput": {"structuredPrompt": {"parts": [{"text": prompt}]}},
+                "videoModelKey": model_key,
+                "startImage": {"mediaId": mid},
+                "metadata": {"sceneId": scene_id or str(uuid.uuid4())},
+            })
+        body = {
+            "clientContext": ctx,
+            "mediaGenerationContext": {"batchId": str(uuid.uuid4())},
+            "requests": items,
+            "useV2ModelConfig": True,
+        }
+
+        resp = await self._client.api_request(
+            url=VIDEO_I2V_URL,
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+            captcha_action=CAPTCHA_VIDEO,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        inner_err = _extract_inner_api_error(resp)
+        if inner_err:
+            return {"raw": resp, "error": inner_err}
+
+        op_names = extract_operation_names(resp)
+        if not op_names:
+            return {"raw": resp, "error": "no_operations_in_response"}
+        out: dict[str, Any] = {"raw": resp, "operation_names": op_names}
+        # NEW low-priority workflow models return `data.workflows[]` with a
+        # `primaryMediaId` per workflow instead of operations. Surface the
+        # pairing so the poller can hit `/v1/media/<id>` directly.
+        workflows = extract_video_workflows(resp)
+        if workflows:
+            out["workflows"] = workflows
+        return out
+
+    # ── Veo 3.1 reference-to-video (r2v) ───────────────────────────────────
+    async def gen_video_r2v(
+        self,
+        prompt: str,
+        project_id: str,
+        ref_media_ids: list[str],
+        aspect_ratio: str = "VIDEO_ASPECT_RATIO_PORTRAIT",
+        paygate_tier: Optional[str] = None,
+        seed: Optional[int] = None,
+        reference_audio_ids: Optional[list[str]] = None,
+        model_key: Optional[str] = None,
+        scene_id: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Kick off Veo 3.1 reference-to-video generation. Uses
+        /video:batchAsyncGenerateVideoReferenceImages with a referenceImages[]
+        payload — distinct from the (now-stale) i2v startImage path.
+
+        Returns ``{raw, operation_names}`` (+ ``workflows`` for the
+        low-priority workflow schema) on success or ``{raw, error}`` on
+        failure. Polls via the shared ``check_async`` path.
+
+        ``ref_media_ids`` MUST be non-empty (the model is
+        reference-conditioned, not text-only).
+        ``aspect_ratio`` ∈ {PORTRAIT, LANDSCAPE}.
+        ``reference_audio_ids`` — optional audio reference media ids (e.g.
+        ``"algenib"``). When provided, attached as ``referenceAudio``; omitted
+        entirely otherwise.
+        ``paygate_tier`` required — same as gen_video.
+        """
+        if paygate_tier is None:
+            raise ValueError("paygate_tier is required")
+        if aspect_ratio not in R2V_VALID_ASPECTS:
+            return {
+                "raw": None,
+                "error": f"r2v_aspect_unsupported_{aspect_ratio}",
+            }
+        cleaned_refs = [m for m in (ref_media_ids or []) if isinstance(m, str) and m]
+        if not cleaned_refs:
+            return {"raw": None, "error": "missing_ref_media_ids"}
+
+        ts = int(time.time() * 1000)
+        used_seed = seed if seed is not None else ts % 1_000_000
+        ctx = _client_context(project_id, paygate_tier)
+        request_item: dict[str, Any] = {
+            "aspectRatio": aspect_ratio,
+            "textInput": {"structuredPrompt": {"parts": [{"text": prompt}]}},
+            "videoModelKey": model_key or VEO_R2V_MODEL_KEY,
+            "seed": used_seed,
+            "metadata": {"sceneId": scene_id} if scene_id else {},
+            "referenceImages": [
+                {"mediaId": mid, "imageUsageType": "IMAGE_USAGE_TYPE_ASSET"}
+                for mid in cleaned_refs
+            ],
+        }
+        cleaned_audio = [a for a in (reference_audio_ids or []) if isinstance(a, str) and a]
+        if cleaned_audio:
+            request_item["referenceAudio"] = [{"mediaId": a} for a in cleaned_audio]
+        body = {
+            "mediaGenerationContext": {
+                "batchId": str(uuid.uuid4()),
+                # V2 config flags silent-audio outputs as failures so the
+                # caller can retry instead of getting a degraded video.
+                "audioFailurePreference": "BLOCK_SILENCED_VIDEOS",
+            },
+            "clientContext": {**ctx, "sessionId": f";{ts}"},
+            "requests": [request_item],
+            "useV2ModelConfig": True,
+        }
+
+        resp = await self._client.api_request(
+            url=VIDEO_R2V_URL,
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+            captcha_action=CAPTCHA_VIDEO,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        inner_err = _extract_inner_api_error(resp)
+        if inner_err:
+            return {"raw": resp, "error": inner_err}
+
+        op_names = extract_operation_names(resp)
+        if not op_names:
+            return {"raw": resp, "error": "no_operations_in_response"}
+        out: dict[str, Any] = {"raw": resp, "operation_names": op_names}
+        workflows = extract_video_workflows(resp)
+        if workflows:
+            out["workflows"] = workflows
+        if scene_id:
+            out["scene_id"] = scene_id
+        return out
+
+    # ── Veo 3.1 text-to-video (t2v) ────────────────────────────────────────
+    async def gen_video_t2v(
+        self,
+        prompt: str,
+        project_id: str,
+        aspect_ratio: str = "VIDEO_ASPECT_RATIO_LANDSCAPE",
+        paygate_tier: Optional[str] = None,
+        seed: Optional[int] = None,
+        model_key: Optional[str] = None,
+        scene_id: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Kick off text-to-video. Same workflow path as r2v but with no image
+        or audio inputs — hits /video:batchAsyncGenerateVideoText.
+
+        ``model_key`` is required (resolved from the catalog) — there is no
+        static fallback for t2v.
+
+        ``scene_id`` (optional) pins the output into a client-chosen scene via
+        ``metadata.sceneId`` — Flow otherwise auto-creates a scene and never
+        tells us its id, which would leave the clip un-extendable. When set, the
+        scene id is echoed back in the result so the caller can remember it.
+        """
+        if paygate_tier is None:
+            raise ValueError("paygate_tier is required")
+        if aspect_ratio not in R2V_VALID_ASPECTS:
+            return {"raw": None, "error": f"t2v_aspect_unsupported_{aspect_ratio}"}
+        if not model_key:
+            return {"raw": None, "error": "t2v_model_key_required"}
+
+        ts = int(time.time() * 1000)
+        used_seed = seed if seed is not None else ts % 1_000_000
+        ctx = _client_context(project_id, paygate_tier)
+        request_item = {
+            "aspectRatio": aspect_ratio,
+            "textInput": {"structuredPrompt": {"parts": [{"text": prompt}]}},
+            "videoModelKey": model_key,
+            "seed": used_seed,
+            "metadata": {"sceneId": scene_id} if scene_id else {},
+        }
+        body = {
+            "mediaGenerationContext": {
+                "batchId": str(uuid.uuid4()),
+                "audioFailurePreference": "BLOCK_SILENCED_VIDEOS",
+            },
+            "clientContext": {**ctx, "sessionId": f";{ts}"},
+            "requests": [request_item],
+            "useV2ModelConfig": True,
+        }
+
+        resp = await self._client.api_request(
+            url=VIDEO_T2V_URL,
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+            captcha_action=CAPTCHA_VIDEO,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        inner_err = _extract_inner_api_error(resp)
+        if inner_err:
+            return {"raw": resp, "error": inner_err}
+
+        op_names = extract_operation_names(resp)
+        if not op_names:
+            return {"raw": resp, "error": "no_operations_in_response"}
+        out: dict[str, Any] = {"raw": resp, "operation_names": op_names}
+        workflows = extract_video_workflows(resp)
+        if workflows:
+            out["workflows"] = workflows
+        if scene_id:
+            out["scene_id"] = scene_id
+        return out
+
+    # ── Veo 3.1 extend (continue a clip) ───────────────────────────────────
+    async def gen_video_extend(
+        self,
+        prompt: str,
+        project_id: str,
+        source_media_id: str,
+        scene_id: str,
+        position: int = 1,
+        aspect_ratio: str = "VIDEO_ASPECT_RATIO_LANDSCAPE",
+        paygate_tier: Optional[str] = None,
+        seed: Optional[int] = None,
+        model_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Extend an existing Veo clip (``batchAsyncGenerateVideoExtendVideo``).
+
+        ``source_media_id`` is the clip to continue — for extend this is the
+        source video's *operation/generation id* (``video.operation.name``),
+        NOT its workflow primaryMediaId. ``scene_id`` is the scene the source
+        belongs to and ``position`` is the slot the extension occupies in that
+        scene's timeline (1 for the first extension). Only Veo-generated videos
+        can be extended.
+
+        Returns the workflow-schema shape (``{raw, operation_names, workflows}``)
+        like the other video dispatchers; poll via the shared ``check_async``.
+        """
+        if paygate_tier is None:
+            raise ValueError("paygate_tier is required")
+        if not model_key:
+            return {"raw": None, "error": "extend_model_key_required"}
+        if not isinstance(source_media_id, str) or not source_media_id:
+            return {"raw": None, "error": "missing_source_media_id"}
+        if not isinstance(scene_id, str) or not scene_id:
+            return {"raw": None, "error": "missing_scene_id"}
+
+        ts = int(time.time() * 1000)
+        used_seed = seed if seed is not None else ts % 1_000_000
+        ctx = _client_context(project_id, paygate_tier)
+        body = {
+            "mediaGenerationContext": {
+                "batchId": str(uuid.uuid4()),
+                "audioFailurePreference": "BLOCK_SILENCED_VIDEOS",
+                "sceneContext": {"sceneId": scene_id, "position": position},
+            },
+            "clientContext": {**ctx, "sessionId": f";{ts}"},
+            "requests": [
+                {
+                    "aspectRatio": aspect_ratio,
+                    "textInput": {"structuredPrompt": {"parts": [{"text": prompt}]}},
+                    "videoModelKey": model_key,
+                    "seed": used_seed,
+                    "metadata": {"sceneId": scene_id},
+                    "videoInput": {"mediaId": source_media_id},
+                }
+            ],
+            "useV2ModelConfig": True,
+        }
+        return await self._dispatch_video(VIDEO_EXTEND_URL, body)
+
+    # ── Veo 3.1 edit (video-to-video) ──────────────────────────────────────
+    async def gen_video_edit(
+        self,
+        prompt: str,
+        project_id: str,
+        source_media_id: str,
+        workflow_id: str,
+        end_frame_index: int,
+        start_frame_index: int = 0,
+        aspect_ratio: str = "VIDEO_ASPECT_RATIO_LANDSCAPE",
+        paygate_tier: Optional[str] = None,
+        seed: Optional[int] = None,
+        model_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Edit an existing video (``batchAsyncGenerateVideoEditVideo``, v2v).
+
+        ``source_media_id`` is the source video's workflow primaryMediaId (its
+        media ``name``). ``workflow_id`` is the source's workflow; the edit
+        produces a new media version under it. ``start_frame_index`` /
+        ``end_frame_index`` select the slice to edit — frames are 30fps, so a
+        full 8s clip is 0..240. Verified key: ``abra_edit``.
+
+        Returns the workflow-schema shape; poll via the shared ``check_async``.
+        """
+        if paygate_tier is None:
+            raise ValueError("paygate_tier is required")
+        if not model_key:
+            return {"raw": None, "error": "edit_model_key_required"}
+        if not isinstance(source_media_id, str) or not source_media_id:
+            return {"raw": None, "error": "missing_source_media_id"}
+        if not isinstance(workflow_id, str) or not workflow_id:
+            return {"raw": None, "error": "missing_workflow_id"}
+
+        ts = int(time.time() * 1000)
+        used_seed = seed if seed is not None else ts % 1_000_000
+        ctx = _client_context(project_id, paygate_tier)
+        body = {
+            "mediaGenerationContext": {
+                "batchId": str(uuid.uuid4()),
+                "audioFailurePreference": "BLOCK_SILENCED_VIDEOS",
+            },
+            "clientContext": {**ctx, "sessionId": f";{ts}"},
+            "requests": [
+                {
+                    "aspectRatio": aspect_ratio,
+                    "textInput": {"structuredPrompt": {"parts": [{"text": prompt}]}},
+                    "videoModelKey": model_key,
+                    "seed": used_seed,
+                    "metadata": {"workflowId": workflow_id},
+                    "videoInput": {
+                        "mediaId": source_media_id,
+                        "startFrameIndex": start_frame_index,
+                        "endFrameIndex": end_frame_index,
+                    },
+                }
+            ],
+        }
+        return await self._dispatch_video(VIDEO_EDIT_URL, body)
+
+    async def resolve_scene(
+        self, project_id: str, workflow_ids: list[str]
+    ) -> dict[str, Any]:
+        """Resolve the scene that holds a set of workflows, via
+        ``POST /v1/flow/projects/{id}/scenes`` with ``{workflowIds:[...]}``.
+
+        This is how the web client learns a clip's scene id before extending it
+        — Flow places every generated video in an auto-created scene but never
+        echoes the id anywhere else. Returns ``{raw, scene_id, position}`` where
+        ``position`` is the next free slot in the scene's timeline (the count of
+        workflows already in it), or ``{raw, error}``.
+        """
+        cleaned = [w for w in workflow_ids if isinstance(w, str) and w]
+        if not cleaned:
+            return {"raw": None, "error": "missing_workflow_ids"}
+        url = f"{FLOW_API_BASE}/v1/flow/projects/{project_id}/scenes"
+        resp = await self._client.api_request(
+            url=url,
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body={"workflowIds": cleaned},
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        inner_err = _extract_inner_api_error(resp)
+        if inner_err:
+            return {"raw": resp, "error": inner_err}
+        data = resp.get("data") if isinstance(resp, dict) else None
+        scene = data.get("scene") if isinstance(data, dict) else None
+        scene_id = scene.get("sceneId") if isinstance(scene, dict) else None
+        if not isinstance(scene_id, str) or not scene_id:
+            return {"raw": resp, "error": "no_scene_id_in_response"}
+        sws = data.get("sceneWorkflows") if isinstance(data, dict) else None
+        position = len(sws) if isinstance(sws, list) else 1
+        return {"raw": resp, "scene_id": scene_id, "position": position}
+
+    async def fetch_video_meta(
+        self, media_ids: list[str], project_id: str
+    ) -> dict[str, Any]:
+        """Fetch rich metadata for finished video media via the media-based
+        ``batchCheckAsync`` (``{media:[{name,projectId}]}``) — distinct from the
+        operation-based poll. This is the only call that returns the workflow id,
+        operation/generation id, scene id, and dimensions needed to drive
+        extend/edit. Returns ``{raw, meta: {media_id: {...}}}``.
+        """
+        cleaned = [m for m in media_ids if isinstance(m, str) and m]
+        if not cleaned:
+            return {"raw": None, "meta": {}}
+        body = {"media": [{"name": m, "projectId": project_id} for m in cleaned]}
+        resp = await self._client.api_request(
+            url=VIDEO_POLL_URL,
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+        )
+        meta: dict[str, dict[str, Any]] = {}
+        data = resp.get("data") if isinstance(resp, dict) else None
+        media = data.get("media") if isinstance(data, dict) else None
+        for m in media or []:
+            if not isinstance(m, dict):
+                continue
+            name = m.get("name")
+            if not isinstance(name, str):
+                continue
+            video = m.get("video") if isinstance(m.get("video"), dict) else {}
+            op = video.get("operation") if isinstance(video.get("operation"), dict) else {}
+            dims = video.get("dimensions") if isinstance(video.get("dimensions"), dict) else {}
+            meta[name] = {
+                "workflow_id": m.get("workflowId"),
+                "operation_id": op.get("name"),
+                "scene_id": m.get("sceneId") or m.get("sceneIdContext"),
+                "length": dims.get("length"),
+            }
+        return {"raw": resp, "meta": meta}
+
+    async def _dispatch_video(self, url: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Shared submit + response-shaping for the workflow-schema video
+        dispatchers (extend / edit). Sends the captcha-gated request and
+        returns ``{raw, operation_names, workflows}`` or ``{raw, error}``."""
+        resp = await self._client.api_request(
+            url=url,
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+            captcha_action=CAPTCHA_VIDEO,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        inner_err = _extract_inner_api_error(resp)
+        if inner_err:
+            return {"raw": resp, "error": inner_err}
+        op_names = extract_operation_names(resp)
+        if not op_names:
+            return {"raw": resp, "error": "no_operations_in_response"}
+        out: dict[str, Any] = {"raw": resp, "operation_names": op_names}
+        workflows = extract_video_workflows(resp)
+        if workflows:
+            out["workflows"] = workflows
+        return out
+
+    async def check_async(
+        self,
+        operation_names: list[str],
+        workflows: Optional[list[dict[str, Any]]] = None,
+        project_id: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Poll one or more video operations. No captcha.
+
+        Returns ``{raw, operations: [{name, done, media_entries}]}`` — one
+        entry per input operation. ``media_entries`` is a list of
+        ``{media_id, url, mediaType}`` ready for ``media.ingest_urls``.
+
+        ``workflows`` (optional) carries ``{name, primary_media_id}`` pairs
+        from the NEW low-priority response. When provided, every workflow
+        entry is polled against ``/v1/media/<primary_media_id>`` and the
+        result is merged into the same ``operations`` shape so the caller
+        is schema-agnostic.
+        """
+        ops_summary: list[dict[str, Any]] = []
+        raw_old: Any = None
+        # Names that came from workflows are NOT valid operation handles —
+        # don't dispatch them to batchCheckAsync (Flow would 400).
+        workflow_names = {w["name"] for w in (workflows or []) if isinstance(w, dict) and w.get("name")}
+        old_names = [n for n in operation_names if n not in workflow_names]
+        if old_names:
+            body = {
+                "operations": [
+                    {"operation": {"name": name}} for name in old_names
+                ]
+            }
+            raw_old = await self._client.api_request(
+                url=VIDEO_POLL_URL,
+                method="POST",
+                headers=dict(_API_HEADERS),
+                body=body,
+            )
+            if isinstance(raw_old, dict) and raw_old.get("error"):
+                return {"raw": raw_old, "error": raw_old["error"]}
+            ops_summary.extend(
+                extract_video_operations(raw_old, requested=old_names)
+            )
+
+        raw_workflows: list[dict[str, Any]] = []
+        if workflows:
+            wf_summary, raw_workflows = await self._poll_workflows(
+                workflows, project_id
+            )
+            ops_summary.extend(wf_summary)
+
+        # Preserve the original input order so callers (worker) can keep
+        # positional alignment with their per-op state.
+        order = {name: i for i, name in enumerate(operation_names)}
+        ops_summary.sort(key=lambda op: order.get(op.get("name"), 1 << 30))
+
+        raw_out: dict[str, Any] = {}
+        if raw_old is not None:
+            raw_out["operations_poll"] = raw_old
+        if raw_workflows:
+            raw_out["workflow_polls"] = raw_workflows
+        return {"raw": raw_out or raw_old, "operations": ops_summary}
+
+    async def _poll_workflows(
+        self,
+        workflows: list[dict[str, Any]],
+        project_id: Optional[str] = None,
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        """Single poll pass for workflow-mode (Low Priority) submissions.
+
+        Flow's web client checks these via
+        ``POST /v1/video:batchCheckAsyncVideoGenerationStatus`` with a
+        ``{media:[{name, projectId}]}`` body and reads
+        ``mediaMetadata.mediaStatus.mediaGenerationStatus``
+        (SCHEDULED → ACTIVE → SUCCESSFUL). The older ``GET /v1/media/<id>``
+        status probe now returns ``400 INVALID_ARGUMENT`` while the media is
+        still scheduled, which aborted otherwise-fine jobs — so status MUST
+        come from the batch-check call. Only once the media is SUCCESSFUL do
+        we fetch the encoded MP4 bytes (``GET /v1/media/<id>`` → base64).
+
+        Returns ``(ops_summary, raw_polls)`` mirroring the OLD-schema
+        ``check_async`` contract: one entry per workflow with
+        ``{name, done, media_entries, status, error}``. The poll loop in
+        the worker calls this repeatedly via ``check_async`` until ``done``.
+        """
+        ops_summary: list[dict[str, Any]] = []
+        raw_polls: list[dict[str, Any]] = []
+        for wf in workflows:
+            if not isinstance(wf, dict):
+                continue
+            name = wf.get("name")
+            mid = wf.get("primary_media_id")
+            if not isinstance(name, str) or not isinstance(mid, str) or not mid:
+                continue
+            pending = {
+                "name": name, "done": False, "media_entries": [],
+                "status": None, "error": None,
+            }
+            # 1. Status via the media-based batchCheckAsync (same call the web
+            #    client uses). projectId is required by Flow.
+            try:
+                status_resp = await self._client.api_request(
+                    url=VIDEO_POLL_URL,
+                    method="POST",
+                    headers=dict(_API_HEADERS),
+                    body={"media": [{"name": mid, "projectId": project_id}]},
+                )
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("workflow status poll error for %s: %s", mid[:8], exc)
+                ops_summary.append(pending)
+                continue
+            raw_polls.append({"name": name, "media_id": mid, "resp": status_resp})
+
+            m = _first_media_entry(status_resp, mid)
+            m_status = (
+                ((m.get("mediaMetadata") or {}).get("mediaStatus") or {})
+                .get("mediaGenerationStatus")
+            )
+            if m_status == "MEDIA_GENERATION_STATUS_FAILED":
+                ops_summary.append({
+                    **pending, "done": True, "status": m_status,
+                    "error": "MEDIA_GENERATION_STATUS_FAILED",
+                })
+                continue
+            if m_status != "MEDIA_GENERATION_STATUS_SUCCESSFUL":
+                # SCHEDULED / ACTIVE / PENDING / unknown — keep polling.
+                ops_summary.append(pending)
+                continue
+
+            # 2. SUCCESSFUL. Prefer a direct URL if the status payload carries
+            #    one; otherwise fetch the encoded MP4 bytes.
+            url = _media_url_from_entry(m)
+            if url:
+                ops_summary.append({
+                    "name": name, "done": True,
+                    "media_entries": [
+                        {"media_id": mid, "url": url, "mediaType": "video"}
+                    ],
+                    "status": m_status, "error": None,
+                })
+                continue
+            entry = await self._fetch_workflow_bytes(mid)
+            if entry is None:
+                # Status is SUCCESSFUL but bytes not materialised yet — keep
+                # polling rather than failing.
+                ops_summary.append(pending)
+                continue
+            ops_summary.append({
+                "name": name, "done": True, "media_entries": [entry],
+                "status": m_status, "error": None,
+            })
+        return ops_summary, raw_polls
+
+    async def _fetch_workflow_bytes(self, mid: str) -> Optional[dict[str, Any]]:
+        """Fetch a finished workflow clip's encoded MP4 via ``GET /v1/media/<id>``.
+
+        Returns a media entry (``{media_id, url, mediaType, encoded_video}``)
+        once Flow serves the base64 MP4, or ``None`` while the bytes are not
+        yet available (any error / non-``ftyp`` payload) so the caller keeps
+        polling.
+        """
+        import base64 as _b64
+
+        try:
+            resp = await self._client.api_request(
+                url=_media_get_url(mid),
+                method="GET",
+                headers=dict(_API_HEADERS),
+                body=None,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("workflow byte fetch error for %s: %s", mid[:8], exc)
+            return None
+        if not isinstance(resp, dict):
+            return None
+        status_code = resp.get("status")
+        if isinstance(status_code, int) and status_code >= 400:
+            return None  # not ready yet
+        data = resp.get("data") if isinstance(resp.get("data"), dict) else {}
+        video_block = data.get("video") if isinstance(data.get("video"), dict) else {}
+        encoded = (
+            video_block.get("encodedVideo") if isinstance(video_block, dict) else None
+        )
+        if not isinstance(encoded, str) or not encoded:
+            return None
+        try:
+            binary = _b64.b64decode(encoded, validate=False)
+        except Exception:  # noqa: BLE001
+            return None
+        # MP4 box layout: bytes 4..8 == "ftyp" on a complete file.
+        if not (len(binary) >= 12 and binary[4:8] == b"ftyp"):
+            return None
+        fife = (
+            video_block.get("fifeUrl") if isinstance(video_block, dict) else None
+        ) or data.get("fifeUrl")
+        return {
+            "media_id": mid,
+            "url": fife if isinstance(fife, str) else None,
+            "mediaType": "video",
+            "encoded_video": encoded,
+        }
+
+    # ── image generation (api_request + captcha) ───────────────────────────
+    async def gen_image(
+        self,
+        prompt: str,
+        project_id: str,
+        aspect_ratio: str = "IMAGE_ASPECT_RATIO_LANDSCAPE",
+        paygate_tier: Optional[str] = None,
+        ref_media_ids: Optional[list[str]] = None,
+        variant_count: int = 1,
+        character_media_ids: Optional[list[str]] = None,  # legacy alias
+        prompts: Optional[list[str]] = None,
+        image_model: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Generate ``variant_count`` images (1-4). When ``ref_media_ids`` is
+        provided, every request item is augmented with ``imageInputs`` so Flow
+        conditions the result on those upstream images (any combination of
+        character / image / visual_asset upstream nodes — all become
+        ``IMAGE_INPUT_TYPE_REFERENCE`` inputs).
+
+        Multiple variants are produced by replicating the request item with
+        distinct seeds — Flow returns one entry in ``data.media[]`` per
+        request item.
+
+        ``paygate_tier`` is required. See ``gen_video`` for rationale.
+        """
+        if paygate_tier is None:
+            raise ValueError("paygate_tier is required — caller must resolve before dispatch")
+        n = max(1, min(int(variant_count), MAX_VARIANT_COUNT))
+        ts = int(time.time() * 1000)
+        ctx = _client_context(project_id, paygate_tier)
+        model_name = resolve_image_model(image_model)
+        # Accept the legacy `character_media_ids` kwarg as a fallback.
+        merged_refs = ref_media_ids if ref_media_ids is not None else character_media_ids
+        image_inputs = None
+        if merged_refs:
+            image_inputs = [
+                {"name": mid, "imageInputType": "IMAGE_INPUT_TYPE_REFERENCE"}
+                for mid in merged_refs
+            ]
+
+        # Per-variant prompts: when the caller provides `prompts`, each
+        # request_item gets its own text so the 4 variants render with
+        # different poses instead of 4 seeds of one stance. Missing /
+        # short list falls back to the single `prompt` for that slot.
+        per_item_prompts: list[str] = []
+        for i in range(n):
+            if prompts and i < len(prompts) and isinstance(prompts[i], str) and prompts[i]:
+                per_item_prompts.append(prompts[i])
+            else:
+                per_item_prompts.append(prompt)
+
+        requests_arr: list[dict[str, Any]] = []
+        for i in range(n):
+            seed = (ts + i * 9973) % 1_000_000  # any deterministic spread is fine
+            item: dict[str, Any] = {
+                "clientContext": {**ctx, "sessionId": f";{ts + i}"},
+                "seed": seed,
+                "structuredPrompt": {"parts": [{"text": per_item_prompts[i]}]},
+                "imageAspectRatio": aspect_ratio,
+                "imageModelName": model_name,
+            }
+            if image_inputs is not None:
+                item["imageInputs"] = list(image_inputs)
+            requests_arr.append(item)
+
+        body = {
+            "clientContext": ctx,
+            "mediaGenerationContext": {"batchId": str(uuid.uuid4())},
+            "useNewMedia": True,
+            "requests": requests_arr,
+        }
+
+        resp = await self._client.api_request(
+            url=_generate_images_url(project_id),
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+            captcha_action=CAPTCHA_IMAGE,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        inner_err = _extract_inner_api_error(resp)
+        if inner_err:
+            return {"raw": resp, "error": inner_err}
+
+        entries = extract_media_entries(resp)
+        media_ids = [e["media_id"] for e in entries]
+        return {"raw": resp, "media_ids": media_ids, "media_entries": entries}
+
+    # ── image refine (edit_image) ──────────────────────────────────────────
+    async def edit_image(
+        self,
+        prompt: str,
+        project_id: str,
+        source_media_id: str,
+        ref_media_ids: Optional[list[str]] = None,
+        aspect_ratio: str = "IMAGE_ASPECT_RATIO_LANDSCAPE",
+        paygate_tier: Optional[str] = None,
+        image_model: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Refine an existing image with an optional list of reference media.
+
+        Order of ``imageInputs`` matters — flowkit puts BASE_IMAGE first so
+        Flow knows which is the canonical source.
+
+        ``paygate_tier`` is required. See ``gen_video`` for rationale.
+        """
+        if paygate_tier is None:
+            raise ValueError("paygate_tier is required — caller must resolve before dispatch")
+        ts = int(time.time() * 1000)
+        ctx = _client_context(project_id, paygate_tier)
+        model_name = resolve_image_model(image_model)
+
+        image_inputs: list[dict[str, Any]] = [
+            {"name": source_media_id, "imageInputType": "IMAGE_INPUT_TYPE_BASE_IMAGE"}
+        ]
+        for mid in ref_media_ids or []:
+            if isinstance(mid, str) and mid:
+                image_inputs.append(
+                    {"name": mid, "imageInputType": "IMAGE_INPUT_TYPE_REFERENCE"}
+                )
+
+        request_item = {
+            "clientContext": {**ctx, "sessionId": f";{ts}"},
+            "seed": ts % 1_000_000,
+            "structuredPrompt": {"parts": [{"text": prompt}]},
+            "imageAspectRatio": aspect_ratio,
+            "imageModelName": model_name,
+            "imageInputs": image_inputs,
+        }
+        body = {
+            "clientContext": ctx,
+            "mediaGenerationContext": {"batchId": str(uuid.uuid4())},
+            "useNewMedia": True,
+            "requests": [request_item],
+        }
+
+        resp = await self._client.api_request(
+            url=_generate_images_url(project_id),
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+            captcha_action=CAPTCHA_IMAGE,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+        inner_err = _extract_inner_api_error(resp)
+        if inner_err:
+            return {"raw": resp, "error": inner_err}
+
+        entries = extract_media_entries(resp)
+        media_ids = [e["media_id"] for e in entries]
+        return {"raw": resp, "media_ids": media_ids, "media_entries": entries}
+
+    # ── image upload (api_request, no captcha) ─────────────────────────────
+    async def upload_image(
+        self,
+        image_base64: str,
+        mime_type: str,
+        project_id: str,
+        file_name: str = "upload.png",
+    ) -> dict[str, Any]:
+        """Upload a user-provided image into a Flow project. Returns
+        ``{raw, media_id}`` on success or ``{raw, error}`` on failure.
+
+        ``image_base64`` should be a base64-encoded payload (no data: prefix).
+        Flow accepts the image bytes inline in the JSON body.
+        """
+        body = {
+            "clientContext": {
+                "projectId": str(project_id),
+                "tool": "PINHOLE",
+            },
+            "fileName": file_name,
+            "imageBytes": image_base64,
+            "isHidden": False,
+            "isUserUploaded": True,
+            "mimeType": mime_type,
+        }
+        resp = await self._client.api_request(
+            url=UPLOAD_IMAGE_URL,
+            method="POST",
+            headers=dict(_API_HEADERS),
+            body=body,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+
+        media_id = _extract_uploaded_media_id(resp)
+        if media_id is None:
+            # Flow returned 200 but no usable media handle. Most common cause
+            # is a silent content-filter rejection (logos/watermarks/branded
+            # imagery from product CDNs); next most common is a Flow schema
+            # change. Log the full payload so the operator can tell which.
+            logger.error(
+                "upload_image: no media_id in response (project_id=%s, "
+                "file=%s, mime=%s) — raw=%r",
+                project_id, file_name, mime_type, resp,
+            )
+            return {"raw": resp, "error": "no_media_id_in_upload_response"}
+        return {"raw": resp, "media_id": media_id}
+
+    # ── video upload (resumable, via extension) ────────────────────────────
+    async def upload_video(
+        self,
+        video_base64: str,
+        mime_type: str,
+        project_id: str,
+        file_name: str = "upload.mp4",
+        end_offset: str = "8s",
+    ) -> dict[str, Any]:
+        """Upload a user-provided video into a Flow project, returning
+        ``{raw, media_id, workflow_id, width, height}`` on success or
+        ``{raw, error}`` on failure.
+
+        Unlike images, video upload can't go through ``api_request`` — it's a
+        resumable, cookie-authed handshake against labs.google with a binary
+        PUT body. The extension runs that handshake in the browser session (a
+        ``upload_video`` bridge method) and hands back Flow's final
+        ``{mediaServerId, workflowServerId, videoWidth, videoHeight}`` payload.
+        We then register the trim window via ``videoFx.updateVideoOffset`` so
+        the upload becomes a referenceable workflow media — exactly what the
+        Flow web client does after a drag-and-drop upload.
+
+        ``video_base64`` should be a base64-encoded payload (no data: prefix).
+        """
+        resp = await self._client.upload_video(
+            project_id=project_id,
+            file_name=file_name,
+            content_type=mime_type,
+            data_base64=video_base64,
+        )
+        if isinstance(resp, dict) and resp.get("error"):
+            return {"raw": resp, "error": resp["error"]}
+
+        final = resp.get("data") if isinstance(resp, dict) else None
+        final = final if isinstance(final, dict) else {}
+        media_id = final.get("mediaServerId")
+        if not isinstance(media_id, str) or not media_id:
+            logger.error(
+                "upload_video: no mediaServerId in response (project_id=%s, "
+                "file=%s, mime=%s) — raw=%r",
+                project_id, file_name, mime_type, resp,
+            )
+            return {"raw": resp, "error": "no_media_id_in_upload_response"}
+
+        # Register the trim window (videoFx.updateVideoOffset). This is what
+        # promotes the raw upload into a usable workflow media; the media id is
+        # already valid, so a failure here is soft — surface it in raw for
+        # diagnosis but still return the id.
+        offset_resp = await self._client.trpc_request(
+            url=TRPC_UPDATE_VIDEO_OFFSET,
+            method="POST",
+            headers=_TRPC_HEADERS,
+            body={
+                "json": {
+                    "mediaId": media_id,
+                    "startOffset": "0s",
+                    "endOffset": end_offset,
+                }
+            },
+        )
+        workflow_id = final.get("workflowServerId")
+        return {
+            "raw": {"upload": resp, "offset": offset_resp},
+            "media_id": media_id,
+            "workflow_id": workflow_id if isinstance(workflow_id, str) else None,
+            "width": final.get("videoWidth"),
+            "height": final.get("videoHeight"),
+        }
+
+
+def _extract_project_id(resp: Any) -> Optional[str]:
+    """TRPC createProject nests the projectId quite deeply."""
+    try:
+        data = resp.get("data") if isinstance(resp, dict) else None
+        return data["result"]["data"]["json"]["result"]["projectId"]  # type: ignore[index]
+    except (KeyError, TypeError):
+        return None
+
+
+_VALID_TIERS = {"PAYGATE_TIER_ONE", "PAYGATE_TIER_TWO"}
+
+
+def _extract_uploaded_media_id(resp: Any) -> Optional[str]:
+    """uploadImage returns ``data.media.name`` as the new media_id."""
+    if not isinstance(resp, dict):
+        return None
+    data = resp.get("data")
+    if not isinstance(data, dict):
+        return None
+    media = data.get("media")
+    if isinstance(media, dict):
+        name = media.get("name")
+        if isinstance(name, str) and name:
+            return name
+    return None
+
+
+def extract_operation_names(resp: Any) -> list[str]:
+    """Pull ``operation.name`` out of a ``batchAsyncGenerateVideo*`` response.
+
+    Supports two shapes:
+
+    * **OLD** (Lite / Fast / Quality) — ``data.operations[].operation.name``.
+    * **NEW** (Low Priority — ``_low_priority`` / ``_relaxed`` models) —
+      ``data.workflows[].name``. Workflows don't have ``operation.name``;
+      callers that need to poll must also read ``primaryMediaId`` from
+      ``workflows[].metadata`` (see ``extract_video_workflows``).
+    """
+    if not isinstance(resp, dict):
+        return []
+    data = resp.get("data")
+    if not isinstance(data, dict):
+        return []
+    names: list[str] = []
+    ops = data.get("operations")
+    if isinstance(ops, list):
+        for op in ops:
+            if not isinstance(op, dict):
+                continue
+            inner = op.get("operation") if isinstance(op.get("operation"), dict) else None
+            if inner is None:
+                # Some variants inline the name at top level.
+                name = op.get("name")
+            else:
+                name = inner.get("name")
+            if isinstance(name, str) and name:
+                names.append(name)
+    if names:
+        return names
+    # NEW workflow schema. The tracking key is the workflow id — take it from
+    # `media[].workflowId` (preferred, pairs with extract_video_workflows) or
+    # fall back to `workflows[].name`. The two normally coincide; keeping them
+    # consistent ensures check_async routes these to workflow polling, not the
+    # operation poll (which would 400 on a workflow id).
+    media = data.get("media")
+    if isinstance(media, list):
+        for m in media:
+            wf = m.get("workflowId") if isinstance(m, dict) else None
+            if isinstance(wf, str) and wf and wf not in names:
+                names.append(wf)
+    if names:
+        return names
+    workflows = data.get("workflows")
+    if isinstance(workflows, list):
+        for wf in workflows:
+            if not isinstance(wf, dict):
+                continue
+            name = wf.get("name")
+            if isinstance(name, str) and name:
+                names.append(name)
+    return names
+
+
+def extract_video_workflows(resp: Any) -> list[dict[str, Any]]:
+    """Pull workflow entries out of a NEW-schema video submit response.
+
+    Returns ``[{"name": <workflow_name>, "primary_media_id": <new media uuid>},
+    ...]`` — the media id to poll for the freshly generated output. Empty list
+    when the response is OLD-schema (operations-based) or has no workflows.
+
+    Source of the media id matters: ``data.media[].name`` is the NEW output, and
+    we pair it to its workflow via ``media[].workflowId``. For **edit** the
+    workflow's ``metadata.primaryMediaId`` still points at the SOURCE clip, so
+    polling that would return the un-edited input — we must poll ``media[].name``
+    instead. For t2v/r2v/extend the two coincide, so ``media[]`` is correct in
+    all cases. ``workflows[].metadata.primaryMediaId`` is only a fallback for a
+    response that omits ``media[]``.
+    """
+    if not isinstance(resp, dict):
+        return []
+    data = resp.get("data")
+    if not isinstance(data, dict):
+        return []
+
+    out: list[dict[str, Any]] = []
+    media = data.get("media")
+    if isinstance(media, list):
+        for m in media:
+            if not isinstance(m, dict):
+                continue
+            mid = m.get("name")
+            wf = m.get("workflowId")
+            if isinstance(mid, str) and mid and isinstance(wf, str) and wf:
+                out.append({"name": wf, "primary_media_id": mid})
+        if out:
+            return out
+
+    # Fallback: derive from workflows[].metadata.primaryMediaId (no media[]).
+    workflows = data.get("workflows")
+    if not isinstance(workflows, list):
+        return []
+    for wf in workflows:
+        if not isinstance(wf, dict):
+            continue
+        name = wf.get("name")
+        meta = wf.get("metadata") if isinstance(wf.get("metadata"), dict) else {}
+        primary = meta.get("primaryMediaId") if isinstance(meta, dict) else None
+        if isinstance(name, str) and name and isinstance(primary, str) and primary:
+            out.append({"name": name, "primary_media_id": primary})
+    return out
+
+
+def extract_video_operations(
+    resp: Any, *, requested: list[str]
+) -> list[dict[str, Any]]:
+    """Summarise a ``batchCheckAsync`` response.
+
+    Flow's response shape is::
+
+        {"data": {"operations": [{
+            "status": "MEDIA_GENERATION_STATUS_{PENDING,SUCCESSFUL,FAILED}",
+            "operation": {"name": "<id>", "metadata": {"video": {
+                "mediaId": "<uuid>", "fifeUrl": "https://flow-content..."
+            }}}
+        }]}}
+
+    flowkit treats ``MEDIA_GENERATION_STATUS_SUCCESSFUL`` as terminal-success;
+    we mirror that.
+
+    Returns one entry per *requested* operation name, in order. Missing
+    operations are reported as ``done=False`` so the caller can keep polling.
+    """
+    by_name: dict[str, dict[str, Any]] = {}
+    if isinstance(resp, dict):
+        data = resp.get("data")
+        if isinstance(data, dict):
+            ops = data.get("operations")
+            if isinstance(ops, list):
+                for op in ops:
+                    if not isinstance(op, dict):
+                        continue
+                    inner = op.get("operation") if isinstance(op.get("operation"), dict) else op
+                    name = inner.get("name") if isinstance(inner, dict) else None
+                    if not isinstance(name, str):
+                        continue
+                    meta = (inner.get("metadata") or {}) if isinstance(inner, dict) else {}
+                    video_meta = meta.get("video") if isinstance(meta.get("video"), dict) else {}
+                    media_id = video_meta.get("mediaId") if isinstance(video_meta, dict) else None
+                    fife = video_meta.get("fifeUrl") if isinstance(video_meta, dict) else None
+                    # Flow's video poll response usually omits `mediaId` and only
+                    # provides `mediaGenerationId` (base64 protobuf, NOT a UUID).
+                    # The actual UUID is embedded in the `fifeUrl` path. Recover it.
+                    if not (isinstance(media_id, str) and media_id):
+                        recovered = _media_id_from_url(fife if isinstance(fife, str) else None)
+                        if recovered is None and isinstance(video_meta, dict):
+                            recovered = _media_id_from_url(video_meta.get("servingBaseUri"))
+                        if recovered is not None:
+                            media_id = recovered
+                    # Flow puts the status at the *top* of each op envelope,
+                    # not on the inner operation object — bug we hit before.
+                    status = op.get("status") if isinstance(op.get("status"), str) else None
+                    # Per-op terminal failure (e.g. PUBLIC_ERROR_AUDIO_FILTERED).
+                    # Flow puts the error on the inner operation object as
+                    # ``{code, message}``. We surface it so the worker can bail
+                    # instead of polling for the full timeout.
+                    op_err: Optional[str] = None
+                    inner_err = inner.get("error") if isinstance(inner, dict) else None
+                    if isinstance(inner_err, dict):
+                        msg = inner_err.get("message") or inner_err.get("status") or "operation_failed"
+                        op_err = str(msg)
+                    if status == "MEDIA_GENERATION_STATUS_FAILED" and op_err is None:
+                        op_err = "MEDIA_GENERATION_STATUS_FAILED"
+                    done_flag = (
+                        status == "MEDIA_GENERATION_STATUS_SUCCESSFUL"
+                        or status == "MEDIA_GENERATION_STATUS_FAILED"
+                        or bool(inner.get("done"))
+                        or bool(media_id and fife)
+                    )
+                    entries = []
+                    if (
+                        done_flag
+                        and op_err is None
+                        and isinstance(media_id, str)
+                    ):
+                        entries.append(
+                            {
+                                "media_id": media_id,
+                                "url": fife if isinstance(fife, str) else None,
+                                "mediaType": "video",
+                            }
+                        )
+                    by_name[name] = {
+                        "name": name,
+                        "done": done_flag,
+                        "media_entries": entries,
+                        "status": status,
+                        "error": op_err,
+                    }
+
+    out: list[dict[str, Any]] = []
+    for name in requested:
+        out.append(
+            by_name.get(
+                name, {"name": name, "done": False, "media_entries": []}
+            )
+        )
+    return out
+
+
+def _extract_media_ids(resp: Any) -> list[str]:
+    return [e["media_id"] for e in extract_media_entries(resp)]
+
+
+def extract_media_entries(resp: Any) -> list[dict[str, Any]]:
+    """Pull media entries out of a ``batchGenerateImages`` response.
+
+    Returns a list of ``{media_id, url, mediaType}`` dicts suitable for
+    ``media.ingest_urls``. ``url`` may be missing if Flow didn't include a
+    ``fifeUrl`` for some reason — caller should handle that.
+    """
+    if not isinstance(resp, dict):
+        return []
+    data = resp.get("data")
+    if not isinstance(data, dict):
+        return []
+    media = data.get("media")
+    if not isinstance(media, list):
+        return []
+    out: list[dict[str, Any]] = []
+    for m in media:
+        if not isinstance(m, dict):
+            continue
+        media_id = m.get("name")
+        if not isinstance(media_id, str) or not media_id:
+            continue
+        url: Optional[str] = None
+        kind = "image"
+        image = m.get("image") if isinstance(m.get("image"), dict) else None
+        video = m.get("video") if isinstance(m.get("video"), dict) else None
+        if image is not None:
+            gen = image.get("generatedImage")
+            if isinstance(gen, dict):
+                candidate = gen.get("fifeUrl")
+                if isinstance(candidate, str):
+                    url = candidate
+            kind = "image"
+        elif video is not None:
+            gen = video.get("generatedVideo") or video.get("generatedImage")
+            if isinstance(gen, dict):
+                candidate = gen.get("fifeUrl")
+                if isinstance(candidate, str):
+                    url = candidate
+            kind = "video"
+        out.append({"media_id": media_id, "url": url, "mediaType": kind})
+    return out
+
+
+_sdk: Optional[FlowSDK] = None
+
+
+def get_flow_sdk() -> FlowSDK:
+    global _sdk
+    if _sdk is None:
+        _sdk = FlowSDK()
+    return _sdk