@weirdfingers/baseboards 0.6.2 → 0.7.0

package/templates/api/src/boards/generators/implementations/fal/video/wan_25_preview_text_to_video.py

@@ -0,0 +1,208 @@
+"""
+Wan 2.5 Preview text-to-video generator.
+
+A text-to-video generation model that converts text prompts into video content,
+supporting both Chinese and English inputs up to 800 characters.
+
+Based on Fal AI's fal-ai/wan-25-preview/text-to-video model.
+See: https://fal.ai/models/fal-ai/wan-25-preview/text-to-video
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class Wan25PreviewTextToVideoInput(BaseModel):
+    """Input schema for Wan 2.5 Preview text-to-video generation.
+
+    Artifact fields are automatically detected via type introspection
+    and resolved from generation IDs to artifact objects.
+    """
+
+    prompt: str = Field(
+        description="Text prompt for video generation. Supports Chinese and English.",
+        min_length=1,
+        max_length=800,
+    )
+    aspect_ratio: Literal["16:9", "9:16", "1:1"] = Field(
+        default="16:9",
+        description="Aspect ratio of the generated video",
+    )
+    resolution: Literal["480p", "720p", "1080p"] = Field(
+        default="1080p",
+        description="Resolution of the generated video",
+    )
+    duration: Literal[5, 10] = Field(
+        default=5,
+        description="Duration of the generated video in seconds",
+    )
+    audio_url: str | None = Field(
+        default=None,
+        description="URL of background audio (WAV/MP3). Must be 3-30 seconds and max 15MB. "
+        "Audio longer than video is truncated; shorter audio results in silent sections.",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random seed for reproducibility",
+    )
+    enable_safety_checker: bool = Field(
+        default=True,
+        description="Whether to enable safety filtering",
+    )
+    negative_prompt: str | None = Field(
+        default=None,
+        description="Content to avoid in generation",
+        max_length=500,
+    )
+    enable_prompt_expansion: bool = Field(
+        default=True,
+        description="Whether to expand short prompts for improved results. "
+        "Increases processing time but improves quality for short prompts.",
+    )
+
+
+class FalWan25PreviewTextToVideoGenerator(BaseGenerator):
+    """Generator for text-to-video using Wan 2.5 Preview."""
+
+    name = "fal-wan-25-preview-text-to-video"
+    description = (
+        "Fal: Wan 2.5 Preview - Text-to-video generation supporting "
+        "Chinese/English prompts up to 800 characters"
+    )
+    artifact_type = "video"
+
+    def get_input_schema(self) -> type[Wan25PreviewTextToVideoInput]:
+        """Return the input schema for this generator."""
+        return Wan25PreviewTextToVideoInput
+
+    async def generate(
+        self, inputs: Wan25PreviewTextToVideoInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate video using fal.ai Wan 2.5 Preview model."""
+        # Check for API key
+        if not os.getenv("FAL_KEY"):
+            raise ValueError("API configuration invalid. Missing FAL_KEY environment variable")
+
+        # Import fal_client
+        try:
+            import fal_client
+        except ImportError as e:
+            raise ImportError(
+                "fal.ai SDK is required for FalWan25PreviewTextToVideoGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Prepare arguments for fal.ai API
+        arguments: dict = {
+            "prompt": inputs.prompt,
+            "aspect_ratio": inputs.aspect_ratio,
+            "resolution": inputs.resolution,
+            "duration": inputs.duration,
+            "enable_safety_checker": inputs.enable_safety_checker,
+            "enable_prompt_expansion": inputs.enable_prompt_expansion,
+        }
+
+        # Add optional parameters
+        if inputs.audio_url is not None:
+            arguments["audio_url"] = inputs.audio_url
+        if inputs.seed is not None:
+            arguments["seed"] = inputs.seed
+        if inputs.negative_prompt is not None:
+            arguments["negative_prompt"] = inputs.negative_prompt
+
+        # Submit async job
+        handler = await fal_client.submit_async(
+            "fal-ai/wan-25-preview/text-to-video",
+            arguments=arguments,
+        )
+
+        # Store external job ID
+        await context.set_external_job_id(handler.request_id)
+
+        # Stream progress updates
+        from .....progress.models import ProgressUpdate
+
+        event_count = 0
+        async for event in handler.iter_events(with_logs=True):
+            event_count += 1
+            # Sample every 3rd event to avoid spam
+            if event_count % 3 == 0:
+                # Extract logs if available
+                logs = getattr(event, "logs", None)
+                if logs:
+                    # Join log entries into a single message
+                    if isinstance(logs, list):
+                        message = " | ".join(str(log) for log in logs if log)
+                    else:
+                        message = str(logs)
+
+                    if message:
+                        await context.publish_progress(
+                            ProgressUpdate(
+                                job_id=handler.request_id,
+                                status="processing",
+                                progress=50.0,  # Approximate mid-point progress
+                                phase="processing",
+                                message=message,
+                            )
+                        )
+
+        # Get final result
+        result = await handler.get()
+
+        # Extract video from result
+        video_data = result.get("video")
+        if not video_data:
+            raise ValueError("No video returned from fal.ai API")
+
+        video_url = video_data.get("url")
+        if not video_url:
+            raise ValueError("Video missing URL in fal.ai response")
+
+        # Extract video metadata from response or use defaults
+        width = video_data.get("width")
+        height = video_data.get("height")
+        duration = video_data.get("duration")
+        fps = video_data.get("fps")
+
+        # If dimensions not provided, determine based on aspect ratio and resolution
+        if width is None or height is None:
+            resolution_dimensions = {
+                "480p": {"16:9": (854, 480), "9:16": (480, 854), "1:1": (480, 480)},
+                "720p": {"16:9": (1280, 720), "9:16": (720, 1280), "1:1": (720, 720)},
+                "1080p": {"16:9": (1920, 1080), "9:16": (1080, 1920), "1:1": (1080, 1080)},
+            }
+            dims = resolution_dimensions.get(inputs.resolution, {}).get(
+                inputs.aspect_ratio, (1920, 1080)
+            )
+            width, height = dims
+
+        # Store video result
+        artifact = await context.store_video_result(
+            storage_url=video_url,
+            format="mp4",
+            width=width,
+            height=height,
+            duration=float(duration) if duration else float(inputs.duration),
+            fps=fps,
+            output_index=0,
+        )
+
+        return GeneratorResult(outputs=[artifact])
+
+    async def estimate_cost(self, inputs: Wan25PreviewTextToVideoInput) -> float:
+        """Estimate cost for Wan 2.5 Preview generation.
+
+        Pricing information not provided in official documentation.
+        Estimated at $0.10 per 5-second video based on typical video generation costs.
+        Cost scales with duration.
+        """
+        # Base cost per 5-second video
+        base_cost = 0.10
+        # Scale by duration: 5s = 1x, 10s = 2x
+        duration_multiplier = inputs.duration / 5
+        return base_cost * duration_multiplier

package/templates/api/src/boards/generators/implementations/kie/__init__.py

@@ -0,0 +1,11 @@
+"""Kie.ai generator implementations."""
+
+from .image.nano_banana_edit import KieNanoBananaEditGenerator, NanoBananaEditInput
+from .video.veo3 import KieVeo3Generator, KieVeo3Input
+
+__all__ = [
+    "KieNanoBananaEditGenerator",
+    "NanoBananaEditInput",
+    "KieVeo3Generator",
+    "KieVeo3Input",
+]

package/templates/api/src/boards/generators/implementations/kie/base.py

@@ -0,0 +1,316 @@
+"""Base classes for Kie.ai generators.
+
+Provides common functionality shared across all Kie.ai generator implementations,
+including API key validation, HTTP client setup, response validation, and polling logic.
+
+Kie.ai supports two API patterns:
+- Market API: Unified endpoint for 30+ models using /api/v1/jobs endpoints
+- Dedicated API: Model-specific endpoints with custom paths
+"""
+
+import asyncio
+import os
+from abc import abstractmethod
+from typing import Any, ClassVar, Literal
+
+import httpx
+
+from ....progress.models import ProgressUpdate
+from ...base import BaseGenerator, GeneratorExecutionContext
+
+
+class KieBaseGenerator(BaseGenerator):
+    """Base class for all Kie.ai generators with common functionality.
+
+    Provides shared methods for API key management, HTTP requests,
+    response validation, and external job ID storage.
+
+    Subclasses must define:
+    - api_pattern: Either "market" or "dedicated"
+    - model_id: Model identifier (for market) or endpoint path (for dedicated)
+    """
+
+    # Subclasses must define these
+    api_pattern: ClassVar[Literal["market", "dedicated"]]
+    model_id: str
+
+    def _get_api_key(self) -> str:
+        """Get and validate KIE_API_KEY from environment.
+
+        Returns:
+            The API key string
+
+        Raises:
+            ValueError: If KIE_API_KEY is not set
+        """
+        api_key = os.getenv("KIE_API_KEY")
+        if not api_key:
+            raise ValueError("API configuration invalid. Missing KIE_API_KEY environment variable")
+        return api_key
+
+    def _validate_response(self, response: dict[str, Any]) -> None:
+        """Validate standard Kie.ai response structure.
+
+        All Kie.ai APIs return responses with a "code" field where 200 indicates success.
+
+        Args:
+            response: The JSON response from Kie.ai API
+
+        Raises:
+            ValueError: If the response code is not 200
+        """
+        if response.get("code") != 200:
+            error_msg = response.get("msg", "Unknown error")
+            raise ValueError(f"Kie.ai API error: {error_msg}")
+
+    async def _make_request(
+        self,
+        url: str,
+        method: Literal["GET", "POST"],
+        api_key: str,
+        json: dict[str, Any] | None = None,
+        timeout: float = 30.0,
+    ) -> dict[str, Any]:
+        """Make HTTP request to Kie.ai API with standard error handling.
+
+        Args:
+            url: Full URL to request
+            method: HTTP method (GET or POST)
+            api_key: API key for authorization
+            json: Request body for POST requests
+            timeout: Request timeout in seconds
+
+        Returns:
+            The validated JSON response
+
+        Raises:
+            ValueError: If the request fails or returns an error response
+        """
+        async with httpx.AsyncClient() as client:
+            if method == "POST":
+                response = await client.post(
+                    url,
+                    json=json,
+                    headers={
+                        "Authorization": f"Bearer {api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    timeout=timeout,
+                )
+            else:
+                response = await client.get(
+                    url,
+                    headers={"Authorization": f"Bearer {api_key}"},
+                    timeout=timeout,
+                )
+
+            if response.status_code != 200:
+                raise ValueError(
+                    f"Kie.ai API request failed: {response.status_code} {response.text}"
+                )
+
+            result = response.json()
+            self._validate_response(result)
+            return result
+
+    @abstractmethod
+    async def _poll_for_completion(
+        self,
+        task_id: str,
+        api_key: str,
+        context: GeneratorExecutionContext,
+    ) -> dict[str, Any]:
+        """Poll for task completion.
+
+        Subclasses implement this based on their API pattern (Market vs Dedicated).
+
+        Args:
+            task_id: The task ID to poll
+            api_key: API key for authorization
+            context: Generator execution context for progress updates
+
+        Returns:
+            The completed task data containing results
+
+        Raises:
+            ValueError: If polling fails or task fails
+        """
+        pass
+
+
+class KieMarketAPIGenerator(KieBaseGenerator):
+    """Base class for Kie.ai Market API generators.
+
+    Market API is used for 30+ models through a unified endpoint.
+    - Submit: POST /api/v1/jobs/createTask with model parameter
+    - Status: GET /api/v1/jobs/recordInfo?taskId={id}
+    - Status field: "state" with values: "waiting", "pending", "processing", "success", "failed"
+    """
+
+    api_pattern: ClassVar[Literal["market"]] = "market"
+
+    async def _poll_for_completion(
+        self,
+        task_id: str,
+        api_key: str,
+        context: GeneratorExecutionContext,
+        max_polls: int = 120,
+        poll_interval: int = 10,
+    ) -> dict[str, Any]:
+        """Poll Market API for task completion using state field.
+
+        Args:
+            task_id: The task ID to poll
+            api_key: API key for authorization
+            context: Generator execution context for progress updates
+            max_polls: Maximum number of polling attempts (default: 120 = 20 minutes)
+            poll_interval: Seconds between polls (default: 10)
+
+        Returns:
+            The completed task data from the "data" field
+
+        Raises:
+            ValueError: If task fails or times out
+        """
+        status_url = f"https://api.kie.ai/api/v1/jobs/recordInfo?taskId={task_id}"
+
+        async with httpx.AsyncClient() as client:
+            for poll_count in range(max_polls):
+                # Don't sleep on first poll - check status immediately
+                if poll_count > 0:
+                    await asyncio.sleep(poll_interval)
+
+                status_response = await client.get(
+                    status_url,
+                    headers={"Authorization": f"Bearer {api_key}"},
+                    timeout=30.0,
+                )
+
+                if status_response.status_code != 200:
+                    raise ValueError(
+                        f"Status check failed: {status_response.status_code} {status_response.text}"
+                    )
+
+                status_result = status_response.json()
+                self._validate_response(status_result)
+
+                task_data = status_result.get("data", {})
+                state = task_data.get("state")
+
+                if state == "success":
+                    return task_data
+                elif state == "failed":
+                    error_msg = task_data.get("failMsg", "Unknown error")
+                    raise ValueError(f"Generation failed: {error_msg}")
+                elif state not in ["waiting", "pending", "processing", None]:
+                    raise ValueError(
+                        f"Unknown state '{state}' from Kie.ai API. Full response: {status_result}"
+                    )
+
+                # Publish progress
+                progress = min(90, (poll_count / max_polls) * 100)
+                await context.publish_progress(
+                    ProgressUpdate(
+                        job_id=task_id,
+                        status="processing",
+                        progress=progress,
+                        phase="processing",
+                    )
+                )
+            else:
+                timeout_minutes = (max_polls * poll_interval) / 60
+                raise ValueError(f"Generation timed out after {timeout_minutes} minutes")
+
+
+class KieDedicatedAPIGenerator(KieBaseGenerator):
+    """Base class for Kie.ai Dedicated API generators.
+
+    Dedicated APIs have model-specific endpoints with custom paths.
+    - Submit: POST /api/v1/{model}/generate (no model parameter in body)
+    - Status: GET /api/v1/{model}/record-info?taskId={id}
+    - Status field: "successFlag" with values: 0 (processing), 1 (success), 2/3 (failed)
+    """
+
+    api_pattern: ClassVar[Literal["dedicated"]] = "dedicated"
+
+    @abstractmethod
+    def _get_status_url(self, task_id: str) -> str:
+        """Get the status check URL for this specific dedicated API.
+
+        Each dedicated API has its own status endpoint path.
+
+        Args:
+            task_id: The task ID to check status for
+
+        Returns:
+            Full URL for status checking
+        """
+        pass
+
+    async def _poll_for_completion(
+        self,
+        task_id: str,
+        api_key: str,
+        context: GeneratorExecutionContext,
+        max_polls: int = 180,
+        poll_interval: int = 10,
+    ) -> dict[str, Any]:
+        """Poll Dedicated API for task completion using successFlag field.
+
+        Args:
+            task_id: The task ID to poll
+            api_key: API key for authorization
+            context: Generator execution context for progress updates
+            max_polls: Maximum number of polling attempts (default: 180 = 30 minutes)
+            poll_interval: Seconds between polls (default: 10)
+
+        Returns:
+            The completed task data from the "data" field
+
+        Raises:
+            ValueError: If task fails or times out
+        """
+        status_url = self._get_status_url(task_id)
+
+        async with httpx.AsyncClient() as client:
+            for poll_count in range(max_polls):
+                # Don't sleep on first poll - check status immediately
+                if poll_count > 0:
+                    await asyncio.sleep(poll_interval)
+
+                status_response = await client.get(
+                    status_url,
+                    headers={"Authorization": f"Bearer {api_key}"},
+                    timeout=30.0,
+                )
+
+                if status_response.status_code != 200:
+                    raise ValueError(
+                        f"Status check failed: {status_response.status_code} {status_response.text}"
+                    )
+
+                status_result = status_response.json()
+                self._validate_response(status_result)
+
+                task_data = status_result.get("data", {})
+                success_flag = task_data.get("successFlag")
+
+                if success_flag == 1:
+                    return task_data
+                elif success_flag in [2, 3]:
+                    error_msg = task_data.get("errorMsg", "Unknown error")
+                    raise ValueError(f"Generation failed: {error_msg}")
+
+                # Publish progress
+                progress = min(90, (poll_count / max_polls) * 100)
+                await context.publish_progress(
+                    ProgressUpdate(
+                        job_id=task_id,
+                        status="processing",
+                        progress=progress,
+                        phase="processing",
+                    )
+                )
+            else:
+                timeout_minutes = (max_polls * poll_interval) / 60
+                raise ValueError(f"Generation timed out after {timeout_minutes} minutes")

package/templates/api/src/boards/generators/implementations/kie/image/__init__.py

@@ -0,0 +1,3 @@
+from .nano_banana_edit import KieNanoBananaEditGenerator
+
+__all__ = ["KieNanoBananaEditGenerator"]