Skip to content

OpenSenseNova/SenseNova-Skills / skills/sn-image-base

sn-image-base

Verified

Base-layer skill for the SenseNova-Skills project, providing low-level APIs for image generation, recognition (VLM), and text optimization (LLM). This skill does not preprocess inputs; it only calls backend services and returns results. This skill is not user-facing and is intended for upper-layer skills only.

FileKindSize
.gitattributesother219 B
.gitignoreother4.3 KB
README.mdmarkdown10.7 KB
README_CN.mdmarkdown10.4 KB
SKILL.mdskill md13.0 KB
references/api_spec.mdmarkdown14.0 KB
requirements.txtmanifest50 B
scripts/.python-versionother4 B
scripts/extract_json.pyscript3.6 KB
scripts/pyproject.tomlmanifest339 B
scripts/ruff.tomlconfig730 B
scripts/sn_agent_runner.pyscript25.1 KB
scripts/sn_image_base/__init__.pyscript24 B
scripts/sn_image_base/configs.pyscript12.5 KB
scripts/sn_image_base/exceptions.pyscript1.2 KB
scripts/sn_image_base/generation/__init__.pyscript358 B
scripts/sn_image_base/generation/atlas_cloud.pyscript9.6 KB
scripts/sn_image_base/generation/core/__init__.pyscript412 B
scripts/sn_image_base/generation/core/client_base.pyscript2.5 KB
scripts/sn_image_base/generation/nano_banana.pyscript11.6 KB
scripts/sn_image_base/generation/openai_image.pyscript12.3 KB
scripts/sn_image_base/generation/sensenova.pyscript19.5 KB
scripts/sn_image_base/llm/__init__.pyscript215 B
scripts/sn_image_base/llm/anthropic_adapter.pyscript5.0 KB
scripts/sn_image_base/llm/chat_completions_adapter.pyscript9.7 KB
scripts/sn_image_base/llm/llm_adapter.pyscript1.8 KB
scripts/sn_image_base/utils/__init__.pyscript0 B
scripts/sn_image_base/utils/error_utils.pyscript7.3 KB
scripts/sn_image_base/utils/httpx_client.pyscript7.0 KB
scripts/sn_image_base/vlm/__init__.pyscript100 B
scripts/sn_image_base/vlm/utils.pyscript3.0 KB
scripts/sn_image_base/vlm/vlm_adapter.pyscript2.1 KB
scripts/tests/test_atlas_cloud.pyscript6.9 KB
tests/conftest.pyscript375 B
tests/test_configs_env_fallthrough.pyscript2.8 KB

scripts/sn_image_base/generation/sensenova.py

View on GitHub
from __future__ import annotations

import os
import tempfile
import time
from pathlib import Path
from typing import TYPE_CHECKING, Any, Literal
from urllib.parse import urlparse

import httpx
from PIL import Image
from typing_extensions import override

from sn_image_base.configs import global_configs, is_valid_base_url
from sn_image_base.exceptions import InvalidBaseUrlError, MissingApiKeyError
from sn_image_base.generation.core import ensure_output_path
from sn_image_base.generation.core.client_base import (
    DEFAULT_HTTP_REQUEST_TIMEOUT,
    DEFAULT_MAX_CONNECTIONS,
    T2IBaseClient,
)
from sn_image_base.utils.error_utils import U1HttpErrorBase
from sn_image_base.vlm.utils import image_to_data_url

if TYPE_CHECKING:
    from collections.abc import Sequence

DEFAULT_RESOLUTION: Literal["1K", "2K", "4K"] = "2K"
DEFAULT_ASPECT_RATIO = "16:9"
DEFAULT_POLL_INTERVAL = 5.0
OUTPUT_DIR = Path("/tmp/openclaw-sn-image")
U15_LITE_MODEL = "sensenova-u1.5-lite"


IMAGE_GEN_ENDPOINT = "/images/generations"
IMAGE_EDIT_ENDPOINT = "/images/edits"


def _normalize_edit_image(image: str) -> str:
    """Return an edit image as a URL or data URL accepted by SenseNova."""
    if image.startswith("data:image/") and ";base64," in image:
        return image
    parsed = urlparse(image)
    if parsed.scheme in {"http", "https"} and parsed.netloc:
        return image
    return image_to_data_url(image)


class SensenovaText2ImageClient(T2IBaseClient):
    """Async client for Sensenova text-to-image API."""

    def __init__(
        self,
        api_key: str,
        base_url: str | None = None,
        *,
        model: str | None = None,
        max_connections: int = DEFAULT_MAX_CONNECTIONS,
        timeout: float = DEFAULT_HTTP_REQUEST_TIMEOUT,
        ssl_verify: bool = True,
        **kwargs: Any,
    ) -> None:
        """Initialize the SensenovaText2ImageClient.

        Args:
            api_key (str):
                API key for authentication.
            base_url (str | None, optional):
                API base URL. If None, reads from SN_IMAGE_GEN_BASE_URL env var.
            model (str | None, optional):
                Model name. If None, reads from SN_IMAGE_GEN_MODEL env var.
            max_connections (int, optional):
                Maximum number of connections. Defaults to 100.
            timeout (float, optional):
                Total timeout in seconds for HTTP requests.
                Defaults to DEFAULT_HTTP_REQUEST_TIMEOUT.
            ssl_verify (bool, optional):
                If True, enable TLS verification. Defaults to True.
        """
        api_key = api_key or global_configs.SN_IMAGE_GEN_API_KEY
        if not api_key:
            raise MissingApiKeyError(
                "API key is missing: {}".format(
                    global_configs.get_env_var_help("SN_IMAGE_GEN_API_KEY")
                )
            )
        base_url = base_url or global_configs.SN_IMAGE_GEN_BASE_URL
        if not base_url:
            raise InvalidBaseUrlError(
                "Base URL is missing: {}".format(
                    global_configs.get_env_var_help("SN_IMAGE_GEN_BASE_URL")
                )
            )
        if not is_valid_base_url(base_url):
            raise InvalidBaseUrlError(
                f"Base URL is not a valid base URL: {base_url}. "
                f"Try setting environment variable(s): {global_configs.get_env_var_help('SN_IMAGE_GEN_BASE_URL')}"
            )
        super().__init__(
            api_key=api_key,
            base_url=base_url,
            model=model,
            max_connections=max_connections,
            timeout=timeout,
            ssl_verify=ssl_verify,
            **kwargs,
        )

    @override
    async def generate(
        self,
        prompt: str,
        negative_prompt: str = "",
        *,
        model: str | None = None,
        image_size: Literal["1K", "2K", "4K"] = DEFAULT_RESOLUTION,
        aspect_ratio: str = DEFAULT_ASPECT_RATIO,
        output_path: Path | None = None,
        **kwargs: Any,
    ) -> dict:
        """Generate an image from text prompt.

        Args:
            prompt (str):
                Text prompt for image generation.
            negative_prompt (str, optional):
                Negative prompt. Defaults to "".
            model (str | None, optional):
                Model name override. Defaults to None.
            image_size (str, optional):
                Image size preset ("1K", "2K", "4K"). Defaults to DEFAULT_RESOLUTION.
            aspect_ratio (str, optional):
                Aspect ratio (e.g. "16:9", "1:1"). Defaults to DEFAULT_ASPECT_RATIO.
            output_path (Path | None, optional):
                Output path for the generated image. Defaults to None.
            **kwargs:
                Additional arguments reserved for backend compatibility.

        Returns:
            dict:
                On success, keys: status, output (path), message. On failure,
                keys: status, error_type, error.
        """
        model = model or self.model or global_configs.SN_IMAGE_GEN_MODEL
        # Normalize image_size to uppercase for NanoBanana API
        image_size = image_size.upper()  # type: ignore[assignment]
        output_format = "png"
        size = self._resolve_size(image_size, aspect_ratio, model=model)
        payload = self.build_payload(
            prompt=prompt,
            model=model,
            size=size,
            aspect_ratio=aspect_ratio,
            output_format=output_format,
        )
        return await self._request_and_save(
            payload, IMAGE_GEN_ENDPOINT, output_path, output_format, "t2i"
        )

    async def edit(
        self,
        prompt: str,
        images: Sequence[str],
        *,
        model: str | None = None,
        output_path: Path | None = None,
    ) -> dict:
        """Edit one or more reference images with SenseNova U1.5 Lite."""
        model = model or self.model or global_configs.SN_IMAGE_GEN_MODEL
        if model.lower() != U15_LITE_MODEL:
            raise ValueError(
                f"SenseNova image editing requires model {U15_LITE_MODEL!r}; got {model!r}."
            )
        if not images:
            raise ValueError("At least one reference image is required.")
        payload = {
            "model": model,
            "images": [{"image_url": _normalize_edit_image(image)} for image in images],
            "prompt": prompt,
            "n": 1,
            "size": "auto",
            "watermark": False,
            "prompt_extend": True,
            "response_format": "url",
        }
        return await self._request_and_save(
            payload, IMAGE_EDIT_ENDPOINT, output_path, "png", "edit"
        )

    async def _request_and_save(
        self,
        payload: dict[str, Any],
        endpoint: str,
        output_path: Path | None,
        output_format: str,
        filename_prefix: str,
    ) -> dict:
        headers = self.headers
        if output_path is None:
            OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
            timestamp = time.strftime("%Y%m%d_%H%M%S")
            output_path = OUTPUT_DIR / f"{filename_prefix}_{timestamp}.png"
        output_path = ensure_output_path(output_path)
        client = await self._get_client()
        try:
            create_response = await client.post(
                f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}",
                json=payload,
                headers=headers,
            )
            data = self.parse_response(create_response)
        except U1HttpErrorBase as exc:
            details = exc.detail or ""
            field_name = "SN_IMAGE_GEN_BASE_URL" if exc.code == 404 else None
            field_name = "SN_IMAGE_GEN_API_KEY" if exc.code == 401 else field_name
            if field_name is not None:
                field_hint = global_configs.get_annotated_field(field_name)
                env_names = (
                    list(field_hint.env_names) if field_hint and field_hint.env_names else []
                )
                if env_names:
                    if len(env_names) == 1:
                        details += f"\nIs the environment variable `{env_names[0]}` set correctly?"
                    else:
                        env_names_str = ", ".join(f"`{name}`" for name in env_names)
                        details += (
                            "\nIs any of the following environment variable(s) set correctly: "
                            f"{env_names_str}?"
                        )
            return {
                "status": "failed",
                "error_type": type(exc).__name__,
                "error": f"HTTP {exc.code}: {exc.message}" + (f"\n{details}" if details else ""),
            }
        try:
            images_urls: list[str] = data["images_urls"]
            if not images_urls:
                return {
                    "status": "failed",
                    "error_type": "EmptyResponse",
                    "error": "No image generated from the model",
                }
            saved_path = await download_image(
                url=images_urls[-1],
                save_path=output_path.with_suffix(f".{output_format}"),
            )
            return {
                "status": "ok",
                "output": str(saved_path),
                "message": "Image generated successfully",
            }
        except httpx.HTTPStatusError as exc:
            return {
                "status": "failed",
                "error_type": type(exc).__name__,
                "error": f"HTTP {exc.response.status_code}: {exc.response.text}",
            }
        except (httpx.HTTPError, OSError, ValueError) as exc:
            return {"status": "failed", "error_type": type(exc).__name__, "error": str(exc)}

    @property
    @override
    def api_key(self) -> str:
        api_key = self._api_key or global_configs.SN_IMAGE_GEN_API_KEY
        if not api_key:
            raise ValueError(
                "API key is missing: {}".format(
                    global_configs.get_env_var_help("SN_IMAGE_GEN_API_KEY")
                )
            )
        return api_key

    @property
    @override
    def base_url(self) -> str:
        base_url = self._base_url or global_configs.SN_IMAGE_GEN_BASE_URL
        if not base_url:
            raise ValueError(
                "Base URL is missing: {}".format(
                    global_configs.get_env_var_help("SN_IMAGE_GEN_BASE_URL")
                )
            )
        if not is_valid_base_url(base_url):
            raise ValueError(
                f"Base URL is not a valid base URL: {base_url}. "
                f"Try setting environment variable(s): {global_configs.get_env_var_help('SN_IMAGE_GEN_BASE_URL')}"
            )
        return base_url

    @override
    def get_api_url(self, _model: str | None = None) -> str:
        base_url = self.base_url.rstrip("/")
        path = IMAGE_GEN_ENDPOINT.lstrip("/")
        api_url = f"{base_url}/{path}"
        return api_url

    @override
    def build_payload(
        self,
        prompt: str,
        model: str,
        *,
        size: str | None = None,
        modalities: Sequence[str] = ("text", "image"),
        output_format: Literal["png"] = "png",
        response_format: Literal["url"] = "url",
        **kwargs: Any,
    ) -> dict[str, Any]:
        """Build the payload for the SenseNova image-generation endpoint.

        Args:
            prompt (str): The prompt to generate an image for.
            model (str): The model to use for generation.
            size (str | None): Pixel size string (for example, "1920x1920").
            modalities (Sequence[str]): Reserved for compatibility; currently not sent.
            output_format (Literal["png"]): The output format of the image. Defaults to "png".
            response_format (Literal["url"]): The response format of the image. Defaults to "url".
            **kwargs (Any, optional): Additional parameters to pass to the API.

        Example:
        {
            "model": "sensenova-u1.5-lite",
            "prompt": "A cat wearing a hat",
            "size": "1024x1024",
            "response_format": "url",
            "output_format": "png",
        }
        """
        payload = {
            "model": model,
            "prompt": prompt,
            # "modalities": modalities,
            "size": size,
            # "n": 1,
            "response_format": response_format,
            "output_format": output_format,
            "watermark": False,
            **kwargs,
        }
        return payload

    @property
    @override
    def headers(self) -> dict[str, str]:
        if not self.api_key:
            raise MissingApiKeyError(
                "API key is missing: {}".format(
                    global_configs.get_env_var_help("SN_IMAGE_GEN_API_KEY")
                )
            )
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }

    @classmethod
    def _resolve_size(
        cls,
        resolution: Literal["1K", "2K", "4K"] | str | None = None,
        aspect_ratio: ASPECT_RATIO_LITERALS | str | None = None,
        *,
        model: str | None = None,
    ) -> str | None:
        """Convert (resolution, aspect_ratio) to a pixel size string.

        If aspect_ratio is None, returns the resolution as-is (e.g. "1K").
        """
        if not resolution and not aspect_ratio:
            return None
        resolution = resolution or "2K"
        aspect_ratio = aspect_ratio or "1:1"
        if resolution == "1K":
            buckets = BUCKETS_1K
        elif resolution == "2K":
            buckets = BUCKETS_2K
        elif resolution == "4K" and (model or "").lower() == U15_LITE_MODEL:
            buckets = BUCKETS_4K
        else:
            # U1 Fast only supports 1K / 2K. U1.5 Lite is the only SenseNova
            # model currently supporting native 4K output.
            raise ValueError(
                f"image-size {resolution!r} is not supported by the SenseNova image backend "
                f"for model {model or 'unknown'!r} (supported: 1K, 2K; U1.5 Lite also supports 4K)."
            )
        try:
            ws, _, hs = aspect_ratio.strip().partition(":")
            width = int(ws)
            height = int(hs)
            ratio = width / height
        except Exception as e:
            raise ValueError(f"Invalid aspect ratio: {aspect_ratio!r}") from e
        if ratio > 16 / 9:
            raise ValueError(f"Aspect ratio {aspect_ratio!r} is too wide. Maximum is 16:9")
        if ratio < 9 / 21:
            raise ValueError(f"Aspect ratio {aspect_ratio!r} is too high. Maximum is 9:21")
        w, h = _find_nearest_aspect_ratio(ratio, buckets)
        return f"{w}x{h}"

    @override
    def parse_response(self, response: httpx.Response) -> dict:
        """Parse the response from the SenseNova image-generation endpoint.

        Example response data:

        ```json
        {
            "data": [{
                "url": "https://cdn.sensenova.dev/gen/..."
            }]
        }
        ```

        Args:
            response: The HTTP response from the SenseNova image-generation endpoint.

        Returns:
            dict: Parsed data with key ``images_urls``.
        """
        raw_data = super().parse_response(response)

        images_urls: list[str] = []
        for item in raw_data.get("data", []):
            url = item.get("url")
            if isinstance(url, str) and url:
                images_urls.append(url)
        return {"images_urls": images_urls}


async def download_image(
    url: str,
    save_path: Path,
    timeout: float = DEFAULT_HTTP_REQUEST_TIMEOUT,
) -> Path:
    """Download an image from a URL.

    Args:
        url: The URL of the image to download.
        timeout: The timeout for the request.

    Returns:
        Path: The path to the downloaded image file.
    """
    save_path.parent.mkdir(parents=True, exist_ok=True)
    temp_path: Path | None = None
    bytes_written = 0
    expected_length: int | None = None
    try:
        with tempfile.NamedTemporaryFile(
            dir=save_path.parent,
            prefix=f".{save_path.name}.",
            suffix=".tmp",
            delete=False,
        ) as temp_file:
            temp_path = Path(temp_file.name)
            async with httpx.AsyncClient(timeout=timeout) as client:
                async with client.stream("GET", url) as response:
                    response.raise_for_status()
                    content_length = response.headers.get("content-length")
                    if content_length is not None:
                        expected_length = int(content_length)
                    async for chunk in response.aiter_bytes():
                        bytes_written += len(chunk)
                        temp_file.write(chunk)
            temp_file.flush()
            os.fsync(temp_file.fileno())

        if expected_length is not None and bytes_written != expected_length:
            raise OSError(
                f"Downloaded image is incomplete: got {bytes_written} bytes, "
                f"expected {expected_length} bytes"
            )

        assert temp_path is not None
        _validate_image_file(temp_path)
        temp_path.replace(save_path)
        return save_path
    except Exception:
        if temp_path is not None:
            temp_path.unlink(missing_ok=True)
        raise


def _validate_image_file(image_path: Path) -> None:
    """Verify that the downloaded image can be decoded completely."""
    with Image.open(image_path) as image:
        image.verify()
    with Image.open(image_path) as image:
        image.load()


def mime_type_to_suffix(mime_type: str) -> str:
    """Convert MIME type to file suffix.

    Args:
        mime_type: MIME type.

    Returns:
        str: File suffix.
    """
    if mime_type == "image/jpeg":
        return ".jpg"
    elif mime_type == "image/png":
        return ".png"
    elif mime_type == "image/webp":
        return ".webp"
    else:
        return ".png"


ASPECT_RATIO_LITERALS = Literal[
    "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "1:1", "16:9", "9:16", "9:21"
]
BUCKETS_1K: dict[ASPECT_RATIO_LITERALS, tuple[int, int]] = {
    "2:3": (1088, 1632),
    "3:2": (1632, 1088),
    "3:4": (1152, 1536),
    "4:3": (1536, 1152),
    "4:5": (1184, 1472),
    "5:4": (1472, 1184),
    "1:1": (1344, 1344),
    "16:9": (1792, 992),
    "9:16": (992, 1792),
    "9:21": (864, 2048),
}
BUCKETS_2K: dict[ASPECT_RATIO_LITERALS, tuple[int, int]] = {
    "2:3": (1664, 2496),
    "3:2": (2496, 1664),
    "3:4": (1760, 2368),
    "4:3": (2368, 1760),
    "4:5": (1824, 2272),
    "5:4": (2272, 1824),
    "1:1": (2048, 2048),
    "16:9": (2752, 1536),
    "9:16": (1536, 2752),
    "9:21": (1344, 3136),
}
BUCKETS_4K: dict[ASPECT_RATIO_LITERALS, tuple[int, int]] = {
    "2:3": (2731, 4096),
    "3:2": (4096, 2731),
    "3:4": (3072, 4096),
    "4:3": (4096, 3072),
    "4:5": (3277, 4096),
    "5:4": (4096, 3277),
    "1:1": (4096, 4096),
    "16:9": (4096, 2304),
    "9:16": (2304, 4096),
    "9:21": (1755, 4096),
}


def _find_nearest_aspect_ratio(
    ratio: float,
    buckets: dict[ASPECT_RATIO_LITERALS, tuple[int, int]],
) -> tuple[int, int]:
    wh_pairs = sorted(
        buckets.values(),
        key=lambda wh: abs(wh[0] / wh[1] - ratio),
    )
    return wh_pairs[0]


if __name__ == "__main__":
    import asyncio

    async def main_async():
        client = SensenovaText2ImageClient(
            api_key=global_configs.SN_IMAGE_GEN_API_KEY,
            base_url=global_configs.SN_IMAGE_GEN_BASE_URL,
        )

        result = await client.generate(
            prompt="A cat wearing a hat",
            image_size="1K",
            aspect_ratio="16:9",
        )
        print(result)

    asyncio.run(main_async())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall