runapi-seedream 0.1.0__py3-none-any.whl

runapi/seedream/__init__.py

@@ -0,0 +1,24 @@
+"""Seedream client for RunAPI."""
+
+from runapi.core import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    TaskFailedError,
+    TaskTimeoutError,
+    ValidationError,
+)
+
+from .client import SeedreamClient
+
+__all__ = [
+    "SeedreamClient",
+    "AuthenticationError",
+    "RateLimitError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "ValidationError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]

runapi/seedream/client.py

@@ -0,0 +1,29 @@
+"""Seedream client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.edit_image import EditImage
+from .resources.text_to_image import TextToImage
+
+
+class SeedreamClient:
+    """Seedream text-to-image and edit-image client.
+
+    Example::
+
+        client = SeedreamClient(api_key="sk-...")
+        result = client.text_to_image.run(
+            model="seedream-v4-text-to-image", prompt="A neon city street"
+        )
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        resolved_api_key = resolve_api_key(api_key)
+        client_options = ClientOptions(api_key=resolved_api_key, **options)
+        http = client_options.http_client or HttpClient(client_options)
+        self.text_to_image = TextToImage(http)
+        self.edit_image = EditImage(http)

runapi/seedream/contract_gen.py

@@ -0,0 +1,117 @@
+# Code generated by SdkContractGenerator. DO NOT EDIT.
+
+CONTRACT = {
+    "edit-image": {
+        "models": ["seedream-4.5-edit", "seedream-5-lite-edit", "seedream-v4-edit"],
+        "fields_by_model": {
+            "seedream-4.5-edit": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+                    "required": True
+                },
+                "output_count": {
+                    "type": "integer"
+                },
+                "output_quality": {
+                    "enum": ["basic", "high"],
+                    "required": True
+                },
+                "seed": {
+                    "type": "integer"
+                },
+                "source_image_urls": {
+                    "required": True
+                }
+            },
+            "seedream-5-lite-edit": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+                    "required": True
+                },
+                "output_count": {
+                    "type": "integer"
+                },
+                "output_quality": {
+                    "enum": ["basic", "high"],
+                    "required": True
+                },
+                "seed": {
+                    "type": "integer"
+                },
+                "source_image_urls": {
+                    "required": True
+                }
+            },
+            "seedream-v4-edit": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9"]
+                },
+                "output_count": {
+                    "enum": [1, 2, 3, 4, 5, 6],
+                    "type": "integer"
+                },
+                "output_resolution": {
+                    "enum": ["1k", "2k", "4k"]
+                },
+                "seed": {
+                    "type": "integer"
+                },
+                "source_image_urls": {
+                    "required": True
+                }
+            }
+        }
+    },
+    "text-to-image": {
+        "models": ["seedream-4.5-text-to-image", "seedream-5-lite-text-to-image", "seedream-v4-text-to-image"],
+        "fields_by_model": {
+            "seedream-4.5-text-to-image": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+                    "required": True
+                },
+                "output_count": {
+                    "type": "integer"
+                },
+                "output_quality": {
+                    "enum": ["basic", "high"],
+                    "required": True
+                },
+                "seed": {
+                    "type": "integer"
+                }
+            },
+            "seedream-5-lite-text-to-image": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+                    "required": True
+                },
+                "output_count": {
+                    "type": "integer"
+                },
+                "output_quality": {
+                    "enum": ["basic", "high"],
+                    "required": True
+                },
+                "seed": {
+                    "type": "integer"
+                }
+            },
+            "seedream-v4-text-to-image": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9"]
+                },
+                "output_count": {
+                    "enum": [1, 2, 3, 4, 5, 6],
+                    "type": "integer"
+                },
+                "output_resolution": {
+                    "enum": ["1k", "2k", "4k"]
+                },
+                "seed": {
+                    "type": "integer"
+                }
+            }
+        }
+    }
+}

runapi/seedream/resources/__init__.py

@@ -0,0 +1,4 @@
+from .edit_image import EditImage
+from .text_to_image import TextToImage
+
+__all__ = ["TextToImage", "EditImage"]

runapi/seedream/resources/edit_image.py

@@ -0,0 +1,92 @@
+"""Seedream edit-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    LITE_MODELS,
+    V4_MODELS,
+    CompletedEditImageResponse,
+    EditImageResponse,
+)
+
+
+class EditImage(Resource):
+    """Edit images from a prompt and source images with Seedream models."""
+
+    ENDPOINT = "/api/v1/seedream/edit_image"
+
+    RESPONSE_CLASS = EditImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedEditImageResponse
+
+    PROMPT_MAX_LENGTH = 3000
+    V4_PROMPT_MAX_LENGTH = 5000
+    PROMPT_MIN_LENGTH_LITE = 3
+
+    def run(self, **params: Any) -> Any:
+        """Edit an image and poll until it completes.
+
+        Args:
+            **params: image edit parameters (model, ...).
+
+        Returns:
+            The completed (narrowed) image edit response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create an image editing task and return immediately with an id.
+
+        Args:
+            **params: image edit parameters (model, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_params(compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of an image editing task.
+
+        Args:
+            id: The task id returned by ``create``.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        self._validate_contract(CONTRACT["edit-image"], params)
+
+        model = params.get("model")
+
+        prompt = params.get("prompt")
+        if not (isinstance(prompt, str) and prompt):
+            raise ValidationError("prompt is required")
+        max_length = self.V4_PROMPT_MAX_LENGTH if model in V4_MODELS else self.PROMPT_MAX_LENGTH
+        if len(prompt) > max_length:
+            raise ValidationError(f"prompt must be at most {max_length} characters")
+        if model in LITE_MODELS and len(prompt) < self.PROMPT_MIN_LENGTH_LITE:
+            raise ValidationError(
+                f"prompt must be between {self.PROMPT_MIN_LENGTH_LITE} and {self.PROMPT_MAX_LENGTH} characters"
+            )
+
+        if model in V4_MODELS:
+            self._validate_integer(params, "seed")
+
+    @staticmethod
+    def _validate_integer(params: Dict[str, Any], key: str) -> None:
+        value = params.get(key)
+        if value is None:
+            return
+        if isinstance(value, int) and not isinstance(value, bool):
+            return
+        raise ValidationError(f"{key} must be an integer")

runapi/seedream/resources/text_to_image.py

@@ -0,0 +1,104 @@
+"""Seedream text-to-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    LITE_MODELS,
+    V4_MODELS,
+    CompletedTextToImageResponse,
+    TextToImageResponse,
+)
+
+
+class TextToImage(Resource):
+    """Generate images from text prompts with Seedream models."""
+
+    ENDPOINT = "/api/v1/seedream/text_to_image"
+
+    RESPONSE_CLASS = TextToImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedTextToImageResponse
+
+    PROMPT_MAX_LENGTH = 3000
+    V4_PROMPT_MAX_LENGTH = 5000
+    PROMPT_MIN_LENGTH_LITE = 3
+
+    def run(self, **params: Any) -> Any:
+        """Create a text-to-image task and poll until it completes.
+
+        Args:
+            **params: text-to-image parameters (model, ...).
+
+        Returns:
+            The completed (narrowed) text-to-image response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a text-to-image task and return immediately with an id.
+
+        Args:
+            **params: text-to-image parameters (model, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_params(compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a text-to-image task.
+
+        Args:
+            id: The task id returned by ``create``.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        self._validate_contract(CONTRACT["text-to-image"], params)
+
+        model = params.get("model")
+
+        prompt = params.get("prompt")
+        if not (isinstance(prompt, str) and prompt):
+            raise ValidationError("prompt is required")
+        max_length = self.V4_PROMPT_MAX_LENGTH if model in V4_MODELS else self.PROMPT_MAX_LENGTH
+        if len(prompt) > max_length:
+            raise ValidationError(f"prompt must be at most {max_length} characters")
+        if model in LITE_MODELS and len(prompt) < self.PROMPT_MIN_LENGTH_LITE:
+            raise ValidationError(
+                f"prompt must be between {self.PROMPT_MIN_LENGTH_LITE} and {self.PROMPT_MAX_LENGTH} characters"
+            )
+
+        if model in V4_MODELS:
+            self._validate_integer(params, "seed")
+
+        if self._field_present(params, "source_image_urls"):
+            raise ValidationError(f"source_image_urls is not supported for {model}")
+
+    @staticmethod
+    def _field_present(params: Dict[str, Any], key: str) -> bool:
+        value = params.get(key)
+        if value is None:
+            return False
+        if hasattr(value, "__len__"):
+            return len(value) > 0
+        return True
+
+    @staticmethod
+    def _validate_integer(params: Dict[str, Any], key: str) -> None:
+        value = params.get(key)
+        if value is None:
+            return
+        if isinstance(value, int) and not isinstance(value, bool):
+            return
+        raise ValidationError(f"{key} must be an integer")

runapi/seedream/types.py

@@ -0,0 +1,36 @@
+"""Seedream model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+# Model groupings used by bespoke prompt-length selection (per-model rule the
+# contract cannot express). Model membership and field enums are validated by
+# the generated CONTRACT.
+LITE_MODELS = ["seedream-5-lite-text-to-image", "seedream-5-lite-edit"]
+V4_MODELS = ["seedream-v4-text-to-image", "seedream-v4-edit"]
+
+
+class Image(BaseModel):
+    url = optional(str)
+
+
+class TextToImageResponse(TaskResponse):
+    """Seedream image task status response."""
+
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+    images = optional([lambda: Image])
+    error = optional(str)
+
+
+EditImageResponse = TextToImageResponse
+
+
+class CompletedTextToImageResponse(TextToImageResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    images = required([lambda: Image])
+
+
+CompletedEditImageResponse = CompletedTextToImageResponse

runapi_seedream-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: runapi-seedream
+Version: 0.1.0
+Summary: Seedream text-to-image and edit-image client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/seedream
+Project-URL: Documentation, https://runapi.ai/docs#sdk-seedream
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,edit-image,runapi,sdk,seedream,text-to-image
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Seedream API Python SDK for RunAPI
+
+The seedream api Python SDK is the language-specific package for Seedream on RunAPI. Use this seedream api package for text-to-image, image editing, and creative production flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+This seedream api README is the Python package guide inside the public `seedream-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/seedream; for API reference, use https://runapi.ai/docs#seedream; for SDK docs, use https://runapi.ai/docs#sdk-seedream.
+
+## Install
+
+```bash
+pip install runapi-seedream
+```
+
+## Quick start
+
+```python
+from runapi.seedream import SeedreamClient
+
+client = SeedreamClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_image.create(
+    model="seedream-v4-text-to-image",
+    prompt="A precise product render of a glass teapot on white marble",
+    aspect_ratio="16:9",
+    output_resolution="2k",
+    output_count=3,
+)
+status = client.text_to_image.get(task.id)
+
+edit = client.edit_image.create(
+    model="seedream-v4-edit",
+    prompt="Make it golden hour",
+    source_image_urls=["https://example.com/source.jpg"],
+)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task state, and `run` when a script should create and poll until completion:
+
+```python
+result = client.text_to_image.run(
+    model="seedream-v4-text-to-image",
+    prompt="A serene mountain lake at dawn",
+)
+print(result.images[0].url)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.
+
+## Language notes
+
+Pass parameters as keyword arguments and catch the `runapi.seedream` error classes when building image jobs or scripts. The available resources are `text_to_image` for text models and `edit_image` for editing models. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/seedream
+- SDK docs: https://runapi.ai/docs#sdk-seedream
+- Product docs: https://runapi.ai/docs#seedream
+- Pricing and rate limits: https://runapi.ai/models/seedream/v4-text-to-image
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/seedream-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_seedream-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+runapi/seedream/__init__.py,sha256=BVqXWOILYMAKbUM-7nwcZiVieuX-V7R4V5tdMwLnNm0,466
+runapi/seedream/client.py,sha256=QppM6kYDO2FJbQ8NTte8_Vwk1sgCQ-r8RchjY8SmIrA,903
+runapi/seedream/contract_gen.py,sha256=oHsyW03OhP-WyuiP5MTBhwkxn9kNhvDwwj68aNWRTlI,3914
+runapi/seedream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runapi/seedream/types.py,sha256=XmnQuhBuK7wT-FIpxzdrsxds1OK1l5gzftK1CYI1Obo,1050
+runapi/seedream/resources/__init__.py,sha256=cWTZRb2Hewznm9agkhjkcKjEPbJO2YaQOW1fuixLjtw,113
+runapi/seedream/resources/edit_image.py,sha256=RL4iWEB7zIwh06zNm7TpGksGa4MbL4Np2ohW9gRtmtE,2894
+runapi/seedream/resources/text_to_image.py,sha256=bruWUZQIrpmLnZGhDrO8wi3cNnjGDw552sW9IwG1uk0,3331
+runapi_seedream-0.1.0.dist-info/METADATA,sha256=MeQgXNbtgghXIFJLYu6idFpAZ9ilR4IBg5dYuhlgnVg,3106
+runapi_seedream-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+runapi_seedream-0.1.0.dist-info/RECORD,,

runapi_seedream-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any