Merge main into refactor-optionalSettings

Author: Sirsho1997

README.md

@@ -1031,3 +1031,52 @@ asyncio.run(main())
 ```
 
 For more detailed usage and additional examples, please refer to the examples directory.
+
+## Configuring Timeouts
+
+The Runware SDK provides configurable timeout settings for different operations through environment variables. All timeout values are in milliseconds.
+
+### Timeout Configuration
+
+Set environment variables to customize timeout behavior:
+
+```bash
+# Image Operations (milliseconds)
+RUNWARE_IMAGE_INFERENCE_TIMEOUT=300000      # Image generation (default: 5 min)
+RUNWARE_IMAGE_OPERATION_TIMEOUT=120000      # Caption, upscale, background removal (default: 2 min)
+RUNWARE_IMAGE_UPLOAD_TIMEOUT=60000          # Image upload (default: 1 min)
+
+# Video Operations (milliseconds)
+RUNWARE_VIDEO_INITIAL_TIMEOUT=30000         # Initial response wait (default: 30 sec)
+RUNWARE_VIDEO_POLLING_DELAY=3000            # Delay between status checks (default: 3 sec)
+RUNWARE_MAX_POLLS_VIDEO_GENERATION=480      # Max polling attempts (default: 480, ~24 min total)
+
+# Audio Operations (milliseconds)
+RUNWARE_AUDIO_INFERENCE_TIMEOUT=300000      # Audio generation (default: 5 min)
+RUNWARE_AUDIO_POLLING_DELAY=1000            # Delay between status checks (default: 1 sec)
+RUNWARE_MAX_POLLS_AUDIO_GENERATION=240      # Max polling attempts (default: 240, ~4 min total)
+
+# Other Operations (milliseconds)
+RUNWARE_PROMPT_ENHANCE_TIMEOUT=60000        # Prompt enhancement (default: 1 min)
+RUNWARE_WEBHOOK_TIMEOUT=30000               # Webhook acknowledgment (default: 30 sec)
+RUNWARE_TIMEOUT_DURATION=480000             # General operations (default: 8 min)
+```
+
+### Usage Example
+
+```python
+import os
+
+# Configure before importing Runware
+os.environ["RUNWARE_VIDEO_POLLING_DELAY"] = "5000"  # 5 seconds between checks
+os.environ["RUNWARE_MAX_POLLS_VIDEO_GENERATION"] = "600"  # Allow up to 50 minutes
+
+from runware import Runware
+
+async def main():
+    runware = Runware(api_key=os.getenv("RUNWARE_API_KEY"))
+    await runware.connect()
+    # Your code here
+```
+
+**Note:** For long-running video operations, consider using webhooks or `skipResponse=True` to avoid timeout issues with extended generation times.

runware/base.py

@@ -40,12 +40,8 @@
     IVideoCaption,
     IVideoToText,
     IVideoBackgroundRemoval,
-    IVideoBackgroundRemovalInputs,
-    IVideoBackgroundRemovalSettings,
     IVideoUpscale,
-    IVideoUpscaleInputs,
     IVideoInference,
-    IVideoInputs,
     IVideoAdvancedFeatures,
     IAcceleratorOptions,
     IAudio,
@@ -73,7 +69,7 @@
     removeListener,
     LISTEN_TO_IMAGES_KEY,
     isLocalFile,
-    process_image, delay,
+    process_image,
     createAsyncTaskResponse,
     VIDEO_INITIAL_TIMEOUT,
     VIDEO_POLLING_DELAY,
@@ -83,13 +79,15 @@
     PROMPT_ENHANCE_TIMEOUT,
     IMAGE_UPLOAD_TIMEOUT,
     AUDIO_INFERENCE_TIMEOUT,
+    AUDIO_POLLING_DELAY,
+    MAX_POLLS_AUDIO_GENERATION,
+    MAX_POLLS_VIDEO_GENERATION,
 )
 
 # Configure logging
 configure_logging(log_level=logging.CRITICAL)
 
 logger = logging.getLogger(__name__)
-MAX_POLLS_VIDEO_GENERATION = int(os.environ.get("RUNWARE_MAX_POLLS_VIDEO_GENERATION", 480))
 
 
 class RunwareBase:
@@ -1474,13 +1472,19 @@ async def ensureConnection(self) -> None:
 
         try:
             if self._invalidAPIkey:
+                if not self._reconnection_manager._had_successful_auth:
+                    raise ConnectionError(self._invalidAPIkey)
+
                 circuit_state = self._reconnection_manager.get_state()
                 if circuit_state == ConnectionState.CIRCUIT_OPEN:
                     raise ConnectionError(self._invalidAPIkey)
 
             if not isConnected:
                 await self.connect()
 
+                if self._invalidAPIkey and not self._reconnection_manager._had_successful_auth:
+                    raise ConnectionError(self._invalidAPIkey)
+
         except Exception as e:
             raise ConnectionError(
                 self._invalidAPIkey
@@ -2131,7 +2135,7 @@ async def _pollVideoResults(self, task_uuid: str, number_results: int, response_
                 if poll_count >= MAX_POLLS_VIDEO_GENERATION - 1:
                     raise e
 
-            await delay(VIDEO_POLLING_DELAY)
+            await asyncio.sleep(VIDEO_POLLING_DELAY / 1000)
 
         # Different timeout messages based on response type
         timeout_msg = "Timed out"
@@ -2236,7 +2240,7 @@ async def _handleInitialAudioResponse(self, task_uuid: str, number_results: int)
             return [response] if response else []
         else:
             # Multiple results - use polling
-            return await self._pollForAudioResults(task_uuid, number_results)
+            return await self._pollAudioResults(task_uuid, number_results)
 
     async def _waitForAudioCompletion(self, task_uuid: str) -> Optional[IAudio]:
         lis = self.globalListener(taskUUID=task_uuid)
@@ -2274,34 +2278,36 @@ async def check(resolve: Callable, reject: Callable, *args: Any) -> bool:
             lis["destroy"]()
             raise e
 
-    async def _pollForAudioResults(self, task_uuid: str, number_results: int) -> List[IAudio]:
+    async def _pollAudioResults(self, task_uuid: str, number_results: int) -> List[IAudio]:
         completed_results = []
         lis = self.globalListener(taskUUID=task_uuid)
 
         try:
-            while len(completed_results) < number_results:
-                responses = self._globalMessages.get(task_uuid, [])
-                if not isinstance(responses, list):
-                    responses = [responses] if responses else []
+            for poll_count in range(MAX_POLLS_AUDIO_GENERATION):
+                async with self._messages_lock:
+                    responses = self._globalMessages.get(task_uuid, [])
+                    if not isinstance(responses, list):
+                        responses = [responses] if responses else []
 
                 processed_responses = self._processAudioPollingResponse(responses)
                 completed_results.extend(processed_responses)
 
                 if len(completed_results) >= number_results:
                     break
 
-                await asyncio.sleep(1)  # Poll every second
-
-            # Clean up
-            if task_uuid in self._globalMessages:
-                del self._globalMessages[task_uuid]
-            lis["destroy"]()
+                if poll_count >= MAX_POLLS_AUDIO_GENERATION - 1:
+                    raise RunwareAPIError(
+                        {"message": f"Audio generation timeout after {MAX_POLLS_AUDIO_GENERATION} polls"})
 
-            return [self._createAudioFromResponse(response) for response in completed_results[:number_results]]
+                await asyncio.sleep(AUDIO_POLLING_DELAY / 1000)
 
-        except Exception as e:
+        finally:
             lis["destroy"]()
-            raise e
+            async with self._messages_lock:
+                if task_uuid in self._globalMessages:
+                    del self._globalMessages[task_uuid]
+
+        return [self._createAudioFromResponse(response) for response in completed_results[:number_results]]
 
     def _processAudioPollingResponse(self, responses: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         completed_results = []

runware/utils.py

@@ -48,72 +48,104 @@
     "REQUEST_IMAGES": 2,
 }
 
-
+# WebSocket connection health check timeout (milliseconds)
+# Maximum time to wait for pong response after sending ping
+# Used in: server.heartBeat() to detect connection loss
 PING_TIMEOUT_DURATION = 10000
+
+# WebSocket ping interval (milliseconds)
+# How often to send ping messages to keep connection alive
+# Used in: server.heartBeat() for periodic health checks
 PING_INTERVAL = 5000
 
+# Image generation timeout (milliseconds)
+# Maximum time to wait for image generation completion (imageInference, photoMaker)
+# Used in: photoMaker(), getSimililarImage() for waiting image generation results
 IMAGE_INFERENCE_TIMEOUT = int(os.environ.get(
     "RUNWARE_IMAGE_INFERENCE_TIMEOUT",
     300000
 ))
 
+# Image operation timeout (milliseconds)
+# Maximum time to wait for image operations (caption, background removal, upscale)
+# Used in: imageCaption(), imageBackgroundRemoval(), imageUpscale()
 IMAGE_OPERATION_TIMEOUT = int(os.environ.get(
     "RUNWARE_IMAGE_OPERATION_TIMEOUT",
     120000
 ))
 
+# Image upload timeout (milliseconds)
+# Maximum time to wait for image upload to complete
+# Used in: uploadImage() for uploading local images or base64 data
 IMAGE_UPLOAD_TIMEOUT = int(os.environ.get(
     "RUNWARE_IMAGE_UPLOAD_TIMEOUT",
     60000
 ))
 
-VIDEO_INFERENCE_TIMEOUT = int(os.environ.get(
-    "RUNWARE_VIDEO_INFERENCE_TIMEOUT",
-    600000
-))
-
+# Video initial response timeout (milliseconds)
+# Maximum time to wait for initial video generation response or polling response
+# Used in: _handleInitialVideoResponse(), _sendPollRequest()
 VIDEO_INITIAL_TIMEOUT = int(os.environ.get(
     "RUNWARE_VIDEO_INITIAL_TIMEOUT",
     30000
 ))
 
+# Video polling delay (milliseconds)
+# Delay between consecutive polling requests for video generation status
+# Used in: _pollVideoResults() for checking video generation progress
 VIDEO_POLLING_DELAY = int(os.environ.get(
     "RUNWARE_VIDEO_POLLING_DELAY",
-    3
-))
-
-VIDEO_OPERATION_TIMEOUT = int(os.environ.get(
-    "RUNWARE_VIDEO_OPERATION_TIMEOUT",
-    120000
+    3000
 ))
 
+# Audio generation timeout (milliseconds)
+# Maximum time to wait for audio generation completion
+# Used in: _waitForAudioCompletion() for single audio generation
 AUDIO_INFERENCE_TIMEOUT = int(os.environ.get(
     "RUNWARE_AUDIO_INFERENCE_TIMEOUT",
     300000
 ))
 
-AUDIO_OPERATION_TIMEOUT = int(os.environ.get(
-    "RUNWARE_AUDIO_OPERATION_TIMEOUT",
-    120000
+# Audio polling delay (milliseconds)
+# Delay between consecutive polling requests for audio generation status
+# Used in: _pollForAudioResults() for checking audio generation progress
+AUDIO_POLLING_DELAY = int(os.environ.get(
+    "RUNWARE_AUDIO_POLLING_DELAY",
+    1000
 ))
 
+# Prompt enhancement timeout (milliseconds)
+# Maximum time to wait for prompt enhancement completion
+# Used in: promptEnhance() for enhancing text prompts
 PROMPT_ENHANCE_TIMEOUT = int(os.environ.get(
     "RUNWARE_PROMPT_ENHANCE_TIMEOUT",
     60000
 ))
 
+# Webhook acknowledgment timeout (milliseconds)
+# Maximum time to wait for webhook task acknowledgment
+# Used in: videoCaption(), videoBackgroundRemoval(), videoUpscale() when webhook is provided
 WEBHOOK_TIMEOUT = int(os.environ.get(
     "RUNWARE_WEBHOOK_TIMEOUT",
     30000
 ))
 
-POLLING_INTERVAL = int(os.environ.get("RUNWARE_POLLING_INTERVAL", 1000))
-
+# Default timeout duration (milliseconds)
+# Maximum time to wait for general operations (model upload, model search, media upload)
+# Used in: RunwareBase.__init__(), uploadMedia(), modelUpload(), modelSearch()
 TIMEOUT_DURATION = int(os.environ.get(
     "RUNWARE_TIMEOUT_DURATION",
     480000
 ))
+# Maximum polling attempts for video generation
+# Number of polling iterations before timing out video generation
+# Used in: _pollVideoResults() for video generation status checks
+MAX_POLLS_VIDEO_GENERATION = int(os.environ.get("RUNWARE_MAX_POLLS_VIDEO_GENERATION", 480))
 
+# Maximum polling attempts for audio generation
+# Number of polling iterations before timing out audio generation
+# Used in: _pollAudioResults() for audio generation status checks
+MAX_POLLS_AUDIO_GENERATION = int(os.environ.get("RUNWARE_MAX_POLLS_AUDIO_GENERATION", 240))
 
 class LISTEN_TO_IMAGES_KEY:
     REQUEST_IMAGES = "REQUEST_IMAGES"
@@ -874,4 +906,4 @@ async def process_image(
         return image.imageUUID
     if isLocalFile(image) and not image.startswith("http"):
         return await fileToBase64(image)
-    return image
+    return image