@oh-story/dsh 0.1.4 → 0.1.6

package/lib/drama/skills/short-drama-produce/scripts/provider_adapters.py

@@ -32,6 +32,7 @@ MINIMAX_MUSIC_MODEL = "music-3.0"
 OPENAI_BASE_URL = "https://api.openai.com/v1"
 SEEDANCE_BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"
 MINIMAX_BASE_URL = "https://api.minimax.io/v1"
+MINIMAX_VIDEO_BASE_URL = "https://api.minimax.io/v2"
 MAX_JSON_RESPONSE = 128 * 1024 * 1024
 MAX_OUTPUT_BYTES = 512 * 1024 * 1024
 MAX_REFERENCE_BYTES = 50 * 1024 * 1024
@@ -39,6 +40,47 @@ MAX_MULTIPART_BYTES = 200 * 1024 * 1024
 MAX_ERROR_BODY_BYTES = 64 * 1024
 TERMINAL_FAILURES = {"failed", "cancelled", "canceled", "timeout", "expired"}
 SEEDANCE_RATIOS = {"adaptive", "1:1", "3:4", "4:3", "9:16", "16:9", "21:9"}
+SEEDANCE_REFERENCE_ROLES = {
+    "reference_image": "image_url",
+    "reference_video": "video_url",
+    "reference_audio": "audio_url",
+}
+MINIMAX_VIDEO_RATIOS = {"adaptive", "1:1", "3:4", "4:3", "9:16", "16:9", "21:9"}
+MINIMAX_VIDEO_RESOLUTIONS = {"480P", "768P", "2K"}
+MINIMAX_VIDEO_PROMPT_LIMIT = 7000
+MINIMAX_VIDEO_ROLES = {
+    "first_frame": "image_url",
+    "last_frame": "image_url",
+    "reference_image": "image_url",
+    "reference_video": "video_url",
+    "reference_audio": "audio_url",
+}
+# Both providers document a `data:<mime>;base64,<...>` URI as an accepted media
+# input alongside a public URL, so a local project reference needs no upload
+# service to reach them. The caps are MiniMax's published per-modality limits;
+# Seedance publishes no numbers, so the same conservative guard is applied there
+# and can be raised per deployment. Base64 inflates bytes by about a third, so
+# the request cap is checked against the encoded size.
+INLINE_REFERENCE_LIMITS = {
+    "image_url": 30 * 1024 * 1024,
+    "video_url": 50 * 1024 * 1024,
+    "audio_url": 15 * 1024 * 1024,
+}
+INLINE_REFERENCE_BODY_LIMIT = 64 * 1024 * 1024
+INLINE_REFERENCE_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+    ".wav": "audio/wav",
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".aac": "audio/aac",
+    ".flac": "audio/flac",
+}
 GPT_IMAGE_MIN_PIXELS = 655_360
 GPT_IMAGE_MAX_PIXELS = 8_294_400
 MINIMUM_PYTHON = (3, 9)
@@ -161,6 +203,96 @@ def _require_job(job: Mapping[str, Any], modality: str) -> tuple[str, dict[str,
     return prompt, dict(parameters)
 
 
+def _prompt_with_reference_contract(
+    prompt: str,
+    job: Mapping[str, Any],
+    *,
+    prompt_language: str | None = None,
+    reference_tokens: Sequence[str] = (),
+    zh_reference_prefix: str = "参考",
+    zh_heading: str = "参考约束：",
+) -> str:
+    bindings = job.get("reference_bindings", [])
+    references = job.get("references", [])
+    if not bindings:
+        return prompt
+    if (
+        not isinstance(bindings, list)
+        or not isinstance(references, list)
+        or len(bindings) != len(references)
+    ):
+        raise ValueError("reference bindings must match job references")
+    if reference_tokens and len(reference_tokens) != len(references):
+        raise ValueError("reference tokens must match job references")
+    language = (prompt_language or "en").casefold()
+    instructions: list[str] = []
+    for index, binding in enumerate(bindings, 1):
+        if not isinstance(binding, Mapping) or binding.get("order") != index:
+            raise ValueError("reference binding order is invalid")
+        if binding.get("path") != references[index - 1]:
+            raise ValueError("reference binding path does not match job references")
+        label = binding.get("label")
+        role = binding.get("role")
+        may_control = binding.get("may_control")
+        must_not_control = binding.get("must_not_control")
+        if (
+            not isinstance(label, str)
+            or not label.strip()
+            or not isinstance(role, str)
+            or not role.strip()
+            or not isinstance(may_control, list)
+            or not may_control
+            or not all(isinstance(item, str) and item.strip() for item in may_control)
+            or not isinstance(must_not_control, list)
+            or not must_not_control
+            or not all(isinstance(item, str) and item.strip() for item in must_not_control)
+        ):
+            raise ValueError("reference binding semantics are invalid")
+        values = {
+            "order": index,
+            "reference": reference_tokens[index - 1] if reference_tokens else str(index),
+            "label": label.strip(),
+            "role": role.strip(),
+            "may": ", ".join(item.strip() for item in may_control),
+            "must": ", ".join(item.strip() for item in must_not_control),
+        }
+        if language.startswith("zh"):
+            instructions.append(
+                f"{zh_reference_prefix} "
+                + (
+                    "{reference}（{label}），用途 {role}。允许控制：{may}。"
+                    "不得控制：{must}。".format(**values)
+                )
+            )
+        elif language.startswith("en"):
+            instructions.append(
+                "Reference {reference} ({label}), role {role}. May control: {may}. "
+                "Must not control: {must}.".format(**values)
+            )
+        else:
+            instructions.append(
+                "[REF {order} | {label} | {role}] [+] {may} [-] {must}".format(
+                    **values
+                )
+            )
+    if language.startswith("zh"):
+        heading = zh_heading
+    elif language.startswith("en"):
+        heading = "Reference contract:"
+    else:
+        heading = "<REF_CONTRACT>"
+    return f"{prompt}\n\n{heading}\n" + "\n".join(instructions)
+
+
+def _pop_prompt_language(parameters: dict[str, Any]) -> str | None:
+    value = parameters.pop("prompt_language", None)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip() or len(value) > 64:
+        raise ValueError("prompt_language must be a non-empty bounded language tag")
+    return value.strip()
+
+
 def _take(parameters: dict[str, Any], allowed: set[str]) -> dict[str, Any]:
     unknown = set(parameters) - allowed
     if unknown:
@@ -173,6 +305,7 @@ def compile_seedance_payload(
     *,
     model: str,
     reference_urls: Sequence[str] = (),
+    reference_roles: Sequence[str] = (),
     allowed_ratios: Collection[str] | None = None,
     duration_range: tuple[int, int] | None = None,
 ) -> dict[str, Any]:
@@ -187,24 +320,33 @@ def compile_seedance_payload(
     references = job.get("references", [])
     if not isinstance(references, list) or len(reference_urls) != len(references):
         raise ValueError("Seedance reference URLs must match job references")
+    if len(reference_roles) != len(reference_urls):
+        raise ValueError("Seedance reference roles must match job references")
     if Path(job["outputs"][0]).suffix.casefold() != ".mp4":
         raise ValueError("Seedance adapter requires an MP4 target")
     parameters = _take(
         parameters,
-        {"duration", "ratio"},
+        {
+            "duration",
+            "ratio",
+            "generate_audio",
+            "omni_reference_task_type",
+            "prompt_language",
+        },
     )
+    prompt_language = _pop_prompt_language(parameters)
     duration = parameters.get("duration")
     if duration is not None and (
         not isinstance(duration, int)
         or isinstance(duration, bool)
-        or not 1 <= duration <= 15
+        or (duration != -1 and not 1 <= duration <= 30)
     ):
-        raise ValueError("Seedance duration must be an integer from 1 to 15")
-    if duration is not None:
+        raise ValueError("Seedance duration must be -1 or an integer from 1 to 30")
+    if duration is not None and duration != -1:
         if duration_range is None:
             raise ValueError("Seedance duration needs an explicit model profile")
         minimum, maximum = duration_range
-        if not 1 <= minimum <= maximum <= 15 or not minimum <= duration <= maximum:
+        if not 1 <= minimum <= maximum <= 30 or not minimum <= duration <= maximum:
             raise ValueError("Seedance duration is outside the configured model profile")
     ratio = parameters.get("ratio")
     if ratio is not None and (
@@ -217,38 +359,78 @@ def compile_seedance_payload(
             raise ValueError("Seedance ratio needs an explicit model profile")
         if not configured_ratios <= SEEDANCE_RATIOS or ratio.strip() not in configured_ratios:
             raise ValueError("Seedance ratio is outside the configured model profile")
-    text = prompt
-    if ratio is not None:
-        text += f" --ratio {ratio.strip()}"
-    if duration is not None:
-        text += f" --dur {duration}"
+        ratio = ratio.strip()
+    generate_audio = parameters.get("generate_audio")
+    if generate_audio is not None and not isinstance(generate_audio, bool):
+        raise ValueError("Seedance generate_audio must be a boolean")
+    task_type = parameters.get("omni_reference_task_type")
+    if task_type is not None and task_type not in {"auto", "reference", "edit", "extend"}:
+        raise ValueError("Seedance omni reference task type is invalid")
+    counters = {"image_url": 0, "video_url": 0, "audio_url": 0}
+    labels = {"image_url": "图片", "video_url": "视频", "audio_url": "音频"}
+    reference_tokens: list[str] = []
+    for role in reference_roles:
+        field = SEEDANCE_REFERENCE_ROLES.get(role)
+        if field is None:
+            raise ValueError(f"unsupported Seedance reference role: {role}")
+        counters[field] += 1
+        reference_tokens.append(f"@{labels[field]}{counters[field]}")
+    if task_type in {"edit", "extend"} and "reference_video" not in reference_roles:
+        raise ValueError(f"Seedance {task_type} requires a reference video")
+    if task_type == "edit" and (ratio != "adaptive" or duration != -1):
+        raise ValueError("Seedance edit requires adaptive ratio and duration -1")
+    if task_type == "extend" and ratio != "adaptive":
+        raise ValueError("Seedance extend requires an adaptive ratio")
+    text = _prompt_with_reference_contract(
+        prompt,
+        job,
+        prompt_language=prompt_language,
+        reference_tokens=reference_tokens,
+        zh_reference_prefix=(
+            "输入素材" if task_type in {"edit", "extend"} else "参考"
+        ),
+        zh_heading=(
+            "输入素材约束：" if task_type in {"edit", "extend"} else "参考约束："
+        ),
+    )
     content: list[dict[str, Any]] = [{"type": "text", "text": text}]
     for index, url in enumerate(reference_urls):
         if not isinstance(url, str) or not url:
             raise ValueError("Seedance reference URL must be non-empty")
+        role = reference_roles[index]
+        field = SEEDANCE_REFERENCE_ROLES[role]
         suffix = Path(str(references[index])).suffix.casefold()
-        if suffix in {".png", ".jpg", ".jpeg", ".webp"}:
-            parsed = urllib.parse.urlparse(url)
-            if (
-                parsed.scheme == "https" and parsed.netloc
-            ) or (
+        expected = {
+            "image_url": {".png", ".jpg", ".jpeg", ".webp"},
+            "video_url": {".mp4", ".mov", ".webm"},
+            "audio_url": {".wav", ".mp3", ".m4a", ".aac", ".flac"},
+        }[field]
+        if suffix not in expected:
+            raise ValueError(f"Seedance {role} does not match the reference file type")
+        parsed = urllib.parse.urlparse(url)
+        if not (
+            (parsed.scheme == "https" and parsed.netloc)
+            or (
                 parsed.scheme == "asset"
                 and parsed.netloc.startswith("asset-")
                 and not parsed.path
-            ):
-                pass
-            else:
-                raise ValueError("Seedance reference URL must be HTTPS or asset://")
-            content.append(
-                {
-                    "type": "image_url",
-                    "image_url": {"url": url},
-                    "role": "reference_image",
-                }
             )
-        else:
-            raise ValueError("Seedance adapter accepts image references only")
-    return {"model": model.strip(), "content": content}
+            or _is_inline_reference(url)
+        ):
+            raise ValueError(
+                "Seedance reference URL must be HTTPS, asset:// or a base64 data URI"
+            )
+        content.append({"type": field, field: {"url": url}, "role": role})
+    body: dict[str, Any] = {"model": model.strip(), "content": content}
+    if ratio is not None:
+        body["ratio"] = ratio
+    if duration is not None:
+        body["duration"] = duration
+    if generate_audio is not None:
+        body["generate_audio"] = generate_audio
+    if task_type is not None:
+        body["omni_reference_task_type"] = task_type
+    return body
 
 
 def _seedance_runtime_profile(
@@ -288,7 +470,7 @@ def _seedance_runtime_profile(
             code="invalid_model_profile",
         )
     if duration_range is not None and not (
-        1 <= duration_range[0] <= duration_range[1] <= 15
+        1 <= duration_range[0] <= duration_range[1] <= 30
     ):
         raise AdapterFailure(
             "Seedance duration profile is invalid",
@@ -298,12 +480,198 @@ def _seedance_runtime_profile(
     return allowed_ratios, duration_range
 
 
+def compile_minimax_h3_payload(
+    job: Mapping[str, Any],
+    *,
+    model: str,
+    reference_urls: Sequence[str] = (),
+    reference_roles: Sequence[str] = (),
+    allowed_ratios: Collection[str] | None = None,
+    allowed_resolutions: Collection[str] | None = None,
+    duration_range: tuple[int, int] | None = None,
+) -> dict[str, Any]:
+    """Compile a video job into the official MiniMax video-generation task body.
+
+    ``model`` is mandatory for the same reason it is for Seedance: which release
+    is enabled, and what it accepts, is deployment configuration, never an
+    assumption made here.
+    """
+    prompt, parameters = _require_job(job, "video")
+    if not isinstance(model, str) or not model.strip():
+        raise ValueError("MiniMax video model must be explicitly configured")
+    references = job.get("references", [])
+    if not isinstance(references, list) or len(reference_urls) != len(references):
+        raise ValueError("MiniMax reference URLs must match job references")
+    if len(reference_roles) != len(reference_urls):
+        raise ValueError("MiniMax reference roles must match job references")
+    if Path(job["outputs"][0]).suffix.casefold() != ".mp4":
+        raise ValueError("MiniMax video adapter requires an MP4 target")
+    parameters = _take(
+        parameters, {"duration", "ratio", "resolution", "prompt_language"}
+    )
+    prompt_language = _pop_prompt_language(parameters)
+
+    duration = parameters.get("duration")
+    if not isinstance(duration, int) or isinstance(duration, bool):
+        raise ValueError("MiniMax video duration must be an integer number of seconds")
+    if duration_range is None:
+        raise ValueError("MiniMax video duration needs an explicit model profile")
+    minimum, maximum = duration_range
+    if not 1 <= minimum <= maximum or not minimum <= duration <= maximum:
+        raise ValueError("MiniMax video duration is outside the configured model profile")
+
+    resolution = parameters.get("resolution")
+    if not isinstance(resolution, str) or resolution.strip() not in MINIMAX_VIDEO_RESOLUTIONS:
+        raise ValueError("MiniMax video resolution is outside the supported profile")
+    configured_resolutions = set(allowed_resolutions or ())
+    if not configured_resolutions:
+        raise ValueError("MiniMax video resolution needs an explicit model profile")
+    if (
+        not configured_resolutions <= MINIMAX_VIDEO_RESOLUTIONS
+        or resolution.strip() not in configured_resolutions
+    ):
+        raise ValueError("MiniMax video resolution is outside the configured model profile")
+
+    ratio = parameters.get("ratio")
+    if ratio is not None:
+        if not isinstance(ratio, str) or ratio.strip() not in MINIMAX_VIDEO_RATIOS:
+            raise ValueError("MiniMax video ratio is outside the supported profile")
+        configured_ratios = set(allowed_ratios or ())
+        if not configured_ratios:
+            raise ValueError("MiniMax video ratio needs an explicit model profile")
+        if (
+            not configured_ratios <= MINIMAX_VIDEO_RATIOS
+            or ratio.strip() not in configured_ratios
+        ):
+            raise ValueError("MiniMax video ratio is outside the configured model profile")
+
+    counters = {"image_url": 0, "video_url": 0, "audio_url": 0}
+    labels = {"image_url": "Picture", "video_url": "Video", "audio_url": "Audio"}
+    reference_tokens: list[str] = []
+    for role in reference_roles:
+        field = MINIMAX_VIDEO_ROLES.get(role)
+        if field is None:
+            raise ValueError(f"unsupported MiniMax reference role: {role}")
+        counters[field] += 1
+        reference_tokens.append(f"<{labels[field]} {counters[field]}>")
+    text = _prompt_with_reference_contract(
+        prompt,
+        job,
+        prompt_language=prompt_language,
+        reference_tokens=reference_tokens,
+    )
+    if len(text) > MINIMAX_VIDEO_PROMPT_LIMIT:
+        raise ValueError("MiniMax video prompt exceeds the provider limit")
+    content: list[dict[str, Any]] = [{"type": "text", "text": text}]
+    seen_roles: list[str] = []
+    for index, url in enumerate(reference_urls):
+        role = reference_roles[index]
+        if role not in MINIMAX_VIDEO_ROLES:
+            raise ValueError(f"unsupported MiniMax reference role: {role}")
+        if role in {"first_frame", "last_frame"} and role in seen_roles:
+            raise ValueError(f"MiniMax accepts one {role} reference")
+        seen_roles.append(role)
+        if not isinstance(url, str) or not url:
+            raise ValueError("MiniMax reference URL must be non-empty")
+        parsed = urllib.parse.urlparse(url)
+        if not (
+            (parsed.scheme == "https" and parsed.netloc)
+            or (parsed.scheme == "mm_file" and parsed.netloc and not parsed.path)
+            or _is_inline_reference(url)
+        ):
+            raise ValueError(
+                "MiniMax reference URL must be HTTPS, mm_file:// or a base64 data URI"
+            )
+        field = MINIMAX_VIDEO_ROLES[role]
+        content.append({"type": field, field: {"url": url}, "role": role})
+    frame_roles = {"first_frame", "last_frame"}
+    reference_roles_present = {"reference_image", "reference_video", "reference_audio"}
+    if frame_roles.intersection(seen_roles) and reference_roles_present.intersection(
+        seen_roles
+    ):
+        raise ValueError(
+            "MiniMax frame conditioning cannot be mixed with reference conditioning"
+        )
+    if ratio is None and len(content) == 1:
+        raise ValueError("MiniMax text-to-video requires an explicit ratio")
+    body: dict[str, Any] = {
+        "model": model.strip(),
+        "content": content,
+        "duration": duration,
+        "resolution": resolution.strip(),
+    }
+    if ratio is not None:
+        if ratio.strip() == "adaptive" and len(content) == 1:
+            raise ValueError("MiniMax text-to-video cannot use an adaptive ratio")
+        body["ratio"] = ratio.strip()
+    return body
+
+
+def _minimax_video_runtime_profile() -> tuple[
+    frozenset[str] | None, frozenset[str] | None, tuple[int, int] | None
+]:
+    def _set(name: str, supported: Collection[str]) -> frozenset[str] | None:
+        raw = os.environ.get(name)
+        if raw is None:
+            return None
+        values = frozenset(item.strip() for item in raw.split(",") if item.strip())
+        if not values or not values <= set(supported):
+            raise AdapterFailure(
+                f"MiniMax video profile is invalid: {name}",
+                category="configuration",
+                code="invalid_model_profile",
+            )
+        return values
+
+    allowed_ratios = _set("MINIMAX_VIDEO_RATIOS", MINIMAX_VIDEO_RATIOS)
+    allowed_resolutions = _set("MINIMAX_VIDEO_RESOLUTIONS", MINIMAX_VIDEO_RESOLUTIONS)
+    minimum_raw = os.environ.get("MINIMAX_VIDEO_MIN_DURATION")
+    maximum_raw = os.environ.get("MINIMAX_VIDEO_MAX_DURATION")
+    if (minimum_raw is None) != (maximum_raw is None):
+        raise AdapterFailure(
+            "MiniMax video duration profile is incomplete",
+            category="configuration",
+            code="invalid_model_profile",
+        )
+    try:
+        duration_range = (
+            (int(minimum_raw), int(maximum_raw))
+            if minimum_raw is not None and maximum_raw is not None
+            else None
+        )
+    except ValueError as exc:
+        raise AdapterFailure(
+            "MiniMax video duration profile is invalid",
+            category="configuration",
+            code="invalid_model_profile",
+        ) from exc
+    if duration_range is not None and not 1 <= duration_range[0] <= duration_range[1]:
+        raise AdapterFailure(
+            "MiniMax video duration profile is invalid",
+            category="configuration",
+            code="invalid_model_profile",
+        )
+    return allowed_ratios, allowed_resolutions, duration_range
+
+
 def compile_gpt_image_2_payload(job: Mapping[str, Any]) -> dict[str, Any]:
     """Compile an image job into GPT Image 2 generation/edit fields."""
     prompt, parameters = _require_job(job, "image")
     parameters = _take(
         parameters,
-        {"width", "height", "size", "quality", "background", "moderation"},
+        {
+            "width",
+            "height",
+            "size",
+            "quality",
+            "background",
+            "moderation",
+            "prompt_language",
+        },
+    )
+    prompt_language = _pop_prompt_language(parameters)
+    prompt = _prompt_with_reference_contract(
+        prompt, job, prompt_language=prompt_language
     )
     if len(prompt) > 32000:
         raise ValueError("GPT Image prompt exceeds the provider limit")
@@ -499,7 +867,9 @@ def _read_reference(path: Path) -> bytes:
         raise ValueError("reference is not a regular file")
     if before.st_size > MAX_REFERENCE_BYTES:
         raise ValueError("reference exceeds the provider input size limit")
-    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    # Windows opens files in text mode unless told otherwise, which stops the
+    # read at the first 0x1A byte -- the seventh byte of every PNG signature.
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
     descriptor = os.open(path, flags)
     try:
         opened = os.fstat(descriptor)
@@ -573,6 +943,97 @@ def _reference_paths(job: Mapping[str, Any]) -> list[Path]:
     return result
 
 
+def _binding_roles(
+    job: Mapping[str, Any], *, allowed: Mapping[str, str], provider: str
+) -> list[str]:
+    """The provider role of each reference, taken from the confirmed job.
+
+    `role` is the production-side translation of the creator document's 用途, so
+    it is the job -- not this adapter -- that decides what a picture is for.
+    """
+    bindings = job.get("reference_bindings", [])
+    references = job.get("references", [])
+    if not isinstance(bindings, list) or len(bindings) != len(references):
+        raise AdapterFailure(
+            f"{provider} references need one reference_bindings entry each, "
+            "carrying the provider role for that file",
+            category="configuration",
+            code="missing_reference_roles",
+        )
+    roles: list[str] = []
+    for binding in bindings:
+        role = binding.get("role") if isinstance(binding, Mapping) else None
+        if not isinstance(role, str) or role not in allowed:
+            raise AdapterFailure(
+                f"{provider} reference role must be one of "
+                + ", ".join(sorted(allowed))
+                + f"; got {role!r}",
+                category="configuration",
+                code="invalid_reference_role",
+            )
+        roles.append(role)
+    return roles
+
+
+def _inline_reference_urls(
+    paths: Sequence[Path], roles: Sequence[str], *, allowed: Mapping[str, str], provider: str
+) -> list[str]:
+    """Encode local project references as `data:` URIs the provider accepts."""
+    urls: list[str] = []
+    total = 0
+    for path, role in zip(paths, roles):
+        field = allowed[role]
+        suffix = path.suffix.casefold()
+        mime = INLINE_REFERENCE_MIME.get(suffix)
+        expected = field.split("_", 1)[0]
+        if mime is None or not mime.startswith(expected):
+            raise AdapterFailure(
+                f"{provider} {role} does not accept a {suffix or 'suffixless'} file",
+                category="configuration",
+                code="invalid_reference_type",
+            )
+        try:
+            content = path.read_bytes()
+        except OSError as exc:
+            raise AdapterFailure(
+                f"{provider} could not read a project reference",
+                category="configuration",
+                code="unreadable_reference",
+            ) from exc
+        if not content:
+            raise AdapterFailure(
+                f"{provider} project reference is empty",
+                category="configuration",
+                code="empty_reference",
+            )
+        # The bytes have to be the media type the extension claims, or the
+        # provider rejects a request this adapter said was well formed.
+        _validate_media_content(path.name, content)
+        limit = INLINE_REFERENCE_LIMITS[field]
+        if len(content) > limit:
+            raise AdapterFailure(
+                f"{provider} reference exceeds the {limit // (1024 * 1024)}MB inline "
+                "limit; host it and bind an HTTPS URL instead",
+                category="configuration",
+                code="reference_too_large",
+            )
+        encoded = base64.b64encode(content).decode("ascii")
+        total += len(encoded)
+        if total > INLINE_REFERENCE_BODY_LIMIT:
+            raise AdapterFailure(
+                f"{provider} inline references exceed the request body limit; "
+                "host the largest ones and bind HTTPS URLs instead",
+                category="configuration",
+                code="reference_body_too_large",
+            )
+        urls.append(f"data:{mime};base64,{encoded}")
+    return urls
+
+
+def _is_inline_reference(url: str) -> bool:
+    return bool(re.fullmatch(r"data:[\w.+-]+/[\w.+-]+;base64,[A-Za-z0-9+/]+=*", url))
+
+
 def _validate_media_content(target: str, content: bytes) -> None:
     suffix = Path(target).suffix.casefold()
     signatures = {
@@ -677,14 +1138,20 @@ def _run_seedance(job: Mapping[str, Any]) -> tuple[Path, str]:
     token = _credential("ARK_API_KEY")
     model = os.environ.get("SEEDANCE_MODEL", "")
     references = _reference_paths(job)
-    if references:
-        raise AdapterFailure(
-            "Seedance local references require an external trusted HTTPS upload adapter"
-        )
+    reference_roles = (
+        _binding_roles(job, allowed=SEEDANCE_REFERENCE_ROLES, provider="Seedance")
+        if references
+        else []
+    )
+    reference_urls = _inline_reference_urls(
+        references, reference_roles, allowed=SEEDANCE_REFERENCE_ROLES, provider="Seedance"
+    )
     allowed_ratios, duration_range = _seedance_runtime_profile()
     body = compile_seedance_payload(
         job,
         model=model,
+        reference_urls=reference_urls,
+        reference_roles=reference_roles,
         allowed_ratios=allowed_ratios,
         duration_range=duration_range,
     )
@@ -861,6 +1328,94 @@ def _run_minimax(job: Mapping[str, Any]) -> tuple[Path, str | None]:
     )
 
 
+def _run_minimax_video(job: Mapping[str, Any]) -> tuple[Path, str]:
+    token = _credential("MINIMAX_API_KEY")
+    model = os.environ.get("MINIMAX_VIDEO_MODEL", "")
+    references = _reference_paths(job)
+    reference_roles = (
+        _binding_roles(job, allowed=MINIMAX_VIDEO_ROLES, provider="MiniMax")
+        if references
+        else []
+    )
+    reference_urls = _inline_reference_urls(
+        references, reference_roles, allowed=MINIMAX_VIDEO_ROLES, provider="MiniMax"
+    )
+    ratios, resolutions, duration_range = _minimax_video_runtime_profile()
+    body = compile_minimax_h3_payload(
+        job,
+        model=model,
+        reference_urls=reference_urls,
+        reference_roles=reference_roles,
+        allowed_ratios=ratios,
+        allowed_resolutions=resolutions,
+        duration_range=duration_range,
+    )
+    base = _base_url("MINIMAX_VIDEO_BASE_URL", MINIMAX_VIDEO_BASE_URL)
+    created, _ = _request_json(
+        f"{base}/video_generation",
+        provider="minimax-h3",
+        body=body,
+        token=token,
+    )
+    task_id = created.get("task_id")
+    if not isinstance(task_id, str) or not task_id:
+        raise AdapterFailure(
+            "MiniMax did not return a task id",
+            code=_provider_code(created) or "missing_task_id",
+        )
+    try:
+        interval = float(os.environ.get("MINIMAX_VIDEO_POLL_INTERVAL", "5"))
+        deadline = time.monotonic() + float(
+            os.environ.get("MINIMAX_VIDEO_TIMEOUT_SECONDS", "1800")
+        )
+    except ValueError as exc:
+        raise AdapterFailure("MiniMax polling configuration is invalid") from exc
+    if interval <= 0 or deadline <= time.monotonic():
+        raise AdapterFailure("MiniMax polling configuration is invalid")
+    while time.monotonic() < deadline:
+        document, _ = _request_json(
+            f"{base}/query/video_generation/"
+            + urllib.parse.quote(task_id, safe=""),
+            provider="minimax-h3",
+            method="GET",
+            token=token,
+        )
+        task = document.get("task")
+        status = task.get("status") if isinstance(task, Mapping) else None
+        if status == "succeeded":
+            content = task.get("content") if isinstance(task, Mapping) else None
+            url = content.get("url") if isinstance(content, Mapping) else None
+            if not isinstance(url, str):
+                raise AdapterFailure(
+                    "MiniMax succeeded without a video URL",
+                    code="missing_video_url",
+                    request_id=task_id,
+                )
+            return _download(
+                job, url, job["outputs"][0], provider="minimax-h3"
+            ), task_id
+        if isinstance(status, str) and status.casefold() in TERMINAL_FAILURES:
+            raise AdapterFailure(
+                "MiniMax video task failed",
+                code="task_" + status.casefold(),
+                request_id=task_id,
+            )
+        if status not in {"queued", "running", "processing", "pending", "in_progress"}:
+            raise AdapterFailure(
+                "MiniMax returned an unknown task status",
+                code="unknown_task_status",
+                request_id=task_id,
+            )
+        time.sleep(interval)
+    raise AdapterFailure(
+        "MiniMax video task polling timed out",
+        category="timeout",
+        code="task_poll_timeout",
+        request_id=task_id,
+        retryable=True,
+    )
+
+
 def _selftest() -> None:
     image = {
         "modality": "image", "prompt": "portrait", "references": [],
@@ -884,8 +1439,30 @@ def _selftest() -> None:
     )
     if seedance["model"] != "configured-model":
         raise RuntimeError("Seedance model self-test failed")
-    if not seedance["content"][0]["text"].endswith("--ratio 9:16 --dur 5"):
-        raise RuntimeError("Seedance prompt switch self-test failed")
+    if seedance.get("ratio") != "9:16" or seedance.get("duration") != 5:
+        raise RuntimeError("Seedance parameter self-test failed")
+    minimax_video = compile_minimax_h3_payload(
+        {**video, "parameters": {"duration": 6, "ratio": "9:16", "resolution": "768P"}},
+        model="configured-video-model",
+        allowed_ratios={"9:16"},
+        allowed_resolutions={"768P"},
+        duration_range=(4, 15),
+    )
+    if minimax_video["model"] != "configured-video-model":
+        raise RuntimeError("MiniMax video model self-test failed")
+    if minimax_video["duration"] != 6 or minimax_video["resolution"] != "768P":
+        raise RuntimeError("MiniMax video parameter self-test failed")
+    try:
+        compile_minimax_h3_payload(
+            {**video, "parameters": {"duration": 6, "resolution": "768P"}},
+            model="configured-video-model",
+            allowed_resolutions={"768P"},
+            duration_range=(4, 15),
+        )
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("MiniMax text-to-video without a ratio was accepted")
     compiled_music = compile_minimax_music_payload(music)
     if compiled_music["model"] != MINIMAX_MUSIC_MODEL:
         raise RuntimeError("MiniMax model self-test failed")
@@ -908,16 +1485,21 @@ def _selftest() -> None:
             invalid_reference,
             model="configured-model",
             reference_urls=["asset://asset-example-clip"],
+            reference_roles=["reference_image"],
         )
     except ValueError:
         pass
     else:
-        raise AssertionError("non-image Seedance reference was accepted")
+        raise AssertionError("mismatched Seedance reference role was accepted")
 
 
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("provider", nargs="?", choices=("seedance", "gpt-image-2", "minimax-music"))
+    parser.add_argument(
+        "provider",
+        nargs="?",
+        choices=("seedance", "gpt-image-2", "minimax-music", "minimax-h3"),
+    )
     parser.add_argument("--selftest", action="store_true")
     args = parser.parse_args()
     if args.selftest:
@@ -929,7 +1511,12 @@ def main() -> int:
         job = json.load(sys.stdin.buffer)
         if not isinstance(job, Mapping):
             raise ValueError("adapter input must be an object")
-        runners = {"seedance": _run_seedance, "gpt-image-2": _run_openai, "minimax-music": _run_minimax}
+        runners = {
+            "seedance": _run_seedance,
+            "gpt-image-2": _run_openai,
+            "minimax-music": _run_minimax,
+            "minimax-h3": _run_minimax_video,
+        }
         path, provider_job_id = runners[args.provider](job)
         response: dict[str, Any] = {
             "outputs": [{"target": job["outputs"][0], "source": str(path)}]