bithuman 1.0.2__py3-none-any.whl

bithuman/lib/generator.py

@@ -0,0 +1,763 @@
+from __future__ import annotations
+
+import os
+import threading
+import time
+import uuid
+from typing import Dict, Optional, Union
+
+import numpy as np
+from loguru import logger
+
+from ..engine import RUNTIME_VERSION, CompressionType, LoadingMode
+from ..engine.auth import (
+    JWTValidator,
+    calculate_file_md5,
+    generate_hardware_fingerprint,
+    generate_uuid,
+    request_token as _http_request_token,
+)
+from ..engine.compression import decode_image, encode_image
+from ..engine.image_ops import resize_image
+from ..engine.inference import AudioEncoder
+from ..engine.knn import AudioFeatureIndex
+from ..engine.video_data import LipFormat, VideoData
+
+
+def _parse_compression_type(compression_type: CompressionType | str) -> CompressionType:
+    if isinstance(compression_type, CompressionType):
+        return compression_type
+    maps = {
+        "NONE": CompressionType.NONE,
+        "JPEG": CompressionType.JPEG,
+        "LZ4": CompressionType.LZ4,
+        "TEMP_FILE": CompressionType.TEMP_FILE,
+    }
+    if isinstance(compression_type, str):
+        if compression_type not in maps:
+            raise ValueError(f"Invalid compression type: {compression_type}")
+        compression_type = maps[compression_type]
+    return compression_type
+
+
+def _parse_loading_mode(loading_mode: LoadingMode | str) -> LoadingMode:
+    if isinstance(loading_mode, LoadingMode):
+        return loading_mode
+    maps = {
+        "SYNC": LoadingMode.SYNC,
+        "ASYNC": LoadingMode.ASYNC,
+        "ON_DEMAND": LoadingMode.ON_DEMAND,
+    }
+    return maps[loading_mode]
+
+
+# ---------------------------------------------------------------------------
+# _PythonBithumanRuntime — drop-in replacement for the C++ LibBithuman
+# ---------------------------------------------------------------------------
+class _PythonBithumanRuntime:
+    """Pure Python replacement for the C++ BithumanRuntime (pybind11 class).
+
+    Every public method matches the C++ pybind11 interface exactly so that
+    ``BithumanGenerator`` and ``runtime.py`` can use it without changes.
+    """
+
+    _runtime_version: str = RUNTIME_VERSION
+
+    def __init__(self, audio_encoder_path: str = "", output_size: int = -1) -> None:
+        # Audio encoder (ONNX)
+        self._audio_encoder = AudioEncoder(audio_encoder_path if audio_encoder_path else "")
+
+        # Audio features (KNN index)
+        self._audio_features = AudioFeatureIndex()
+
+        # Output size (-1 means use original)
+        self._output_size = output_size
+
+        # Video data map: name -> VideoData
+        self._video_data: Dict[str, VideoData] = {}
+
+        # JWT validator
+        self._jwt_validator = JWTValidator()
+
+        # Hardware fingerprint (generated once at init, matches C++)
+        self._fingerprint = generate_hardware_fingerprint()
+
+        # Model hash for token verification
+        self._model_hash = ""
+        self._encrypted_model_hash = ""
+
+        # Token refresh thread state
+        self._refresh_thread: Optional[threading.Thread] = None
+        self._refresh_stop_event = threading.Event()
+        self._refresh_running = False
+        self._account_status_error = False
+
+        # Transaction ID (generated in C++ layer to prevent user tampering)
+        self._transaction_id = ""
+        self._transaction_lock = threading.Lock()
+
+        # Instance ID from JWT
+        self._instance_id = ""
+
+    # ------------------------------------------------------------------
+    # Audio encoder
+    # ------------------------------------------------------------------
+    def set_audio_encoder(self, path: str) -> None:
+        self._audio_encoder.load(path)
+
+    # ------------------------------------------------------------------
+    # Audio features
+    # ------------------------------------------------------------------
+    def set_audio_feature(self, feature_source: Union[str, np.ndarray]) -> None:
+        """Set audio features from HDF5 path or numpy array."""
+        if isinstance(feature_source, str):
+            self._audio_features.load_from_h5(feature_source)
+        else:
+            self._audio_features.set_features(feature_source.astype(np.float32))
+
+    # ------------------------------------------------------------------
+    # Output size
+    # ------------------------------------------------------------------
+    def set_output_size(self, output_size: int) -> None:
+        self._output_size = output_size
+
+    # ------------------------------------------------------------------
+    # Video management
+    # ------------------------------------------------------------------
+    def add_video(
+        self,
+        video_name: str,
+        video_path: str,
+        video_data_path: str,
+        avatar_data_path: str,
+        compression_type: CompressionType = CompressionType.JPEG,
+        loading_mode: LoadingMode = LoadingMode.ASYNC,
+        thread_count: int = 0,
+    ) -> None:
+        """Add a video. Matches C++ addVideo (lines 385-407)."""
+        lip_format = LipFormat.detect(avatar_data_path) if avatar_data_path else LipFormat.NONE
+
+        vd = VideoData(
+            video_path=video_path,
+            video_data_path=video_data_path,
+            avatar_data_path=avatar_data_path,
+            lip_format=lip_format,
+            compression_type=compression_type,
+            loading_mode=loading_mode,
+            thread_count=thread_count,
+        )
+        self._video_data[video_name] = vd
+
+    # ------------------------------------------------------------------
+    # Core pipeline: process_audio
+    # ------------------------------------------------------------------
+    def process_audio(
+        self, mel_chunk: np.ndarray, video_name: str, frame_idx: int
+    ) -> np.ndarray:
+        """Process mel chunk → embedding → KNN → blended frame.
+
+        Matches generator.cpp processAudio (lines 321-359):
+        1. checkJWTValidation()
+        2. melChunkToAudioEmbedding(mel_chunk)
+        3. find nearest cluster in audio_features_
+        4. getBlendedFrame(video_name, frame_idx, cluster_idx, num_clusters)
+        5. resize to output_size if needed
+        """
+        self._check_jwt_validation()
+
+        # 1. Mel → embedding
+        embedding = self._audio_encoder.encode(mel_chunk.astype(np.float32))
+
+        # 2. Find nearest cluster
+        cluster_idx = self._audio_features.find_nearest(embedding)
+        num_clusters = self._audio_features.num_clusters
+
+        # 3. Get blended frame
+        vd = self._video_data.get(video_name)
+        if vd is None:
+            raise RuntimeError(f"Video not found: {video_name}")
+
+        frame = vd.get_blended_frame(frame_idx, cluster_idx, num_clusters)
+
+        # 4. Resize if output_size is set
+        if self._output_size > 0 and frame.shape[1] != self._output_size:
+            scale = self._output_size / frame.shape[1]
+            new_h = round(frame.shape[0] * scale)
+            frame = resize_image(frame, self._output_size, new_h)
+
+        return frame
+
+    # ------------------------------------------------------------------
+    # Original frame access
+    # ------------------------------------------------------------------
+    def get_original_frame(self, video_name: str, frame_idx: int) -> np.ndarray:
+        """Get original (non-blended) frame. Matches C++ getOriginalFrame."""
+        self._check_jwt_validation()
+
+        vd = self._video_data.get(video_name)
+        if vd is None:
+            raise RuntimeError(f"Video not found: {video_name}")
+
+        frame = vd.get_original_frame(frame_idx)
+
+        if self._output_size > 0 and frame.shape[1] != self._output_size:
+            scale = self._output_size / frame.shape[1]
+            new_h = round(frame.shape[0] * scale)
+            frame = resize_image(frame, self._output_size, new_h)
+
+        return frame
+
+    # ------------------------------------------------------------------
+    # Frame count
+    # ------------------------------------------------------------------
+    def get_num_frames(self, video_name: str) -> int:
+        vd = self._video_data.get(video_name)
+        if vd is None:
+            return -1
+        return vd.num_frames
+
+    # ------------------------------------------------------------------
+    # JWT / Token validation
+    # ------------------------------------------------------------------
+    def validate_token(self, token: str, verbose: bool = True) -> bool:
+        """Validate and set a JWT token. Matches C++ validateToken."""
+        result = self._jwt_validator.validate_token(token, verbose=verbose)
+        if result:
+            self._instance_id = self._jwt_validator._instance_id
+        return result
+
+    def is_token_validated(self) -> bool:
+        return self._jwt_validator.is_validated()
+
+    def has_expired(self) -> bool:
+        return self._jwt_validator.has_expired()
+
+    def get_expiration_time(self) -> int:
+        """Return expiration time as int seconds, -1 if not validated."""
+        exp = self._jwt_validator.get_expiration_time()
+        if exp is None:
+            return -1
+        return int(exp)
+
+    def get_instance_id(self) -> str:
+        return self._instance_id
+
+    # ------------------------------------------------------------------
+    # Model hash
+    # ------------------------------------------------------------------
+    def set_model_hash_from_file(self, model_path: str) -> str:
+        """Calculate and store model hash from file. Matches C++ setModelHashFromFile."""
+        self._model_hash = calculate_file_md5(model_path)
+        self._encrypted_model_hash = self._jwt_validator.encrypt_model_hash(self._model_hash)
+        return self._model_hash
+
+    # ------------------------------------------------------------------
+    # Hardware fingerprint
+    # ------------------------------------------------------------------
+    def getFingerprint(self) -> str:
+        return self._fingerprint
+
+    # ------------------------------------------------------------------
+    # Token request
+    # ------------------------------------------------------------------
+    def request_token(
+        self,
+        api_url: str,
+        api_secret: str,
+        model_path: Optional[str] = None,
+        tags: Optional[str] = None,
+        transaction_id: Optional[str] = None,
+        insecure: bool = False,
+        timeout: float = 30.0,
+    ) -> str:
+        """Request a token from the auth API. Matches C++ requestToken."""
+        # Calculate runtime model hash if model_path is provided
+        runtime_model_hash = None
+        if model_path:
+            raw_hash = calculate_file_md5(model_path)
+            if raw_hash:
+                runtime_model_hash = self._jwt_validator.encrypt_model_hash(raw_hash)
+
+        return _http_request_token(
+            api_url=api_url,
+            api_secret=api_secret,
+            fingerprint=self._fingerprint,
+            runtime_model_hash=runtime_model_hash,
+            tags=tags,
+            transaction_id=transaction_id,
+            insecure=insecure,
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Token refresh thread
+    # ------------------------------------------------------------------
+    def start_token_refresh(
+        self,
+        api_url: str,
+        api_secret: str,
+        model_path: Optional[str] = None,
+        tags: Optional[str] = None,
+        refresh_interval: int = 60,
+        insecure: bool = False,
+        timeout: float = 30.0,
+    ) -> bool:
+        """Start background token refresh. Matches C++ startTokenRefresh.
+
+        Does an initial synchronous token request, then spawns a daemon
+        thread that refreshes every ``refresh_interval`` seconds.
+        Returns True if started, False if already running.
+        """
+        if self._refresh_running:
+            return False
+
+        # Calculate runtime model hash once
+        runtime_model_hash = None
+        if model_path:
+            raw_hash = calculate_file_md5(model_path)
+            if raw_hash:
+                runtime_model_hash = self._jwt_validator.encrypt_model_hash(raw_hash)
+                self._model_hash = raw_hash
+                self._encrypted_model_hash = runtime_model_hash
+
+        # Synchronous initial token request (matches C++ behavior)
+        try:
+            with self._transaction_lock:
+                txn_id = self._transaction_id
+
+            token = _http_request_token(
+                api_url=api_url,
+                api_secret=api_secret,
+                fingerprint=self._fingerprint,
+                runtime_model_hash=runtime_model_hash,
+                tags=tags,
+                transaction_id=txn_id,
+                insecure=insecure,
+                timeout=timeout,
+            )
+            if not self._jwt_validator.validate_token(token, verbose=True):
+                logger.error("Initial token validation failed during start_token_refresh")
+                return False
+            self._instance_id = self._jwt_validator._instance_id
+            logger.info("Initial token acquired and validated")
+        except RuntimeError as e:
+            error_msg = str(e)
+            if "402" in error_msg or "403" in error_msg or "400" in error_msg:
+                self._account_status_error = True
+                logger.error(f"Account status error: {e}")
+            raise
+
+        # Start background refresh thread
+        self._refresh_stop_event.clear()
+        self._refresh_running = True
+
+        self._refresh_thread = threading.Thread(
+            target=self._token_refresh_worker,
+            args=(
+                api_url,
+                api_secret,
+                runtime_model_hash,
+                tags,
+                refresh_interval,
+                insecure,
+                timeout,
+            ),
+            daemon=True,
+        )
+        self._refresh_thread.start()
+        return True
+
+    def _token_refresh_worker(
+        self,
+        api_url: str,
+        api_secret: str,
+        runtime_model_hash: Optional[str],
+        tags: Optional[str],
+        refresh_interval: int,
+        insecure: bool,
+        timeout: float,
+    ) -> None:
+        """Background token refresh loop. Matches C++ tokenRefreshWorker."""
+        max_retries = 3
+
+        while not self._refresh_stop_event.is_set():
+            # Sleep in small increments so we can respond to stop quickly
+            for _ in range(refresh_interval * 10):
+                if self._refresh_stop_event.is_set():
+                    break
+                time.sleep(0.1)
+
+            if self._refresh_stop_event.is_set():
+                break
+
+            # Attempt token refresh with retries
+            with self._transaction_lock:
+                txn_id = self._transaction_id
+
+            success = False
+            for attempt in range(max_retries):
+                if self._refresh_stop_event.is_set():
+                    break
+                try:
+                    token = _http_request_token(
+                        api_url=api_url,
+                        api_secret=api_secret,
+                        fingerprint=self._fingerprint,
+                        runtime_model_hash=runtime_model_hash,
+                        tags=tags,
+                        transaction_id=txn_id,
+                        insecure=insecure,
+                        timeout=timeout,
+                    )
+                    if self._jwt_validator.validate_token(token, verbose=True):
+                        self._instance_id = self._jwt_validator._instance_id
+                        logger.debug("Token refreshed successfully")
+                        success = True
+                        break
+                    else:
+                        logger.warning(
+                            f"Token refresh validation failed (attempt {attempt + 1}/{max_retries})"
+                        )
+                except RuntimeError as e:
+                    error_msg = str(e)
+                    # Permanent errors — stop retrying
+                    if "402" in error_msg or "403" in error_msg or "400" in error_msg:
+                        self._account_status_error = True
+                        logger.error(f"Permanent token refresh error: {e}")
+                        self._refresh_running = False
+                        return
+                    logger.warning(
+                        f"Token refresh request failed (attempt {attempt + 1}/{max_retries}): {e}"
+                    )
+                    if attempt < max_retries - 1:
+                        time.sleep(2 ** attempt)  # Exponential backoff
+
+            if not success and not self._refresh_stop_event.is_set():
+                logger.error("Token refresh failed after all retries")
+
+        self._refresh_running = False
+
+    def stop_token_refresh(self) -> None:
+        """Stop the background token refresh thread."""
+        self._refresh_stop_event.set()
+        if self._refresh_thread and self._refresh_thread.is_alive():
+            self._refresh_thread.join(timeout=5.0)
+        self._refresh_running = False
+
+    def is_token_refresh_running(self) -> bool:
+        return self._refresh_running
+
+    def is_account_status_error(self) -> bool:
+        return self._account_status_error
+
+    # ------------------------------------------------------------------
+    # Transaction ID
+    # ------------------------------------------------------------------
+    def generate_transaction_id(self) -> str:
+        """Generate and store a new transaction ID. Matches C++ generateTransactionId."""
+        with self._transaction_lock:
+            self._transaction_id = generate_uuid()
+            return self._transaction_id
+
+    def get_transaction_id(self) -> str:
+        with self._transaction_lock:
+            return self._transaction_id
+
+    # ------------------------------------------------------------------
+    # Static methods
+    # ------------------------------------------------------------------
+    @staticmethod
+    def get_runtime_version() -> str:
+        return RUNTIME_VERSION
+
+    @staticmethod
+    def build_token_request_data(
+        fingerprint: str,
+        runtime_model_hash: Optional[str] = None,
+        tags: Optional[str] = None,
+        transaction_id: Optional[str] = None,
+    ) -> str:
+        """Build JSON token request body. Matches C++ buildTokenRequestData."""
+        import json
+
+        body: dict = {
+            "fingerprint": fingerprint,
+            "runtime_version": RUNTIME_VERSION,
+        }
+        if runtime_model_hash:
+            body["runtime_model_hash"] = runtime_model_hash
+        if tags:
+            body["tags"] = tags
+        if transaction_id:
+            body["transaction_id"] = transaction_id
+        return json.dumps(body)
+
+    # ------------------------------------------------------------------
+    # Internal JWT check (called before every frame operation)
+    # ------------------------------------------------------------------
+    def _check_jwt_validation(self) -> None:
+        """Check JWT validity before operations. Matches C++ checkJWTValidation.
+
+        Raises RuntimeError if:
+        - Account status error (402/403/400)
+        - Token not validated
+        - Token expired
+        - Model hash not allowed
+        - Video hash not allowed (not implemented here — future)
+        """
+        if self._account_status_error:
+            raise RuntimeError(
+                "Account status error: token refresh failed with permanent error. "
+                "Runtime terminated."
+            )
+
+        if not self._jwt_validator.is_validated():
+            raise RuntimeError("Token validation failed: token not validated")
+
+        if self._jwt_validator.has_expired():
+            raise RuntimeError("Token validation failed: token has expired")
+
+        # Model hash verification
+        if self._model_hash:
+            if not self._jwt_validator.is_model_hash_allowed(
+                self._model_hash, self._encrypted_model_hash
+            ):
+                raise RuntimeError(
+                    "Token validation failed: model hash not allowed by token"
+                )
+
+
+# ---------------------------------------------------------------------------
+# BithumanGenerator — public wrapper (API unchanged)
+# ---------------------------------------------------------------------------
+class BithumanGenerator:
+    """High-level Python wrapper for Bithuman Runtime Generator."""
+
+    # Re-export CompressionType enum
+    CompressionType = CompressionType
+
+    def __init__(
+        self,
+        audio_encoder_path: Optional[str] = None,
+        output_size: int = -1,
+        api_secret: Optional[str] = None,
+        api_url: Optional[str] = None,
+        model_path: Optional[str] = None,
+        tags: Optional[str] = None,
+        insecure: bool = False,
+    ):
+        """Initialize the generator.
+
+        Args:
+            audio_encoder_path: Path to the ONNX audio encoder model
+            output_size: Output size for frames
+            api_secret: Optional API secret for automatic token refresh
+            api_url: Optional API endpoint URL for token requests
+            model_path: Optional model file path (for token refresh)
+            tags: Optional tags for token requests
+            insecure: Whether to disable SSL verification
+        """
+        if audio_encoder_path is not None:
+            audio_encoder_path = str(audio_encoder_path)
+
+        # Validate audio encoder model file
+        if audio_encoder_path:
+            if not os.path.isfile(audio_encoder_path):
+                raise FileNotFoundError(
+                    f"Audio encoder model not found: {audio_encoder_path}"
+                )
+            file_size = os.path.getsize(audio_encoder_path)
+            if file_size == 0:
+                raise ValueError(
+                    f"Audio encoder model is empty (0 bytes): {audio_encoder_path}"
+                )
+            logger.debug(
+                f"Audio encoder model validated: {audio_encoder_path} "
+                f"({file_size / 1024:.1f} KB)"
+            )
+
+        try:
+            self._generator = _PythonBithumanRuntime(
+                audio_encoder_path or "", output_size
+            )
+        except Exception as e:
+            logger.error(
+                f"Failed to initialize runtime with audio encoder "
+                f"'{audio_encoder_path}': {e}"
+            )
+            raise RuntimeError(
+                f"ONNX audio encoder initialization failed: {e}. "
+                f"This may indicate CPU incompatibility with the INT8 quantized "
+                f"model. Check that the deployment environment supports the "
+                f"required instruction set."
+            ) from e
+
+        # Store initialization parameters for security checks
+        self._initialized_api_secret = api_secret
+        self._initialized_api_url = api_url
+        self._initialized_model_path = model_path
+        self._initialized_tags = tags
+        self._initialized_insecure = insecure
+
+    def set_model_hash_from_file(self, model_path: str) -> str:
+        """Set the model hash for verification against the token from a file."""
+        return self._generator.set_model_hash_from_file(model_path)
+
+    def get_instance_id(self) -> str:
+        """Get the instance ID of this runtime."""
+        return self._generator.get_instance_id()
+
+    def is_token_refresh_running(self) -> bool:
+        """Check if token refresh thread is running."""
+        return self._generator.is_token_refresh_running()
+
+    def is_account_status_error(self) -> bool:
+        """Check if account status error occurred (402, 403, 400)."""
+        return self._generator.is_account_status_error()
+
+    def generate_transaction_id(self) -> str:
+        """Generate and set a new transaction ID."""
+        return self._generator.generate_transaction_id()
+
+    def get_transaction_id(self) -> str:
+        """Get current transaction ID."""
+        return self._generator.get_transaction_id()
+
+    def set_audio_encoder(self, audio_encoder_path: str) -> None:
+        """Set the audio encoder model path."""
+        self._generator.set_audio_encoder(str(audio_encoder_path))
+
+    def set_audio_feature(self, audio_feature: Union[str, np.ndarray]) -> None:
+        """Set the audio feature."""
+        if isinstance(audio_feature, str):
+            self._generator.set_audio_feature(audio_feature)
+        else:
+            self._generator.set_audio_feature(audio_feature.astype(np.float32))
+
+    def set_output_size(self, output_size: int) -> None:
+        """Set the output size."""
+        self._generator.set_output_size(output_size)
+
+    def add_video(
+        self,
+        video_name: str,
+        video_path: str,
+        video_data_path: str,
+        avatar_data_path: str,
+        compression_type: CompressionType | str = CompressionType.JPEG,
+        loading_mode: LoadingMode | str = LoadingMode.ASYNC,
+        thread_count: int = 0,
+    ) -> None:
+        """Add a video to the generator."""
+        compression_type = _parse_compression_type(compression_type)
+        loading_mode = _parse_loading_mode(loading_mode)
+        self._generator.add_video(
+            str(video_name),
+            str(video_path),
+            str(video_data_path),
+            str(avatar_data_path),
+            compression_type,
+            loading_mode,
+            thread_count,
+        )
+
+    def process_audio(
+        self, mel_chunk: np.ndarray, video_name: str, frame_idx: int
+    ) -> np.ndarray:
+        """Process audio chunk and return blended frame."""
+        return self._generator.process_audio(
+            mel_chunk.astype(np.float32), str(video_name), frame_idx
+        )
+
+    def get_original_frame(self, video_name: str, frame_idx: int) -> np.ndarray:
+        """Get the original frame."""
+        return self._generator.get_original_frame(str(video_name), frame_idx)
+
+    def get_num_frames(self, video_name: str) -> int:
+        """Get the number of frames in the video."""
+        return self._generator.get_num_frames(str(video_name))
+
+    def is_token_validated(self) -> bool:
+        """Check if the token is validated."""
+        return self._generator.is_token_validated()
+
+    def get_expiration_time(self) -> int:
+        """Get the expiration time of the token."""
+        return self._generator.get_expiration_time()
+
+    @staticmethod
+    def get_runtime_version() -> str:
+        """Get the runtime version."""
+        return _PythonBithumanRuntime.get_runtime_version()
+
+    def request_token(
+        self,
+        api_url: str,
+        api_secret: str,
+        model_path: Optional[str] = None,
+        tags: Optional[str] = None,
+        transaction_id: Optional[str] = None,
+        insecure: bool = False,
+        timeout: float = 30.0,
+    ) -> str:
+        """Request a token from the authentication server."""
+        return self._generator.request_token(
+            api_url,
+            api_secret,
+            model_path,
+            tags,
+            transaction_id,
+            insecure,
+            timeout,
+        )
+
+    def start_token_refresh(
+        self,
+        api_url: str,
+        api_secret: str,
+        model_path: Optional[str] = None,
+        tags: Optional[str] = None,
+        refresh_interval: int = 60,
+        insecure: bool = False,
+        timeout: float = 30.0,
+    ) -> bool:
+        """Start token refresh thread."""
+        # Security check: If token refresh is already running, prevent restart
+        if self.is_token_refresh_running():
+            logger.warning(
+                "Security: Token refresh is already running. "
+                "Cannot restart with different parameters. "
+                "This prevents security bypass attempts."
+            )
+            return False
+
+        # Security check: Verify parameters match initialization parameters if set
+        if hasattr(self, '_initialized_api_secret') and self._initialized_api_secret:
+            if api_secret != self._initialized_api_secret:
+                logger.error(
+                    "Security violation: api_secret does not match initialization parameter. "
+                    "This prevents security bypass attempts."
+                )
+                raise RuntimeError(
+                    "Cannot change api_secret after initialization. "
+                    "This is a security restriction."
+                )
+            if api_url != self._initialized_api_url:
+                logger.error(
+                    "Security violation: api_url does not match initialization parameter. "
+                    "This prevents security bypass attempts."
+                )
+                raise RuntimeError(
+                    "Cannot change api_url after initialization. "
+                    "This is a security restriction."
+                )
+
+        return self._generator.start_token_refresh(
+            api_url,
+            api_secret,
+            model_path,
+            tags,
+            refresh_interval,
+            insecure,
+            timeout,
+        )