zenstory-ai/drama-skills / skills/short-drama-produce
short-drama-produce
Verified在创作者明确确认后,单条或按批调用已配置接口执行图片、视频、配音或配乐生成并保存产物与运行记录。用于“生成图/视频/配音/音乐”“开始跑图/跑视频”“把定稿提示词送去生成”;不写提示词、不改台词,不把预览或定稿当扣费确认。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| agents/openai.yaml | config | 292 B |
| references/adapter-contract.md | markdown | 9.0 KB |
| references/builtin-providers.md | markdown | 6.6 KB |
| scripts/production_tool.pyexecutable | script | 137.2 KB |
| scripts/provider_adapters.pyexecutable | script | 79.6 KB |
scripts/provider_adapters.py
View on GitHub#!/usr/bin/env python3
"""Stdlib-only production adapters for supported media providers.
The public ``compile_*`` functions are deterministic and perform no I/O. The
CLI reads the confirmed production job from stdin and writes only the adapter
contract JSON to stdout after a provider result has been saved to a temporary
regular file.
"""
from __future__ import annotations
import argparse
import base64
import binascii
import json
import math
import mimetypes
import os
import re
import secrets
import socket
import stat
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
from collections.abc import Collection, Mapping, Sequence
from pathlib import Path
from typing import Any
OPENAI_MODEL = "gpt-image-2"
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
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 = {
"first_frame": "image_url",
"last_frame": "image_url",
"reference_image": "image_url",
"reference_video": "video_url",
"reference_audio": "audio_url",
}
# One opening frame and one closing frame, because each names a single position
# in the take. Note what is deliberately absent: the sibling adapter forbids
# mixing frame conditioning with reference conditioning, and that rule belongs
# to that provider's reference, not to this one. Do not carry it across.
SEEDANCE_SINGULAR_ROLES = {"first_frame", "last_frame"}
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_SPEECH_TEXT_LIMIT = 5000
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",
".opus": "audio/ogg",
}
PUBLIC_ERROR_TOKEN_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,199}")
GPT_IMAGE_MIN_PIXELS = 655_360
GPT_IMAGE_MAX_PIXELS = 8_294_400
MINIMUM_PYTHON = (3, 9)
if sys.version_info < MINIMUM_PYTHON:
raise SystemExit("provider_adapters.py requires Python 3.9 or newer")
class AdapterFailure(RuntimeError):
"""A safe-to-report adapter failure without provider response contents."""
def __init__(
self,
message: str,
*,
category: str = "provider_response",
code: str = "adapter_failure",
http_status: int | None = None,
request_id: str | None = None,
retryable: bool = False,
submitted: bool | None = None,
detail: str | None = None,
) -> None:
super().__init__(message)
self.category = category
self.code = _safe_token(code) or "adapter_failure"
self.http_status = http_status
self.request_id = _safe_token(request_id)
self.retryable = retryable
self.submitted = submitted
self.detail = _safe_detail(detail)
def public(self, provider: str) -> dict[str, Any]:
result: dict[str, Any] = {
"provider": provider,
"category": self.category,
"code": self.code,
"retryable": self.retryable,
}
if self.http_status is not None:
result["http_status"] = self.http_status
if self.request_id is not None:
result["request_id"] = self.request_id
if self.submitted is not None:
result["submitted"] = self.submitted
if self.detail is not None:
result["detail"] = self.detail
return result
AdapterError = AdapterFailure
MINIMAX_H3_REFERENCE_LIMITS = {
"image_url": 9,
"video_url": 3,
"audio_url": 3,
}
def _safe_detail(value: object) -> str | None:
if not isinstance(value, str):
return None
collapsed = " ".join(value.split())
if not collapsed or len(collapsed) > 160:
return None
if any(ord(ch) < 32 or ord(ch) == 127 for ch in collapsed):
return None
if re.search(
r"://|(?<![\w.])/(?:Users|home|private|var|tmp)/|\b[A-Za-z]:[\\/]"
r"|\bbearer\s+\S+|\bsk-[A-Za-z0-9_-]{8,}"
r"|\b(?:authorization|password|passwd|secret|api[_-]?key|access[_-]?token)\s*[:=]",
collapsed,
re.IGNORECASE,
):
return None
return collapsed
def _safe_public_id(value: object) -> str | None:
if isinstance(value, str) and PUBLIC_ERROR_TOKEN_RE.fullmatch(value) is not None:
return value
return None
def _safe_token(value: object) -> str | None:
if isinstance(value, str) and PUBLIC_ERROR_TOKEN_RE.fullmatch(value) is not None:
return value
if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
return str(value)
return None
def _request_id(headers: Mapping[str, Any]) -> str | None:
folded = {str(key).casefold(): value for key, value in headers.items()}
for name in ("x-request-id", "x-tt-logid", "x-trace-id", "trace-id"):
value = _safe_token(folded.get(name))
if value is not None:
return value
return None
def _provider_code(document: object) -> str | None:
if not isinstance(document, Mapping):
return None
error = document.get("error")
if isinstance(error, Mapping):
value = _safe_token(error.get("code"))
if value is not None:
return value
base_resp = document.get("base_resp")
if isinstance(base_resp, Mapping):
value = _safe_token(base_resp.get("status_code"))
if value not in {None, "0"}:
return value
return _safe_token(document.get("code"))
def _http_failure(provider: str, error: urllib.error.HTTPError) -> AdapterFailure:
status = error.code
try:
raw = error.read(MAX_ERROR_BODY_BYTES + 1)
document = json.loads(raw) if len(raw) <= MAX_ERROR_BODY_BYTES else None
except (OSError, UnicodeError, json.JSONDecodeError):
document = None
if status == 401:
category = "authentication"
elif status == 403:
category = "permission"
elif status == 429:
category = "rate_limit"
elif 500 <= status <= 599:
category = "server"
elif 400 <= status <= 499:
category = "invalid_request"
else:
category = "provider_response"
return AdapterFailure(
f"{provider} HTTP request failed",
category=category,
code=_provider_code(document) or f"http_{status}",
http_status=status,
request_id=_request_id(
dict(error.headers.items()) if error.headers is not None else {}
),
retryable=status == 429 or 500 <= status <= 599,
)
def _require_job(
job: Mapping[str, Any], modality: str, *, max_outputs: int = 1
) -> tuple[str, dict[str, Any]]:
if not isinstance(job, Mapping) or job.get("modality") != modality:
raise ValueError(f"adapter requires a {modality} job")
prompt = job.get("prompt")
if not isinstance(prompt, str) or not prompt.strip():
raise ValueError("job prompt must be non-empty")
parameters = job.get("parameters", {})
if not isinstance(parameters, Mapping):
raise ValueError("job parameters must be an object")
outputs = job.get("outputs")
if not isinstance(outputs, list) or not outputs or any(
not isinstance(item, str) for item in outputs
):
raise ValueError("provider adapter requires at least one output")
if max_outputs == 1 and len(outputs) != 1:
raise ValueError("provider adapter requires exactly one output")
if len(outputs) > max_outputs:
raise ValueError(f"provider adapter accepts at most {max_outputs} outputs")
return prompt, dict(parameters)
ZH_ROLE_LABELS = {
"first_frame": "首帧",
"last_frame": "尾帧",
"start_frame": "首帧",
"end_frame": "尾帧",
"reference_image": "参考图",
"reference_video": "参考视频",
"reference_audio": "参考音频",
"identity": "外貌",
"identity_and_look": "外貌与造型",
"look_state": "造型状态",
"look": "造型",
"geography": "空间布局",
"spatial_geography": "空间布局",
"composition": "构图",
"scale": "尺度",
"effect": "效果",
"style": "风格",
"subject": "主体",
"continuity_video": "前序接戏视频",
"actual_tail_frame": "前镜实际尾帧",
}
def _prompt_already_binds_references(
prompt: str,
bindings: Sequence[Mapping[str, Any]],
reference_tokens: Sequence[str],
) -> bool:
if "retention_analysis:" in prompt:
return True
if reference_tokens:
return all(
re.search(rf"{re.escape(token)}(?!\d)", prompt) is not None
for token in reference_tokens
)
count = len(bindings)
return bool(count) and (
all(
re.search(rf"<Picture {index}>(?!\d)", prompt) is not None
for index in range(1, count + 1)
)
or all(
re.search(rf"@图片{index}(?!\d)", prompt) is not None
for index in range(1, count + 1)
)
or all(
re.search(rf"图{index}(?!\d)", prompt) is not None
for index in range(1, count + 1)
)
)
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")
character = binding.get("character")
if character is not None:
if role != "reference_audio" or not isinstance(character, str) or not character.strip():
raise ValueError("reference audio character is invalid")
# The source's explicit speaker wins over the free-form asset label.
label = f"{character.strip()}音色参考"
role_text = role.strip()
values = {
"order": index,
"reference": reference_tokens[index - 1] if reference_tokens else str(index),
"label": label.strip(),
"role": role_text,
"may": ", ".join(item.strip() for item in may_control),
"must": ", ".join(item.strip() for item in must_not_control),
}
if language.startswith("zh"):
zh_values = {
**values,
"role": ZH_ROLE_LABELS.get(role_text, role_text),
}
instructions.append(
f"{zh_reference_prefix} "
+ (
"{reference}({label}),用途:{role}。允许控制:{may}。"
"不得控制:{must}。".format(**zh_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 _prompt_already_binds_references(prompt, bindings, reference_tokens):
return prompt
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:
raise ValueError("unsupported provider parameters: " + ", ".join(sorted(unknown)))
return parameters
def compile_seedance_payload(
job: Mapping[str, Any],
*,
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]:
"""Compile a video production job into the official Seedance task body.
``model`` is deliberately mandatory: callers must obtain it from explicit
runtime configuration rather than assuming any Seedance release.
"""
prompt, parameters = _require_job(job, "video")
if not isinstance(model, str) or not model.strip():
raise ValueError("Seedance model must be explicitly configured")
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",
"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 (duration != -1 and not 1 <= duration <= 30)
):
raise ValueError("Seedance duration must be -1 or an integer from 1 to 30")
if duration is not None and duration != -1:
minimum, maximum = (1, 30) if duration_range is None else duration_range
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 (
not isinstance(ratio, str) or ratio.strip() not in SEEDANCE_RATIOS
):
raise ValueError("Seedance ratio is outside the supported profile")
if ratio is not None:
configured_ratios = (
set(SEEDANCE_RATIOS) if allowed_ratios is None else set(allowed_ratios)
)
if not configured_ratios or not configured_ratios <= SEEDANCE_RATIOS or ratio.strip() not in configured_ratios:
raise ValueError("Seedance ratio is outside the configured model profile")
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] = []
singular_seen: set[str] = set()
for role in reference_roles:
field = SEEDANCE_REFERENCE_ROLES.get(role)
if field is None:
raise ValueError(f"unsupported Seedance reference role: {role}")
if role in SEEDANCE_SINGULAR_ROLES:
if role in singular_seen:
raise ValueError(f"Seedance accepts one {role} reference")
singular_seen.add(role)
# A frame role still occupies a picture slot, so it keeps counting: the
# tokens are positional, and skipping one would point every later
# `@图片N` in the prose at the wrong picture.
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()
expected = {
"image_url": {".png", ".jpg", ".jpeg", ".webp"},
"video_url": {".mp4", ".mov", ".webm"},
"audio_url": {".wav", ".mp3", ".m4a", ".aac", ".flac", ".opus"},
}[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
)
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(
) -> tuple[frozenset[str] | None, tuple[int, int] | None]:
raw_ratios = os.environ.get("SEEDANCE_ALLOWED_RATIOS")
allowed_ratios = (
frozenset(item.strip() for item in raw_ratios.split(",") if item.strip())
if raw_ratios is not None
else None
)
minimum_raw = os.environ.get("SEEDANCE_MIN_DURATION")
maximum_raw = os.environ.get("SEEDANCE_MAX_DURATION")
if (minimum_raw is None) != (maximum_raw is None):
raise AdapterFailure(
"Seedance duration profile is incomplete",
category="configuration",
code="invalid_model_profile",
submitted=False,
detail="SEEDANCE_MIN_DURATION and SEEDANCE_MAX_DURATION must be set together",
)
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(
"Seedance duration profile is invalid",
category="configuration",
code="invalid_model_profile",
submitted=False,
detail="Seedance duration profile must be integer seconds",
) from exc
if allowed_ratios is not None and (
not allowed_ratios or not allowed_ratios <= SEEDANCE_RATIOS
):
raise AdapterFailure(
"Seedance ratio profile is invalid",
category="configuration",
code="invalid_model_profile",
submitted=False,
detail="SEEDANCE_ALLOWED_RATIOS contains unsupported ratios",
)
if duration_range is not None and not (
1 <= duration_range[0] <= duration_range[1] <= 30
):
raise AdapterFailure(
"Seedance duration profile is invalid",
category="configuration",
code="invalid_model_profile",
submitted=False,
detail="Seedance duration profile must be within 1..30 seconds",
)
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")
minimum, maximum = (1, 30) if duration_range is None else duration_range
if not 1 <= minimum <= maximum <= 30 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(MINIMAX_VIDEO_RESOLUTIONS)
if allowed_resolutions is None
else set(allowed_resolutions)
)
if (
not configured_resolutions
or 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(MINIMAX_VIDEO_RATIOS)
if allowed_ratios is None
else set(allowed_ratios)
)
if (
not configured_ratios
or 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]}>")
if all(role not in {"first_frame", "last_frame"} for role in reference_roles):
for field, limit in MINIMAX_H3_REFERENCE_LIMITS.items():
if counters[field] > limit:
detail = (
f"MiniMax H3 accepts at most {limit} {field} reference"
+ ("s" if limit != 1 else "")
)
raise AdapterError(
detail,
category="invalid_request",
code="too_many_references",
retryable=False,
submitted=False,
detail=detail,
)
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(names: Sequence[str], supported: Collection[str]) -> frozenset[str] | None:
chosen_name = next((name for name in names if name in os.environ), None)
if chosen_name is None:
return None
raw = os.environ[chosen_name]
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: {chosen_name}",
category="configuration",
code="invalid_model_profile",
submitted=False,
detail=f"MiniMax video profile is invalid: {chosen_name}",
)
return values
allowed_ratios = _set(
("MINIMAX_VIDEO_ALLOWED_RATIOS", "MINIMAX_VIDEO_RATIOS"),
MINIMAX_VIDEO_RATIOS,
)
allowed_resolutions = _set(
("MINIMAX_VIDEO_ALLOWED_RESOLUTIONS", "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",
submitted=False,
detail="MINIMAX_VIDEO_MIN_DURATION and MINIMAX_VIDEO_MAX_DURATION must be set together",
)
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",
submitted=False,
detail="MiniMax video duration profile must be integer seconds",
) from exc
if duration_range is not None and not (
1 <= duration_range[0] <= duration_range[1] <= 30
):
raise AdapterFailure(
"MiniMax video duration profile is invalid",
category="configuration",
code="invalid_model_profile",
submitted=False,
detail="MiniMax video duration profile must be within 1..30 seconds",
)
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", max_outputs=16)
parameters = _take(
parameters,
{
"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")
width = parameters.pop("width", None)
height = parameters.pop("height", None)
if (width is None) != (height is None) or (width is not None and "size" in parameters):
raise ValueError("use either both width/height or size")
if width is not None:
if not isinstance(width, int) or not isinstance(height, int) or width <= 0 or height <= 0:
raise ValueError("image dimensions must be positive integers")
if width % 16 or height % 16 or not (1 / 3 <= width / height <= 3):
raise ValueError("GPT Image dimensions must be divisible by 16 with ratio between 1:3 and 3:1")
parameters["size"] = f"{width}x{height}"
size = parameters.get("size")
if size != "auto" and size is not None:
if not isinstance(size, str) or "x" not in size:
raise ValueError("GPT Image size is invalid")
try:
parsed_width, parsed_height = (int(part) for part in size.split("x", 1))
except ValueError as exc:
raise ValueError("GPT Image size is invalid") from exc
if (
parsed_width <= 0
or parsed_height <= 0
or parsed_width % 16
or parsed_height % 16
or not (1 / 3 <= parsed_width / parsed_height <= 3)
or parsed_width > 3840
or parsed_height > 3840
or not (
GPT_IMAGE_MIN_PIXELS
<= parsed_width * parsed_height
<= GPT_IMAGE_MAX_PIXELS
)
):
raise ValueError("GPT Image size violates official dimension constraints")
if parameters.get("background") == "transparent":
raise ValueError("GPT Image 2 transparent background is unsupported")
if "background" in parameters and parameters["background"] not in {"auto", "opaque"}:
raise ValueError("GPT Image background is invalid")
if "quality" in parameters and parameters["quality"] not in {"auto", "low", "medium", "high"}:
raise ValueError("GPT Image quality is invalid")
if "moderation" in parameters and parameters["moderation"] not in {"auto", "low"}:
raise ValueError("GPT Image moderation is invalid")
formats = {".png": "png", ".jpg": "jpeg", ".jpeg": "jpeg", ".webp": "webp"}
output_formats: set[str] = set()
for target in job["outputs"]:
suffix = Path(target).suffix.casefold()
if suffix not in formats:
raise ValueError("unsupported GPT Image output extension")
output_formats.add(formats[suffix])
if len(output_formats) != 1:
raise ValueError("GPT Image outputs in one job must share an output format")
output_format = next(iter(output_formats))
references = job.get("references", [])
if not isinstance(references, list) or len(references) > 16:
raise ValueError("GPT Image accepts at most sixteen references")
if any(
not isinstance(reference, str)
or Path(reference).suffix.casefold() not in {".png", ".jpg", ".jpeg", ".webp"}
for reference in references
):
raise ValueError("GPT Image references must be supported image files")
return {
"model": OPENAI_MODEL,
"prompt": prompt,
"n": len(job["outputs"]),
"output_format": output_format,
**parameters,
}
MINIMAX_SPEECH_EMOTIONS = {
"happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral",
}
def compile_minimax_speech_payload(job: Mapping[str, Any]) -> dict[str, Any]:
"""Compile a tts job into the official MiniMax speech JSON body.
The voice catalogue is deliberately not enumerated here. Which preset voices
an account can reach depends on the model and the account, no published list
is authoritative for both, and a list frozen into this file would either
refuse a voice that works or vouch for one that does not. The document owns
the value and a reviewer reads it; the adapter only checks its shape.
"""
text, parameters = _require_job(job, "tts")
parameters = _take(
parameters,
{"model", "voice_id", "speed", "vol", "pitch", "emotion",
"sample_rate", "bitrate", "format"},
)
model = parameters.pop("model", "")
if not isinstance(model, str) or not model.strip():
raise ValueError("MiniMax speech model must be explicitly configured")
voice_id = parameters.pop("voice_id", "")
if not isinstance(voice_id, str) or not voice_id.strip() or voice_id != voice_id.strip():
raise ValueError("MiniMax speech requires a confirmed voice_id")
if len(text) > MINIMAX_SPEECH_TEXT_LIMIT:
raise ValueError("MiniMax speech text exceeds the provider limit")
target_format = Path(job["outputs"][0]).suffix.casefold().lstrip(".")
requested_format = parameters.pop("format", target_format)
if requested_format != target_format or requested_format not in {"mp3", "wav"}:
raise ValueError("MiniMax output format must match a supported target extension")
sample_rate = parameters.pop("sample_rate", 32000)
bitrate = parameters.pop("bitrate", 128000)
if sample_rate not in {16000, 24000, 32000, 44100}:
raise ValueError("unsupported MiniMax sample rate")
if bitrate not in {32000, 64000, 128000, 256000}:
raise ValueError("unsupported MiniMax bitrate")
voice_setting: dict[str, Any] = {"voice_id": voice_id}
emotion = parameters.pop("emotion", None)
if emotion is not None:
if emotion not in MINIMAX_SPEECH_EMOTIONS:
raise ValueError("unsupported MiniMax speech emotion")
voice_setting["emotion"] = emotion
for name, low, high in (("speed", 0.5, 2.0), ("vol", 0.1, 10.0)):
value = parameters.pop(name, None)
if value is None:
continue
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise ValueError(f"MiniMax speech {name} must be a number")
if not low <= float(value) <= high:
raise ValueError(f"MiniMax speech {name} is outside the supported range")
voice_setting[name] = float(value)
pitch = parameters.pop("pitch", None)
if pitch is not None:
if isinstance(pitch, bool) or not isinstance(pitch, int) or not -12 <= pitch <= 12:
raise ValueError("MiniMax speech pitch is outside the supported range")
voice_setting["pitch"] = pitch
return {
"model": model.strip(),
"text": text,
"stream": False,
"output_format": "hex",
"voice_setting": voice_setting,
"audio_setting": {
"sample_rate": sample_rate,
"bitrate": bitrate,
"format": requested_format,
},
}
def compile_minimax_music_payload(job: Mapping[str, Any]) -> dict[str, Any]:
"""Compile an audio job into the official MiniMax Music 3.0 JSON body."""
prompt, parameters = _require_job(job, "music")
parameters = _take(
parameters,
{"lyrics", "sample_rate", "bitrate", "format", "lyrics_optimizer", "is_instrumental"},
)
target_format = Path(job["outputs"][0]).suffix.casefold().lstrip(".")
requested_format = parameters.pop("format", target_format)
if requested_format != target_format or requested_format not in {"mp3", "wav"}:
raise ValueError("MiniMax output format must match a supported target extension")
lyrics = parameters.pop("lyrics", None)
instrumental = parameters.pop("is_instrumental", False)
optimizer = parameters.pop("lyrics_optimizer", False)
if not isinstance(instrumental, bool) or not isinstance(optimizer, bool):
raise ValueError("MiniMax boolean parameters must be booleans")
if optimizer:
raise ValueError("MiniMax lyrics_optimizer is forbidden for confirmed production")
if instrumental and lyrics not in {None, ""}:
raise ValueError("MiniMax instrumental music must not carry lyrics")
if not instrumental and (not isinstance(lyrics, str) or not lyrics.strip()):
raise ValueError("MiniMax vocal music requires confirmed lyrics")
if len(prompt) > 2000 or (isinstance(lyrics, str) and len(lyrics) > 3500):
raise ValueError("MiniMax prompt or lyrics exceeds the provider limit")
sample_rate = parameters.pop("sample_rate", 44100)
bitrate = parameters.pop("bitrate", 256000)
if sample_rate not in {16000, 24000, 32000, 44100}:
raise ValueError("unsupported MiniMax sample rate")
if bitrate not in {32000, 64000, 128000, 256000}:
raise ValueError("unsupported MiniMax bitrate")
body: dict[str, Any] = {
"model": MINIMAX_MUSIC_MODEL,
"prompt": prompt,
"stream": False,
"output_format": "hex",
"audio_setting": {
"sample_rate": sample_rate,
"bitrate": bitrate,
"format": requested_format,
},
"lyrics_optimizer": False,
"is_instrumental": instrumental,
}
if lyrics is not None:
if not isinstance(lyrics, str):
raise ValueError("MiniMax lyrics must be a string")
body["lyrics"] = lyrics
return body
def _base_url(env_name: str, default: str) -> str:
value = os.environ.get(env_name, default).rstrip("/")
parsed = urllib.parse.urlparse(value)
if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password:
raise AdapterFailure(
"provider base URL is invalid",
category="configuration",
code="invalid_base_url",
submitted=False,
detail=f"{env_name} must be an HTTPS base URL without credentials",
)
return value
def _credential(name: str) -> str:
value = os.environ.get(name)
if not value:
raise AdapterFailure(
"provider credential is not configured",
category="configuration",
code="missing_credential",
submitted=False,
detail=f"{name} is not configured",
)
return value
def _is_timeout_error(exc: BaseException) -> bool:
return isinstance(exc, (TimeoutError, socket.timeout)) or (
isinstance(exc, urllib.error.URLError)
and isinstance(getattr(exc, "reason", None), (TimeoutError, socket.timeout))
)
def _request_json(
url: str,
*,
provider: str,
method: str = "POST",
body: Mapping[str, Any] | None = None,
token: str,
) -> tuple[dict[str, Any], Mapping[str, str]]:
data = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, method=method) # noqa: S310 # HTTPS enforced by _base_url
request.add_header("Authorization", f"Bearer {token}")
if body is not None:
request.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(request, timeout=180) as response: # noqa: S310 # HTTPS enforced by _base_url
raw = response.read(MAX_JSON_RESPONSE + 1)
headers = dict(response.headers.items())
except urllib.error.HTTPError as exc:
raise _http_failure(provider, exc) from exc
except (TimeoutError, socket.timeout, urllib.error.URLError, OSError) as exc:
if _is_timeout_error(exc):
raise AdapterFailure(
f"{provider} HTTP request timed out",
category="timeout",
code="request_timeout",
retryable=True,
) from exc
raise AdapterFailure(
f"{provider} HTTP request failed",
category="network",
code="network_error",
retryable=True,
) from exc
if len(raw) > MAX_JSON_RESPONSE:
raise AdapterFailure(
f"{provider} response is too large", code="response_too_large"
)
try:
document = json.loads(raw)
except (UnicodeError, json.JSONDecodeError) as exc:
raise AdapterFailure(
f"{provider} returned invalid JSON", code="invalid_json"
) from exc
if not isinstance(document, dict):
raise AdapterFailure(
f"{provider} returned an invalid response", code="invalid_response"
)
return document, headers
def _read_reference(path: Path) -> bytes:
try:
before = path.lstat()
if stat.S_ISLNK(before.st_mode) or not stat.S_ISREG(before.st_mode):
raise ValueError("reference is not a regular file")
if before.st_size > MAX_REFERENCE_BYTES:
raise ValueError("reference exceeds the provider input size limit")
# 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)
if (
not stat.S_ISREG(opened.st_mode)
or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino)
):
raise ValueError("reference changed while opening")
chunks: list[bytes] = []
size = 0
while chunk := os.read(descriptor, 1024 * 1024):
size += len(chunk)
if size > MAX_REFERENCE_BYTES:
raise ValueError("reference exceeds the provider input size limit")
chunks.append(chunk)
return b"".join(chunks)
finally:
os.close(descriptor)
except OSError as exc:
raise AdapterFailure(
"could not read reference file",
category="invalid_request",
code="unreadable_reference",
submitted=False,
detail="could not read reference file",
) from exc
def _multipart(fields: Mapping[str, Any], paths: Sequence[Path]) -> tuple[bytes, str]:
boundary = "short-drama-" + secrets.token_hex(16)
chunks: list[bytes] = []
for name, value in fields.items():
chunks.extend(
[
f"--{boundary}\r\n".encode(),
f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode(),
str(value).lower().encode() if isinstance(value, bool) else str(value).encode("utf-8"),
b"\r\n",
]
)
image_limit = INLINE_REFERENCE_LIMITS["image_url"]
for path in paths:
content = _read_reference(path)
if not content:
raise AdapterFailure(
"OpenAI reference image is empty",
category="invalid_request",
code="empty_reference",
submitted=False,
detail="reference image is empty",
)
if len(content) > image_limit:
raise AdapterFailure(
f"OpenAI reference image exceeds the {image_limit // (1024 * 1024)}MB limit",
category="invalid_request",
code="reference_too_large",
submitted=False,
detail=f"reference image exceeds the {image_limit // (1024 * 1024)}MB limit",
)
try:
_validate_media_content(path.name, content)
except AdapterFailure as exc:
raise AdapterFailure(
str(exc),
category="invalid_request",
code="invalid_reference_media",
submitted=False,
detail="reference file bytes do not match its file extension",
) from exc
media_type = (
INLINE_REFERENCE_MIME.get(path.suffix.casefold())
or mimetypes.guess_type(path.name)[0]
or "application/octet-stream"
)
safe_filename = re.sub(r'[\x00-\x1f\x7f"\\]', "_", path.name) or "reference"
chunks.extend(
[
f"--{boundary}\r\n".encode(),
f'Content-Disposition: form-data; name="image[]"; filename="{safe_filename}"\r\n'.encode(),
f"Content-Type: {media_type}\r\n\r\n".encode(),
content,
b"\r\n",
]
)
chunks.append(f"--{boundary}--\r\n".encode())
encoded = b"".join(chunks)
if len(encoded) > MAX_MULTIPART_BYTES:
raise AdapterFailure(
"multipart provider input exceeds the total size limit",
category="invalid_request",
code="multipart_too_large",
submitted=False,
detail="multipart provider input exceeds the total size limit",
)
return encoded, f"multipart/form-data; boundary={boundary}"
def _reference_paths(job: Mapping[str, Any]) -> list[Path]:
raw_root = job.get("project_root")
if not isinstance(raw_root, str) or not Path(raw_root).is_absolute():
raise ValueError("project_root is invalid")
root = Path(raw_root).resolve()
if not root.is_dir():
raise ValueError("project_root is invalid")
result: list[Path] = []
for reference in job.get("references", []):
if not isinstance(reference, str):
raise ValueError("reference path is invalid")
path = (root / reference).resolve()
try:
path.relative_to(root)
except ValueError as exc:
raise ValueError("reference escapes project root") from exc
if not path.is_file() or path.is_symlink():
raise ValueError("reference is not a regular file")
result.append(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",
submitted=False,
detail=f"{provider} references require matching reference_bindings",
)
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",
submitted=False,
detail=f"{provider} reference role is unsupported",
)
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",
submitted=False,
detail=f"{provider} {role} does not accept a {suffix or 'suffixless'} file",
)
try:
content = path.read_bytes()
except OSError as exc:
raise AdapterFailure(
f"{provider} could not read a project reference",
category="configuration",
code="unreadable_reference",
submitted=False,
detail=f"{provider} could not read a project reference",
) from exc
if not content:
raise AdapterFailure(
f"{provider} project reference is empty",
category="configuration",
code="empty_reference",
submitted=False,
detail=f"{provider} project reference is empty",
)
# The bytes have to be the media type the extension claims, or the
# provider rejects a request this adapter said was well formed.
try:
_validate_media_content(path.name, content)
except AdapterFailure as exc:
raise AdapterFailure(
str(exc),
category="configuration",
code=(
"invalid_reference_media"
if exc.code == "adapter_failure"
else exc.code
),
submitted=False,
detail="reference file bytes do not match its file extension",
) from exc
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",
submitted=False,
detail=f"{provider} reference exceeds the {limit // (1024 * 1024)}MB inline limit",
)
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",
submitted=False,
detail=f"{provider} inline references exceed the 64MB request body limit",
)
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 = {
".png": content.startswith(b"\x89PNG\r\n\x1a\n"),
".jpg": content.startswith(b"\xff\xd8\xff"),
".jpeg": content.startswith(b"\xff\xd8\xff"),
".webp": len(content) >= 12
and content.startswith(b"RIFF")
and content[8:12] == b"WEBP",
".mp3": content.startswith(b"ID3")
or (
len(content) >= 2
and content[0] == 0xFF
and content[1] & 0xE0 == 0xE0
),
".wav": len(content) >= 12
and content.startswith(b"RIFF")
and content[8:12] == b"WAVE",
".flac": content.startswith(b"fLaC"),
".m4a": len(content) >= 8 and content[4:8] == b"ftyp",
".aac": content.startswith(b"ID3")
or (
len(content) >= 2
and content[0] == 0xFF
and (content[1] & 0xF6) == 0xF0
),
".opus": content.startswith(b"OggS") and b"OpusHead" in content[:64],
".mp4": len(content) >= 12 and content[4:8] == b"ftyp",
".mov": len(content) >= 8
and content[4:8]
in {b"ftyp", b"moov", b"mdat", b"wide", b"free", b"skip", b"pnot"},
".webm": content.startswith(b"\x1a\x45\xdf\xa3"),
}
if not signatures.get(suffix, False):
raise AdapterFailure("provider output does not match the target media type")
def _output_root(job: Mapping[str, Any]) -> Path:
raw = job.get("output_root")
if not isinstance(raw, str):
raise ValueError("output_root is invalid")
root = Path(raw)
if not root.is_absolute():
raise ValueError("output_root is invalid")
try:
details = root.lstat()
except OSError as exc:
raise ValueError("output_root is missing") from exc
if stat.S_ISLNK(details.st_mode) or not stat.S_ISDIR(details.st_mode):
raise ValueError("output_root is unsafe")
return root
def _temporary_output(
job: Mapping[str, Any], target: str, content: bytes, *, index: int | None = None
) -> Path:
if not content or len(content) > MAX_OUTPUT_BYTES:
raise AdapterFailure("provider output is too large")
_validate_media_content(target, content)
stem = "result" if index is None else f"result-{index}"
path = _output_root(job) / (stem + Path(target).suffix.casefold())
with path.open("xb") as handle:
handle.write(content)
return path
def _download(
job: Mapping[str, Any],
url: str,
target: str,
*,
provider: str = "seedance",
) -> Path:
parsed = urllib.parse.urlparse(url)
if parsed.scheme != "https" or not parsed.netloc:
raise AdapterFailure("provider output URL is invalid")
path = _output_root(job) / ("result" + Path(target).suffix.casefold())
size = 0
try:
with urllib.request.urlopen(url, timeout=180) as response, path.open("xb") as handle: # noqa: S310 # HTTPS checked above
while chunk := response.read(1024 * 1024):
size += len(chunk)
if size > MAX_OUTPUT_BYTES:
raise AdapterFailure("provider output is too large")
handle.write(chunk)
except AdapterFailure:
path.unlink(missing_ok=True)
raise
except urllib.error.HTTPError as exc:
path.unlink(missing_ok=True)
raise _http_failure(provider, exc) from exc
except (TimeoutError, socket.timeout, urllib.error.URLError, OSError) as exc:
path.unlink(missing_ok=True)
if _is_timeout_error(exc):
raise AdapterFailure(
"provider output download timed out",
category="timeout",
code="download_timeout",
retryable=True,
) from exc
raise AdapterFailure(
"provider output download failed",
category="network",
code="download_failed",
retryable=True,
) from exc
if size == 0:
raise AdapterFailure("provider output is empty")
with path.open("rb") as handle:
_validate_media_content(target, handle.read(64))
return path
def _record_handle(job: Mapping[str, Any], provider_job_id: str) -> None:
"""Write the provider task id where the caller can find it after a crash.
A video task is billed at submission. Everything after that — polling,
downloading — can be interrupted, and without this the caller is left with a
live, already-paid task it has no id for. Written before the first poll, and
deliberately best-effort: failing to record the handle must not fail a task
that was submitted successfully.
"""
destination = job.get("handle_path")
if not isinstance(destination, str) or not destination:
return
try:
path = Path(destination)
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
temporary.write_text(
json.dumps({"provider_job_id": provider_job_id}, ensure_ascii=True),
encoding="utf-8",
)
temporary.replace(path)
except OSError:
return
def _collect_target(job: Mapping[str, Any]) -> str | None:
value = job.get("collect_provider_job_id")
if value is None or value == "":
return None
token = _safe_public_id(value)
if token is None:
raise ValueError("collect_provider_job_id is invalid")
return token
def _polling_config(
interval_env: str,
timeout_env: str,
*,
provider: str,
) -> tuple[float, float]:
try:
interval = float(os.environ.get(interval_env, "5"))
timeout_seconds = float(os.environ.get(timeout_env, "1800"))
except ValueError as exc:
raise AdapterFailure(
f"{provider} polling configuration is invalid",
category="configuration",
code="invalid_polling_config",
submitted=False,
detail=f"{interval_env} and {timeout_env} must be positive numbers",
) from exc
if (
not math.isfinite(interval)
or interval <= 0
or not math.isfinite(timeout_seconds)
or timeout_seconds <= 0
):
raise AdapterFailure(
f"{provider} polling configuration is invalid",
category="configuration",
code="invalid_polling_config",
submitted=False,
detail=f"{interval_env} and {timeout_env} must be positive numbers",
)
return interval, timeout_seconds
def _run_seedance(job: Mapping[str, Any]) -> tuple[Path, str]:
token = _credential("ARK_API_KEY")
base = _base_url("SEEDANCE_BASE_URL", SEEDANCE_BASE_URL)
interval, timeout_seconds = _polling_config(
"SEEDANCE_POLL_INTERVAL",
"SEEDANCE_TIMEOUT_SECONDS",
provider="Seedance",
)
collecting = _collect_target(job)
if collecting is not None:
return _poll_seedance(
job,
base=base,
token=token,
task_id=collecting,
interval=interval,
timeout_seconds=timeout_seconds,
)
model = os.environ.get("SEEDANCE_MODEL", "")
references = _reference_paths(job)
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,
)
created, _ = _request_json(
f"{base}/contents/generations/tasks",
provider="seedance",
body=body,
token=token,
)
task_id = _safe_public_id(created.get("id"))
if task_id is None:
raise AdapterFailure(
"Seedance did not return a task id", code="missing_task_id"
)
# Billed from here on. Record the id before the first poll.
_record_handle(job, task_id)
return _poll_seedance(
job,
base=base,
token=token,
task_id=task_id,
interval=interval,
timeout_seconds=timeout_seconds,
)
def _poll_seedance(
job: Mapping[str, Any],
*,
base: str,
token: str,
task_id: str,
interval: float | None = None,
timeout_seconds: float | None = None,
) -> tuple[Path, str]:
if interval is None or timeout_seconds is None:
interval, timeout_seconds = _polling_config(
"SEEDANCE_POLL_INTERVAL",
"SEEDANCE_TIMEOUT_SECONDS",
provider="Seedance",
)
deadline = time.monotonic() + timeout_seconds
while time.monotonic() < deadline:
status_doc, _ = _request_json(
f"{base}/contents/generations/tasks/{urllib.parse.quote(task_id, safe='')}",
provider="seedance",
method="GET",
token=token,
)
status = status_doc.get("status")
if status == "succeeded":
content = status_doc.get("content")
url = content.get("video_url") if isinstance(content, Mapping) else None
if not isinstance(url, str):
raise AdapterFailure(
"Seedance succeeded without a video URL",
code="missing_video_url",
request_id=task_id,
)
return _download(
job,
url,
job["outputs"][0],
provider="seedance",
), task_id
if isinstance(status, str) and status.casefold() in TERMINAL_FAILURES:
raise AdapterFailure(
"Seedance task failed",
code="task_" + status.casefold(),
request_id=task_id,
)
if status not in {"queued", "in_progress", "running", "processing", "pending"}:
raise AdapterFailure(
"Seedance returned an unknown task status",
code="unknown_task_status",
request_id=task_id,
)
time.sleep(interval)
raise AdapterFailure(
"Seedance task polling timed out",
category="timeout",
code="task_poll_timeout",
request_id=task_id,
retryable=True,
)
def _run_openai(job: Mapping[str, Any]) -> tuple[Path | list[Path], str | None]:
if _collect_target(job) is not None:
raise AdapterFailure(
"gpt-image-2 uses synchronous generation and cannot collect a prior task",
category="invalid_request",
code="collect_not_supported",
submitted=False,
detail="gpt-image-2 does not support collect",
)
token = _credential("OPENAI_API_KEY")
body = compile_gpt_image_2_payload(job)
base = _base_url("OPENAI_BASE_URL", OPENAI_BASE_URL)
references = _reference_paths(job)
if references:
encoded, content_type = _multipart(body, references)
request = urllib.request.Request(f"{base}/images/edits", data=encoded, method="POST") # noqa: S310 # HTTPS enforced by _base_url
request.add_header("Authorization", f"Bearer {token}")
request.add_header("Content-Type", content_type)
try:
with urllib.request.urlopen(request, timeout=300) as response: # noqa: S310 # HTTPS enforced by _base_url
raw = response.read(MAX_JSON_RESPONSE + 1)
request_id = _request_id(dict(response.headers.items()))
except urllib.error.HTTPError as exc:
raise _http_failure("gpt-image-2", exc) from exc
except (TimeoutError, socket.timeout, urllib.error.URLError, OSError) as exc:
if _is_timeout_error(exc):
raise AdapterFailure(
"OpenAI HTTP request timed out",
category="timeout",
code="request_timeout",
retryable=True,
) from exc
raise AdapterFailure(
"OpenAI HTTP request failed",
category="network",
code="network_error",
retryable=True,
) from exc
if len(raw) > MAX_JSON_RESPONSE:
raise AdapterFailure(
"OpenAI response is too large",
code="response_too_large",
request_id=request_id,
)
try:
result = json.loads(raw)
except (UnicodeError, json.JSONDecodeError) as exc:
raise AdapterFailure(
"OpenAI returned invalid JSON",
code="invalid_json",
request_id=request_id,
) from exc
else:
result, headers = _request_json(
f"{base}/images/generations",
provider="gpt-image-2",
body=body,
token=token,
)
request_id = _request_id(headers)
targets = job["outputs"]
expected_count = len(targets)
data = result.get("data") if isinstance(result, Mapping) else None
if (
not isinstance(data, list)
or len(data) != expected_count
or any(
not isinstance(item, Mapping) or not isinstance(item.get("b64_json"), str)
for item in data
)
):
raise AdapterFailure(
"OpenAI did not return the requested images",
code="missing_image",
request_id=request_id,
)
decoded_images: list[bytes] = []
for item in data:
try:
decoded_images.append(base64.b64decode(item["b64_json"], validate=True))
except (ValueError, binascii.Error) as exc:
raise AdapterFailure(
"OpenAI returned invalid image data",
code="invalid_image_data",
request_id=request_id,
) from exc
if expected_count == 1:
return _temporary_output(job, targets[0], decoded_images[0]), request_id
return (
[
_temporary_output(job, target, content, index=idx)
for idx, (target, content) in enumerate(zip(targets, decoded_images), 1)
],
request_id,
)
def _run_minimax(job: Mapping[str, Any]) -> tuple[Path, str | None]:
if _collect_target(job) is not None:
raise AdapterFailure(
"minimax-music uses synchronous generation and cannot collect a prior task",
category="invalid_request",
code="collect_not_supported",
submitted=False,
detail="minimax-music does not support collect",
)
token = _credential("MINIMAX_API_KEY")
body = compile_minimax_music_payload(job)
base = _base_url("MINIMAX_BASE_URL", MINIMAX_BASE_URL)
result, _ = _request_json(
f"{base}/music_generation",
provider="minimax-music",
body=body,
token=token,
)
base_resp = result.get("base_resp")
if not isinstance(base_resp, Mapping) or base_resp.get("status_code") != 0:
raise AdapterFailure(
"MiniMax music generation failed",
code=_provider_code(result) or "generation_failed",
request_id=_safe_token(result.get("trace_id")),
)
data = result.get("data")
audio = data.get("audio") if isinstance(data, Mapping) else None
if not isinstance(data, Mapping) or data.get("status") != 2 or not isinstance(audio, str):
raise AdapterFailure(
"MiniMax did not return audio data",
code="missing_audio",
request_id=_safe_token(result.get("trace_id")),
)
try:
content = bytes.fromhex(audio)
except ValueError as exc:
raise AdapterFailure("MiniMax returned invalid audio data") from exc
if not content:
raise AdapterFailure("MiniMax returned empty audio data")
trace_id = _safe_public_id(result.get("trace_id"))
return (
_temporary_output(job, job["outputs"][0], content),
trace_id,
)
def _run_minimax_speech(job: Mapping[str, Any]) -> tuple[Path, str | None]:
if _collect_target(job) is not None:
raise AdapterFailure(
"minimax-speech uses synchronous generation and cannot collect a prior task",
category="invalid_request",
code="collect_not_supported",
submitted=False,
detail="minimax-speech does not support collect",
)
token = _credential("MINIMAX_API_KEY")
body = compile_minimax_speech_payload(job)
base = _base_url("MINIMAX_BASE_URL", MINIMAX_BASE_URL)
result, _ = _request_json(
f"{base}/t2a_v2",
provider="minimax-speech",
body=body,
token=token,
)
base_resp = result.get("base_resp")
if not isinstance(base_resp, Mapping) or base_resp.get("status_code") != 0:
raise AdapterFailure(
"MiniMax speech synthesis failed",
code=_provider_code(result) or "generation_failed",
request_id=_safe_token(result.get("trace_id")),
)
data = result.get("data")
audio = data.get("audio") if isinstance(data, Mapping) else None
if not isinstance(audio, str) or not audio:
raise AdapterFailure(
"MiniMax did not return audio data",
code="missing_audio",
request_id=_safe_token(result.get("trace_id")),
)
try:
content = bytes.fromhex(audio)
except ValueError as exc:
raise AdapterFailure("MiniMax returned invalid audio data") from exc
if not content:
raise AdapterFailure("MiniMax returned empty audio data")
trace_id = _safe_public_id(result.get("trace_id"))
return (
_temporary_output(job, job["outputs"][0], content),
trace_id,
)
def _run_minimax_video(job: Mapping[str, Any]) -> tuple[Path, str]:
token = _credential("MINIMAX_API_KEY")
base = _base_url("MINIMAX_VIDEO_BASE_URL", MINIMAX_VIDEO_BASE_URL)
interval, timeout_seconds = _polling_config(
"MINIMAX_VIDEO_POLL_INTERVAL",
"MINIMAX_VIDEO_TIMEOUT_SECONDS",
provider="MiniMax",
)
collecting = _collect_target(job)
if collecting is not None:
return _poll_minimax_video(
job,
base=base,
token=token,
task_id=collecting,
interval=interval,
timeout_seconds=timeout_seconds,
)
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,
)
created, _ = _request_json(
f"{base}/video_generation",
provider="minimax-h3",
body=body,
token=token,
)
task_id = _safe_public_id(created.get("task_id"))
if task_id is None:
raise AdapterFailure(
"MiniMax did not return a task id",
code=_provider_code(created) or "missing_task_id",
)
# Billed from here on. Record the id before the first poll.
_record_handle(job, task_id)
return _poll_minimax_video(
job,
base=base,
token=token,
task_id=task_id,
interval=interval,
timeout_seconds=timeout_seconds,
)
def _poll_minimax_video(
job: Mapping[str, Any],
*,
base: str,
token: str,
task_id: str,
interval: float | None = None,
timeout_seconds: float | None = None,
) -> tuple[Path, str]:
if interval is None or timeout_seconds is None:
interval, timeout_seconds = _polling_config(
"MINIMAX_VIDEO_POLL_INTERVAL",
"MINIMAX_VIDEO_TIMEOUT_SECONDS",
provider="MiniMax",
)
deadline = time.monotonic() + timeout_seconds
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 main(argv: Sequence[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"provider",
choices=(
"seedance", "gpt-image-2", "minimax-music", "minimax-h3",
"minimax-speech",
),
)
args = parser.parse_args(argv)
effective_provider: str = args.provider
try:
raw_stdin: bytes | str = (
sys.stdin.buffer.read()
if hasattr(sys.stdin, "buffer")
else sys.stdin.read()
)
job = json.loads(raw_stdin)
if not isinstance(job, Mapping):
raise ValueError("adapter input must be an object")
adapter_name = _safe_public_id(job.get("adapter"))
if adapter_name is not None:
effective_provider = adapter_name
runners = {
"seedance": _run_seedance,
"gpt-image-2": _run_openai,
"minimax-music": _run_minimax,
"minimax-h3": _run_minimax_video,
"minimax-speech": _run_minimax_speech,
}
result_paths, provider_job_id = runners[args.provider](job)
paths = result_paths if isinstance(result_paths, list) else [result_paths]
response: dict[str, Any] = {
"outputs": [
{"target": target, "source": str(path)}
for target, path in zip(job["outputs"], paths)
]
}
safe_job_id = _safe_public_id(provider_job_id)
if safe_job_id is not None:
response["provider_job_id"] = safe_job_id
json.dump(response, sys.stdout, ensure_ascii=True)
return 0
except AdapterFailure as exc:
# Provider bodies and credentials are intentionally never reflected.
json.dump({"error": exc.public(effective_provider)}, sys.stdout, ensure_ascii=True)
print("provider adapter failed safely", file=sys.stderr)
return 1
except (KeyError, TypeError, UnicodeError, json.JSONDecodeError):
json.dump(
{
"error": {
"provider": effective_provider,
"category": "invalid_request",
"code": "invalid_job",
"retryable": False,
"submitted": False,
}
},
sys.stdout,
ensure_ascii=True,
)
print("provider adapter failed safely", file=sys.stderr)
return 1
except ValueError as exc:
error_payload: dict[str, Any] = {
"provider": effective_provider,
"category": "invalid_request",
"code": "invalid_job",
"retryable": False,
"submitted": False,
}
detail = _safe_detail(str(exc))
if detail is not None:
error_payload["detail"] = detail
json.dump({"error": error_payload}, sys.stdout, ensure_ascii=True)
print("provider adapter failed safely", file=sys.stderr)
return 1
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |