@danhachuel/thunderbolt 0.3.70 → 0.3.72

package/hermes_ui/media_generation.py

@@ -9,6 +9,12 @@ from __future__ import annotations
 
 import base64
 import binascii
+import json
+import mimetypes
+import os
+import shutil
+import subprocess
+import tempfile
 import time
 from pathlib import Path
 from typing import Any, Mapping
@@ -544,3 +550,332 @@ def generate_video_from_pool(
             if not _is_retryable_media_error(exc):
                 raise
     raise MediaGenerationError("Todos os providers do pool de vídeo falharam: " + " | ".join(errors))
+
+
+KIE_FILE_UPLOAD_ENDPOINT = "https://kieai.redpandaai.co/api/file-stream-upload"
+KIE_MOTION_MODEL = "kling-2.6/motion-control"
+KIE_MOTION_IMAGE_MAX_BYTES = 10 * 1024 * 1024
+KIE_MOTION_VIDEO_MAX_BYTES = 100 * 1024 * 1024
+KIE_MOTION_IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png"}
+KIE_MOTION_VIDEO_EXTENSIONS = {".mp4", ".mov"}
+KIE_VEO_MODELS = {"veo3", "veo3_fast", "veo3_lite"}
+
+
+def _require_kie_card(card: Mapping[str, Any]) -> dict[str, Any]:
+    current = dict(card)
+    if str(current.get("provider") or "").strip().lower() != "kie_ai":
+        raise MediaGenerationError("Este workflow requer um cartão KIE AI activo no pool de vídeo.")
+    if not _api_key(current):
+        raise MediaGenerationError("Configure a API key do KIE AI em Configuração API > API Keys > Imagem e Video IA.")
+    return current
+
+
+def _kie_json_error(payload: Any, *, fallback: str) -> ProviderCallError | None:
+    if not isinstance(payload, Mapping):
+        return ProviderCallError(fallback, category="payload", retryable=False)
+    try:
+        code = int(payload.get("code", 200))
+    except (TypeError, ValueError):
+        code = 200
+    if code == 200:
+        return None
+    category = "quota" if code in {402, 429, 433} else "credential" if code == 401 else "endpoint_or_model" if code in {404, 455, 505} else "transient" if code >= 500 else "payload"
+    return ProviderCallError(str(payload.get("msg") or fallback)[:500], status_code=code, category=category, retryable=category in {"quota", "transient"})
+
+
+def validate_motion_control_file(path: str | Path, *, kind: str) -> dict[str, Any]:
+    """Validate KIE Motion Control local input limits before uploading it."""
+    candidate = Path(path).expanduser()
+    if not candidate.is_file():
+        raise MediaGenerationError(f"O ficheiro de {kind} não está disponível.")
+    suffix = candidate.suffix.lower()
+    if kind == "imagem":
+        allowed, maximum = KIE_MOTION_IMAGE_EXTENSIONS, KIE_MOTION_IMAGE_MAX_BYTES
+    elif kind == "vídeo":
+        allowed, maximum = KIE_MOTION_VIDEO_EXTENSIONS, KIE_MOTION_VIDEO_MAX_BYTES
+    else:
+        raise MediaGenerationError("Tipo de input Motion Control inválido.")
+    if suffix not in allowed:
+        raise MediaGenerationError(f"O {kind} Motion Control deve estar em {', '.join(sorted(allowed))}.")
+    size = candidate.stat().st_size
+    if size <= 0:
+        raise MediaGenerationError(f"O ficheiro de {kind} está vazio.")
+    if size > maximum:
+        raise MediaGenerationError(f"O ficheiro de {kind} excede o limite KIE de {maximum // (1024 * 1024)} MB.")
+    duration = None
+    if kind == "vídeo":
+        ffprobe = shutil.which("ffprobe")
+        if not ffprobe:
+            raise MediaGenerationError("Não foi possível verificar a duração do vídeo Motion Control: instale FFmpeg/ffprobe e tente novamente.")
+        try:
+            probe = subprocess.run(
+                [ffprobe, "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", str(candidate)],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=False,
+            )
+            duration = float(probe.stdout.strip())
+        except (OSError, ValueError, subprocess.TimeoutExpired) as exc:
+            raise MediaGenerationError("Não foi possível verificar a duração do vídeo Motion Control com ffprobe.") from exc
+        if duration < 3 or duration > 30:
+            raise MediaGenerationError(f"O vídeo Motion Control deve ter entre 3 e 30 segundos; o ficheiro tem {duration:.1f}s.")
+    return {"path": str(candidate), "name": candidate.name, "size_bytes": size, "extension": suffix, "duration_seconds": duration}
+
+
+def upload_kie_file(path: str | Path, card: Mapping[str, Any], *, upload_path: str = "thunderbolt/influencers") -> str:
+    """Upload one local file to KIE's temporary public file store using the selected card."""
+    current = _require_kie_card(card)
+    candidate = Path(path).expanduser()
+    if not candidate.is_file():
+        raise MediaGenerationError("O ficheiro seleccionado não está disponível para upload KIE.")
+    mime = mimetypes.guess_type(candidate.name)[0] or "application/octet-stream"
+    try:
+        with candidate.open("rb") as handle:
+            response = requests.post(
+                KIE_FILE_UPLOAD_ENDPOINT,
+                headers={"Authorization": f"Bearer {_api_key(current)}"},
+                files={"file": (candidate.name, handle, mime)},
+                data={"uploadPath": upload_path, "fileName": candidate.name},
+                timeout=300,
+            )
+    except requests.RequestException as exc:
+        raise MediaGenerationError(f"Falha no upload temporário do ficheiro para KIE: {str(exc)[:220]}") from exc
+    if response.status_code >= 400:
+        raise MediaGenerationError(f"O upload temporário KIE devolveu HTTP {response.status_code}.")
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise MediaGenerationError("O upload temporário KIE devolveu uma resposta inválida.") from exc
+    error = _kie_json_error(payload, fallback="O upload temporário KIE falhou.")
+    if error:
+        raise MediaGenerationError(str(error))
+    data = payload.get("data") if isinstance(payload, Mapping) else None
+    url = str((data or {}).get("downloadUrl") or (data or {}).get("fileUrl") or payload.get("downloadUrl") or payload.get("fileUrl") or "").strip() if isinstance(payload, Mapping) else ""
+    if not url.startswith(("http://", "https://")):
+        raise MediaGenerationError("O upload KIE terminou sem devolver um URL público temporário.")
+    return url
+
+
+def _download_video_url(url: str, destination: Path, *, card: Mapping[str, Any] | None = None) -> Path:
+    try:
+        response = requests.get(url, headers=_headers(card or {}) if card else {}, timeout=300)
+        response.raise_for_status()
+    except requests.RequestException as exc:
+        raise MediaGenerationError(f"Não foi possível descarregar o vídeo gerado: {str(exc)[:220]}") from exc
+    if not response.content:
+        raise MediaGenerationError("O provider devolveu um vídeo vazio.")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_bytes(response.content)
+    return destination
+
+
+def _kie_result_urls(value: Any) -> list[str]:
+    if isinstance(value, str):
+        raw = value.strip()
+        try:
+            value = json.loads(raw)
+        except json.JSONDecodeError:
+            value = [raw] if raw.startswith(("http://", "https://")) else []
+    if isinstance(value, Mapping):
+        value = value.get("resultUrls") or value.get("result_urls") or value.get("urls") or []
+    if not isinstance(value, list):
+        return []
+    return [str(item).strip() for item in value if str(item).strip().startswith(("http://", "https://"))]
+
+
+def _poll_kie_task(card: Mapping[str, Any], task_id: str, *, endpoint: str, attempts: int = 40, interval_seconds: float = 5.0, veo: bool = False) -> list[str]:
+    base = _base_url(card) or "https://api.kie.ai/api/v1"
+    url = f"{base}{endpoint}"
+    for index in range(max(1, attempts)):
+        try:
+            response = requests.get(url, headers=_headers(card), params={"taskId": task_id}, timeout=60)
+            if response.status_code >= 400:
+                category = "quota" if response.status_code == 429 else "transient" if response.status_code >= 500 else "endpoint_or_model"
+                raise ProviderCallError(f"Consulta KIE devolveu HTTP {response.status_code}.", status_code=response.status_code, category=category, retryable=category in {"quota", "transient"})
+            payload = response.json()
+        except requests.RequestException as exc:
+            raise ProviderCallError(f"Falha ao consultar a tarefa KIE: {str(exc)[:220]}", category="transient", retryable=True) from exc
+        error = _kie_json_error(payload, fallback="A consulta KIE devolveu um erro.")
+        if error:
+            raise error
+        data = payload.get("data") if isinstance(payload, Mapping) and isinstance(payload.get("data"), Mapping) else {}
+        if veo:
+            flag = data.get("successFlag")
+            if str(flag) in {"2", "3"}:
+                raise ProviderCallError(str(data.get("errorMessage") or payload.get("msg") or "A tarefa VEO falhou."), category="provider", retryable=False)
+            response_data = data.get("response") if isinstance(data.get("response"), Mapping) else {}
+            urls = _kie_result_urls(response_data.get("resultUrls") or data.get("resultUrls"))
+            if str(flag) == "1" and urls:
+                return urls
+        else:
+            state = str(data.get("state") or payload.get("state") or "").lower()
+            if state in {"fail", "failed", "error", "cancelled", "canceled"}:
+                raise ProviderCallError(str(data.get("failMsg") or payload.get("msg") or "A tarefa KIE falhou."), category="provider", retryable=False)
+            urls = _kie_result_urls(data.get("resultJson"))
+            if state == "success" and urls:
+                return urls
+        if index + 1 < attempts:
+            time.sleep(max(0.2, interval_seconds))
+    raise ProviderCallError("A tarefa KIE não concluiu dentro do limite de polling local.", category="transient", retryable=True)
+
+
+def generate_motion_control_video(
+    settings: Mapping[str, Any],
+    card: Mapping[str, Any],
+    *,
+    image_url: str,
+    video_url: str,
+    prompt: str = "",
+    output_path: Path | None = None,
+) -> tuple[Path, str]:
+    """Create a Kling 2.6 Motion Control video and download it locally."""
+    current = _require_kie_card(card)
+    if not image_url.startswith(("http://", "https://")) or not video_url.startswith(("http://", "https://")):
+        raise MediaGenerationError("Motion Control requer URLs KIE acessíveis para a imagem e o vídeo enviados.")
+    clean_prompt = str(prompt or "").strip()
+    if len(clean_prompt) > 2500:
+        raise MediaGenerationError("O prompt Motion Control não pode exceder 2500 caracteres.")
+    base = _base_url(current) or "https://api.kie.ai/api/v1"
+    body: dict[str, Any] = {
+        "model": KIE_MOTION_MODEL,
+        "input": {
+            "prompt": clean_prompt or "Preserve a identidade visual da imagem de referência e aplique os movimentos do vídeo de forma natural, estável e fisicamente plausível.",
+            "input_urls": [image_url],
+            "video_urls": [video_url],
+            "character_orientation": "video",
+            "mode": "720p",
+        },
+    }
+
+    def request(_: dict[str, Any]) -> Any:
+        response = requests.post(f"{base}/jobs/createTask", headers=_headers(current), json=body, timeout=180)
+        if response.status_code < 400:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {}
+            error = _kie_json_error(payload, fallback="A criação Motion Control KIE falhou.")
+            if error:
+                raise error
+        return response
+
+    try:
+        routed = route_json_request(settings, pool=POOL_VIDEO, cards=[current], request=request)
+        data = routed.payload.get("data") if isinstance(routed.payload.get("data"), Mapping) else {}
+        task_id = str(data.get("taskId") or routed.payload.get("taskId") or "").strip()
+        if not task_id:
+            raise MediaGenerationError("KIE aceitou Motion Control mas não devolveu taskId.")
+        urls = _poll_kie_task(routed.card, task_id, endpoint="/jobs/recordInfo", veo=False)
+    except (ProviderRoutingError, ProviderCallError) as exc:
+        raise MediaGenerationError(str(exc)) from exc
+    destination = output_path or (STORAGE / "influencer_workflows" / f"motion-control-{task_id}.mp4")
+    return _download_video_url(urls[0], destination, card=routed.card), task_id
+
+
+def generate_ugc_segment(
+    settings: Mapping[str, Any],
+    card: Mapping[str, Any],
+    *,
+    image_url: str,
+    prompt: str,
+    output_path: Path,
+    duration: int = 8,
+) -> tuple[Path, str]:
+    """Create one VEO3.1 image-to-video segment through the official KIE endpoint."""
+    current = _require_kie_card(card)
+    if not image_url.startswith(("http://", "https://")):
+        raise MediaGenerationError("UGC Products requer um URL KIE acessível para a imagem do produto.")
+    model = _model(current).lower() or "veo3_fast"
+    if model not in KIE_VEO_MODELS:
+        model = "veo3_fast"
+    if duration not in {4, 6, 8}:
+        raise MediaGenerationError("A duração de um segmento VEO3 deve ser 4, 6 ou 8 segundos.")
+    base = _base_url(current) or "https://api.kie.ai/api/v1"
+    body = {
+        "prompt": str(prompt or "").strip(),
+        "imageUrls": [image_url],
+        "model": model,
+        "aspect_ratio": "16:9",
+        "resolution": "720p",
+        "duration": duration,
+    }
+
+    def request(_: dict[str, Any]) -> Any:
+        response = requests.post(f"{base}/veo/generate", headers=_headers(current), json=body, timeout=180)
+        if response.status_code < 400:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {}
+            error = _kie_json_error(payload, fallback="A criação de segmento VEO KIE falhou.")
+            if error:
+                raise error
+        return response
+
+    try:
+        routed = route_json_request(settings, pool=POOL_VIDEO, cards=[current], request=request)
+        data = routed.payload.get("data") if isinstance(routed.payload.get("data"), Mapping) else {}
+        task_id = str(data.get("taskId") or routed.payload.get("taskId") or "").strip()
+        if not task_id:
+            raise MediaGenerationError("KIE aceitou VEO3 mas não devolveu taskId.")
+        urls = _poll_kie_task(routed.card, task_id, endpoint="/veo/record-info", veo=True)
+    except (ProviderRoutingError, ProviderCallError) as exc:
+        raise MediaGenerationError(str(exc)) from exc
+    return _download_video_url(urls[0], output_path, card=routed.card), task_id
+
+
+def concatenate_video_files(paths: list[Path], output_path: Path) -> Path:
+    """Join generated clips locally with FFmpeg, without uploading the result anywhere."""
+    valid = [Path(path) for path in paths if Path(path).is_file()]
+    if not valid:
+        raise MediaGenerationError("Não existem segmentos locais para concatenar.")
+    if len(valid) == 1:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        if valid[0] != output_path:
+            output_path.write_bytes(valid[0].read_bytes())
+        return output_path
+    try:
+        from .metadata_cleaner import _resolve_ffmpeg
+
+        ffmpeg = _resolve_ffmpeg()
+    except Exception as exc:
+        raise MediaGenerationError(str(exc)) from exc
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, manifest_name = tempfile.mkstemp(prefix="ugc-concat-", suffix=".txt", dir=str(output_path.parent))
+    os.close(descriptor)
+    manifest = Path(manifest_name)
+    try:
+        manifest.write_text("\n".join(f"file '{str(path).replace(chr(39), chr(39) + chr(92) + chr(39) + chr(39))}'" for path in valid) + "\n", encoding="utf-8")
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        command = [ffmpeg, "-y", "-f", "concat", "-safe", "0", "-i", str(manifest), "-c", "copy", str(output_path)]
+        completed = subprocess.run(command, capture_output=True, text=True, timeout=600, check=False)
+        if completed.returncode != 0:
+            raise MediaGenerationError(f"FFmpeg não conseguiu juntar os segmentos UGC: {completed.stderr[-500:]}")
+    except OSError as exc:
+        raise MediaGenerationError(f"Não foi possível executar FFmpeg para juntar os segmentos UGC: {exc}") from exc
+    finally:
+        manifest.unlink(missing_ok=True)
+    return output_path
+
+
+def generate_ugc_product_video(
+    settings: Mapping[str, Any],
+    card: Mapping[str, Any],
+    *,
+    image_url: str,
+    prompts: list[str],
+    output_path: Path | None = None,
+) -> tuple[Path, list[str]]:
+    """Generate two 8-second KIE VEO3 clips and concatenate them locally."""
+    clean_prompts = [str(item or "").strip() for item in prompts if str(item or "").strip()]
+    if len(clean_prompts) != 2:
+        raise MediaGenerationError("UGC Products requer exactamente dois prompts de segmento.")
+    ensure_storage()
+    destination = output_path or (STORAGE / "influencer_workflows" / f"ugc-products-{abs(hash((image_url, *clean_prompts))) & 0xffffffffffffffff:x}.mp4")
+    segment_paths = [destination.with_name(f"{destination.stem}-segment-{index + 1}.mp4") for index in range(2)]
+    task_ids: list[str] = []
+    for prompt, segment_path in zip(clean_prompts, segment_paths):
+        _, task_id = generate_ugc_segment(settings, card, image_url=image_url, prompt=prompt, output_path=segment_path, duration=8)
+        task_ids.append(task_id)
+    return concatenate_video_files(segment_paths, destination), task_ids

package/integrations/bilibili_upload.py

@@ -0,0 +1,259 @@
+"""Upload de vídeo para Bilibili usando bilibili-api-python.
+
+A biblioteca é opcional no import para que o Thunderbolt continue a arrancar sem
+credenciais Bilibili. As operações do SDK são assíncronas; este adapter expõe uma
+interface síncrona adequada à UI Streamlit e nunca devolve os cookies nos dados.
+"""
+from __future__ import annotations
+
+import asyncio
+import subprocess
+import tempfile
+import threading
+from pathlib import Path
+from typing import Any, Awaitable
+
+from .platforms import IntegrationResult
+
+BILIBILI_VIDEO_EXTENSIONS = {".mp4", ".mov", ".mkv", ".webm"}
+BILIBILI_MAX_TITLE = 80
+BILIBILI_MAX_DESCRIPTION = 2000
+BILIBILI_MAX_TAGS = 10
+BILIBILI_DEFAULT_TID = 130
+BILIBILI_API_VERSION = "17.4.2"
+_SENSITIVE_FIELDS = {"sessdata", "bili_jct", "buvid3", "buvid4", "dedeuserid", "ac_time_value", "proxy"}
+
+
+def _safe_card(card: dict[str, Any], index: int) -> dict[str, Any]:
+    return {
+        "id": str(card.get("id") or f"bilibili-api-{index + 1}").strip(),
+        "label": str(card.get("label") or card.get("name") or f"Conta Bilibili {index + 1}").strip(),
+        "active": bool(card.get("active", True)),
+        "sessdata": str(card.get("sessdata") or "").strip(),
+        "bili_jct": str(card.get("bili_jct") or "").strip(),
+        "buvid3": str(card.get("buvid3") or "").strip(),
+        "buvid4": str(card.get("buvid4") or "").strip(),
+        "dedeuserid": str(card.get("dedeuserid") or "").strip(),
+        "ac_time_value": str(card.get("ac_time_value") or "").strip(),
+        "proxy": str(card.get("proxy") or "").strip(),
+    }
+
+
+def normalise_bilibili_api_cards(settings: dict[str, Any] | None) -> tuple[list[dict[str, Any]], bool]:
+    """Normalise multi-account cards and migrate one legacy settings record."""
+    settings = settings or {}
+    raw = settings.get("bilibili_api_cards")
+    cards: list[dict[str, Any]] = []
+    changed = not isinstance(raw, list)
+    if isinstance(raw, list):
+        for index, item in enumerate(raw):
+            if isinstance(item, dict):
+                card = _safe_card(item, index)
+                cards.append(card)
+                if any(str(item.get(key) or "").strip() != str(card.get(key) or "").strip() for key in card if key not in {"active"}):
+                    changed = True
+            else:
+                changed = True
+    legacy_keys = ("bilibili_sessdata", "bilibili_bili_jct", "bilibili_buvid3", "bilibili_buvid4", "bilibili_dedeuserid", "bilibili_ac_time_value", "bilibili_proxy")
+    legacy_values = {key.removeprefix("bilibili_"): str(settings.get(key) or "").strip() for key in legacy_keys}
+    if not cards and any(legacy_values.values()):
+        cards.append(_safe_card({"id": "bilibili-api-1", "label": "Conta Bilibili 1", **legacy_values}, 0))
+        changed = True
+    return cards, changed
+
+
+def _redacted_card(card: dict[str, Any]) -> dict[str, Any]:
+    return {key: ("***" if key in _SENSITIVE_FIELDS and value else value) for key, value in card.items() if key not in _SENSITIVE_FIELDS or not value}
+
+
+def _safe_card_payload(card: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in _safe_card(card, 0).items() if key != "id"}
+
+
+def _import_sdk() -> tuple[Any, Any]:
+    try:
+        from bilibili_api import Credential, video_uploader
+    except ImportError as exc:
+        raise RuntimeError("A dependência bilibili-api-python não está instalada. Instale/actualize o Thunderbolt e tente novamente.") from exc
+    return Credential, video_uploader
+
+
+def _run_async(awaitable: Awaitable[Any]) -> Any:
+    """Run one SDK coroutine from Streamlit, including when a loop already exists."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(awaitable)
+    result: list[Any] = []
+    error: list[BaseException] = []
+
+    def runner() -> None:
+        try:
+            result.append(asyncio.run(awaitable))
+        except BaseException as exc:  # preserve SDK exception for UI attribution
+            error.append(exc)
+
+    thread = threading.Thread(target=runner, name="thunderbolt-bilibili-sdk", daemon=True)
+    thread.start()
+    thread.join()
+    if error:
+        raise error[0]
+    return result[0] if result else None
+
+
+def _credential(card: dict[str, Any], Credential: Any) -> Any:
+    values = _safe_card_payload(card)
+    values.pop("label", None)
+    values.pop("active", None)
+    values.pop("proxy", None)
+    return Credential(proxy=str(card.get("proxy") or "").strip() or None, **values)
+
+
+def _derive_cover(video_path: Path, directory: Path) -> Path:
+    try:
+        from imageio_ffmpeg import get_ffmpeg_exe
+        executable = get_ffmpeg_exe()
+    except Exception as exc:
+        raise RuntimeError("Não foi possível localizar FFmpeg para criar a capa automática do vídeo Bilibili.") from exc
+    target = directory / "bilibili-cover.jpg"
+    completed = subprocess.run(
+        [executable, "-y", "-hide_banner", "-loglevel", "error", "-ss", "0", "-i", str(video_path), "-frames:v", "1", "-q:v", "3", str(target)],
+        capture_output=True, text=True, timeout=90, check=False,
+    )
+    if completed.returncode != 0 or not target.is_file():
+        raise RuntimeError("FFmpeg não conseguiu criar uma capa a partir do vídeo Bilibili.")
+    return target
+
+def _normalise_tags(tags: str | list[str] | tuple[str, ...] | None) -> list[str]:
+    values = tags if isinstance(tags, (list, tuple)) else str(tags or "").replace("\n", ",").split(",")
+    output: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        clean = str(value or "").strip()
+        if clean and clean not in seen:
+            output.append(clean)
+            seen.add(clean)
+    return output
+
+
+class BilibiliApiAdapter:
+    """Synchronous wrapper around bilibili-api-python's asynchronous video uploader."""
+
+    def __init__(self, card: dict[str, Any] | None = None, settings: dict[str, Any] | None = None):
+        self.card = _safe_card(card or {}, 0)
+        self.settings = settings or {}
+
+    def status(self) -> IntegrationResult:
+        missing = [field for field in ("sessdata", "bili_jct", "buvid3") if not str(self.card.get(field) or "").strip()]
+        if missing:
+            return IntegrationResult(False, "Conta Bilibili incompleta: configure SESSDATA, bili_jct e BUVID3.", {"missing_fields": missing, "account": self.card.get("label", "Conta Bilibili")})
+        try:
+            _import_sdk()
+        except RuntimeError as exc:
+            return IntegrationResult(False, str(exc), {"account": self.card.get("label", "Conta Bilibili")})
+        return IntegrationResult(True, f"Conta Bilibili pronta: {self.card.get('label', 'Conta Bilibili')}.", {"account": self.card.get("label", "Conta Bilibili"), "sdk": BILIBILI_API_VERSION})
+
+    def test_connection(self) -> IntegrationResult:
+        status = self.status()
+        if not status.ok:
+            return status
+        try:
+            Credential, _ = _import_sdk()
+            credential = _credential(self.card, Credential)
+            valid = _run_async(credential.check_valid())
+            if not bool(valid):
+                return IntegrationResult(False, "A sessão Bilibili foi rejeitada ou expirou. Actualize SESSDATA, bili_jct e BUVID3.", {"account": self.card.get("label", "Conta Bilibili"), "valid": False})
+            return IntegrationResult(True, f"Chamada Bilibili concluída para {self.card.get('label', 'Conta Bilibili')}.", {"account": self.card.get("label", "Conta Bilibili"), "valid": True})
+        except Exception as exc:
+            return IntegrationResult(False, f"A chamada Bilibili falhou: {exc}", {"account": self.card.get("label", "Conta Bilibili"), "api": "bilibili-api-python"})
+
+    def upload_video(
+        self,
+        video_path: str | Path,
+        *,
+        title: str,
+        description: str = "",
+        tags: str | list[str] | tuple[str, ...] | None = None,
+        tid: int = BILIBILI_DEFAULT_TID,
+        cover_path: str | Path | None = None,
+        original: bool = True,
+        dynamic: str = "",
+    ) -> IntegrationResult:
+        status = self.status()
+        if not status.ok:
+            return status
+        path = Path(video_path).expanduser()
+        if not path.is_file():
+            return IntegrationResult(False, f"Vídeo Bilibili não encontrado: {path}", {"api": "bilibili-api-python"})
+        if path.suffix.lower() not in BILIBILI_VIDEO_EXTENSIONS:
+            return IntegrationResult(False, f"Formato Bilibili não suportado: {path.suffix}. Use MP4, MOV, MKV ou WEBM.", {"api": "bilibili-api-python"})
+        clean_title = str(title or "Vídeo Thunderbolt").strip()
+        clean_description = str(description or "").strip()
+        clean_tags = _normalise_tags(tags)
+        if not clean_title or len(clean_title) > BILIBILI_MAX_TITLE:
+            return IntegrationResult(False, "O título Bilibili é obrigatório e deve ter no máximo 80 caracteres.", {"api": "bilibili-api-python"})
+        if len(clean_description) > BILIBILI_MAX_DESCRIPTION:
+            return IntegrationResult(False, "A descrição Bilibili deve ter no máximo 2000 caracteres.", {"api": "bilibili-api-python"})
+        if not clean_tags or len(clean_tags) > BILIBILI_MAX_TAGS:
+            return IntegrationResult(False, "Indique entre 1 e 10 tags Bilibili, separadas por vírgulas.", {"api": "bilibili-api-python"})
+        try:
+            tid_value = int(tid)
+        except (TypeError, ValueError):
+            return IntegrationResult(False, "O ID da secção Bilibili deve ser numérico.", {"api": "bilibili-api-python"})
+        cover = Path(cover_path).expanduser() if cover_path else None
+        if cover is not None and not cover.is_file():
+            return IntegrationResult(False, f"Capa Bilibili não encontrada: {cover}", {"api": "bilibili-api-python"})
+        try:
+            Credential, video_uploader = _import_sdk()
+            credential = _credential(self.card, Credential)
+            page = video_uploader.VideoUploaderPage(str(path), clean_title, clean_description)
+            meta: dict[str, Any] = {
+                "title": clean_title,
+                "copyright": 1 if original else 2,
+                "tid": tid_value,
+                "tag": ",".join(clean_tags),
+                "desc_format_id": 9999,
+                "desc": clean_description,
+                "recreate": -1,
+                "dynamic": str(dynamic or "")[:233],
+                "interactive": 0,
+                "act_reserve_create": 0,
+                "no_disturbance": 0,
+                "no_reprint": 0,
+                "subtitle": {"open": 0, "lan": ""},
+                "dolby": 0,
+                "lossless_music": 0,
+                "web_os": 1,
+            }
+            temporary_cover: tempfile.TemporaryDirectory[str] | None = None
+            if cover is None:
+                temporary_cover = tempfile.TemporaryDirectory(prefix="thunderbolt-bilibili-")
+                cover = _derive_cover(path, Path(temporary_cover.name))
+            try:
+                uploader = video_uploader.VideoUploader([page], meta, credential, cover=str(cover))
+                result = _run_async(uploader.start())
+            finally:
+                if temporary_cover is not None:
+                    temporary_cover.cleanup()
+            payload = result if isinstance(result, dict) else {"response": result}
+            public_data = {key: payload.get(key) for key in ("bvid", "aid", "code", "message") if key in payload}
+            public_data.update({"account": self.card.get("label", "Conta Bilibili"), "api": "bilibili-api-python", "title": clean_title})
+            bvid = str(payload.get("bvid") or "").strip()
+            message = "Upload Bilibili concluído."
+            if bvid:
+                message += f" BVID: {bvid}."
+            return IntegrationResult(True, message, public_data)
+        except Exception as exc:
+            return IntegrationResult(False, f"Upload Bilibili falhou na API bilibili-api-python: {exc}", {"account": self.card.get("label", "Conta Bilibili"), "api": "bilibili-api-python"})
+
+
+__all__ = [
+    "BILIBILI_API_VERSION",
+    "BILIBILI_DEFAULT_TID",
+    "BILIBILI_MAX_DESCRIPTION",
+    "BILIBILI_MAX_TAGS",
+    "BILIBILI_MAX_TITLE",
+    "BILIBILI_VIDEO_EXTENSIONS",
+    "BilibiliApiAdapter",
+    "normalise_bilibili_api_cards",
+]