hiapi-seedance 0.1.0__tar.gz

hiapi_seedance-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.env
+.env.*
+!.env.example

hiapi_seedance-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hiapi_seedance-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: hiapi-seedance
+Version: 0.1.0
+Summary: Python SDK for Seedance 2.5 and Seedance video generation through the HiAPI unified task API.
+Project-URL: Homepage, https://www.hiapi.ai/en?utm_source=github&utm_medium=pyproject&utm_campaign=hiapi-seedance-python
+Project-URL: Documentation, https://docs.hiapi.ai/?utm_source=github&utm_medium=pyproject&utm_campaign=hiapi-seedance-python
+Project-URL: Source, https://github.com/HiAPIAI/hiapi-seedance-python
+Author-email: HiAPI <support@hiapi.ai>
+License: MIT
+License-File: LICENSE
+Keywords: ai video generation,hiapi,image to video api,seedance,seedance 2.5,seedance 2.5 api,seedance python sdk,text to video api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HiAPI Seedance Python SDK
+
+Python SDK for **Seedance 2.5 API**, **Seedance text-to-video**, **Seedance image-to-video**, and Seedance video editing through the HiAPI unified task API.
+
+[![PyPI](https://img.shields.io/badge/pip-hiapi--seedance-f97316)](https://pypi.org/project/hiapi-seedance/) [![HiAPI](https://img.shields.io/badge/HiAPI-One%20API%2C%20All%20AI%20Models-111827)](https://www.hiapi.ai/en?utm_source=github&utm_medium=readme&utm_campaign=hiapi-seedance-python) [![Docs](https://img.shields.io/badge/API%20Docs-docs.hiapi.ai-111827)](https://docs.hiapi.ai/?utm_source=github&utm_medium=readme&utm_campaign=hiapi-seedance-python)
+
+Use this SDK when you want a small Python client focused on AI video generation:
+
+- **Seedance 2.5 API access** through HiAPI's `/v1/tasks` endpoint.
+- **Text-to-video** with `client.text_to_video(...)`.
+- **Image-to-video** with `client.image_to_video(...)`.
+- **Video editing** with `client.video_edit(...)`.
+- **Async task polling** built in: submit, poll, and read the output URL.
+- **Zero runtime dependencies**: standard library only.
+
+## Install
+
+```bash
+pip install hiapi-seedance
+```
+
+Requires Python 3.8+.
+
+## Quick Start
+
+```python
+from hiapi_seedance import Seedance
+
+client = Seedance()  # uses HIAPI_API_KEY
+
+task = client.text_to_video(
+    prompt="A 30-second cinematic one-take product film, golden hour, slow dolly in",
+    duration=30,
+    aspect_ratio="16:9",
+    resolution="1080p",
+)
+
+print(task.output[0].url)
+```
+
+Set your API key:
+
+```bash
+export HIAPI_API_KEY="sk-your-hiapi-key"
+```
+
+Get a key at [HiAPI](https://www.hiapi.ai/en/register?utm_source=github&utm_medium=readme&utm_campaign=hiapi-seedance-python).
+
+## Text-to-Video
+
+```python
+from hiapi_seedance import Seedance
+
+client = Seedance(api_key="sk-...")
+
+task = client.text_to_video(
+    prompt=(
+        "A one-take AI video prompt: a glass perfume bottle rotates on wet black "
+        "stone while sunrise light moves across the surface, macro texture, no text."
+    ),
+    duration=15,
+    aspect_ratio="16:9",
+    resolution="1080p",
+)
+
+print(task.status, task.output[0].url)
+```
+
+## Image-to-Video
+
+```python
+task = client.image_to_video(
+    prompt="Animate the reference image with a slow push-in, drifting fabric, and warm rim light.",
+    image_urls=["https://example.com/first-frame.png"],
+    duration=8,
+    aspect_ratio="9:16",
+)
+```
+
+## Video Editing
+
+```python
+task = client.video_edit(
+    prompt="Keep the original camera movement and timing. Add a blue-white energy bow in the actor's hands.",
+    video_urls=["https://example.com/source.mp4"],
+    image_urls=["https://example.com/prop-reference.png"],
+)
+```
+
+## Return Immediately Instead of Waiting
+
+```python
+created = client.text_to_video(
+    prompt="A fashion film in a desert gallery",
+    duration=30,
+    wait=False,
+)
+
+task = client.wait(created.task_id, poll_interval=3, timeout=900)
+print(task.output[0].url)
+```
+
+## Raw HiAPI Task Shape
+
+The SDK sends requests to:
+
+```http
+POST https://api.hiapi.ai/v1/tasks
+Authorization: Bearer $HIAPI_API_KEY
+Content-Type: application/json
+```
+
+```json
+{
+  "model": "seedance-2-5",
+  "input": {
+    "prompt": "A cinematic Seedance 2.5 prompt",
+    "duration": 30,
+    "aspect_ratio": "16:9",
+    "resolution": "1080p"
+  }
+}
+```
+
+You can pass additional model fields as keyword arguments:
+
+```python
+task = client.text_to_video(
+    prompt="A multilingual typography loop",
+    duration=15,
+    web_search=False,
+    generate_audio=True,
+)
+```
+
+## Prompt Library
+
+Need production prompts and preview examples? Use the companion prompt library:
+
+- [Seedance 2.5 prompt library](https://github.com/HiAPIAI/awesome-seedance-2-5-prompts)
+- [Seedance 2.0 prompt library](https://github.com/HiAPIAI/awesome-seedance-2-0-prompts)
+
+## Model Slug
+
+The default model is `seedance-2-5`. You can override it per client or per call:
+
+```python
+client = Seedance(model="seedance-2-5")
+task = client.text_to_video(prompt="...", model="seedance-2-0")
+```
+
+Use the fallback model while waiting for Seedance 2.5 availability on your account.
+
+## SEO Keywords
+
+Seedance 2.5 API, Seedance Python SDK, Seedance API Python, Seedance text to video API, Seedance image to video API, AI video generation API, text-to-video Python, image-to-video Python, HiAPI Seedance API.
+
+## License
+
+MIT

hiapi_seedance-0.1.0/README.md

@@ -0,0 +1,160 @@
+# HiAPI Seedance Python SDK
+
+Python SDK for **Seedance 2.5 API**, **Seedance text-to-video**, **Seedance image-to-video**, and Seedance video editing through the HiAPI unified task API.
+
+[![PyPI](https://img.shields.io/badge/pip-hiapi--seedance-f97316)](https://pypi.org/project/hiapi-seedance/) [![HiAPI](https://img.shields.io/badge/HiAPI-One%20API%2C%20All%20AI%20Models-111827)](https://www.hiapi.ai/en?utm_source=github&utm_medium=readme&utm_campaign=hiapi-seedance-python) [![Docs](https://img.shields.io/badge/API%20Docs-docs.hiapi.ai-111827)](https://docs.hiapi.ai/?utm_source=github&utm_medium=readme&utm_campaign=hiapi-seedance-python)
+
+Use this SDK when you want a small Python client focused on AI video generation:
+
+- **Seedance 2.5 API access** through HiAPI's `/v1/tasks` endpoint.
+- **Text-to-video** with `client.text_to_video(...)`.
+- **Image-to-video** with `client.image_to_video(...)`.
+- **Video editing** with `client.video_edit(...)`.
+- **Async task polling** built in: submit, poll, and read the output URL.
+- **Zero runtime dependencies**: standard library only.
+
+## Install
+
+```bash
+pip install hiapi-seedance
+```
+
+Requires Python 3.8+.
+
+## Quick Start
+
+```python
+from hiapi_seedance import Seedance
+
+client = Seedance()  # uses HIAPI_API_KEY
+
+task = client.text_to_video(
+    prompt="A 30-second cinematic one-take product film, golden hour, slow dolly in",
+    duration=30,
+    aspect_ratio="16:9",
+    resolution="1080p",
+)
+
+print(task.output[0].url)
+```
+
+Set your API key:
+
+```bash
+export HIAPI_API_KEY="sk-your-hiapi-key"
+```
+
+Get a key at [HiAPI](https://www.hiapi.ai/en/register?utm_source=github&utm_medium=readme&utm_campaign=hiapi-seedance-python).
+
+## Text-to-Video
+
+```python
+from hiapi_seedance import Seedance
+
+client = Seedance(api_key="sk-...")
+
+task = client.text_to_video(
+    prompt=(
+        "A one-take AI video prompt: a glass perfume bottle rotates on wet black "
+        "stone while sunrise light moves across the surface, macro texture, no text."
+    ),
+    duration=15,
+    aspect_ratio="16:9",
+    resolution="1080p",
+)
+
+print(task.status, task.output[0].url)
+```
+
+## Image-to-Video
+
+```python
+task = client.image_to_video(
+    prompt="Animate the reference image with a slow push-in, drifting fabric, and warm rim light.",
+    image_urls=["https://example.com/first-frame.png"],
+    duration=8,
+    aspect_ratio="9:16",
+)
+```
+
+## Video Editing
+
+```python
+task = client.video_edit(
+    prompt="Keep the original camera movement and timing. Add a blue-white energy bow in the actor's hands.",
+    video_urls=["https://example.com/source.mp4"],
+    image_urls=["https://example.com/prop-reference.png"],
+)
+```
+
+## Return Immediately Instead of Waiting
+
+```python
+created = client.text_to_video(
+    prompt="A fashion film in a desert gallery",
+    duration=30,
+    wait=False,
+)
+
+task = client.wait(created.task_id, poll_interval=3, timeout=900)
+print(task.output[0].url)
+```
+
+## Raw HiAPI Task Shape
+
+The SDK sends requests to:
+
+```http
+POST https://api.hiapi.ai/v1/tasks
+Authorization: Bearer $HIAPI_API_KEY
+Content-Type: application/json
+```
+
+```json
+{
+  "model": "seedance-2-5",
+  "input": {
+    "prompt": "A cinematic Seedance 2.5 prompt",
+    "duration": 30,
+    "aspect_ratio": "16:9",
+    "resolution": "1080p"
+  }
+}
+```
+
+You can pass additional model fields as keyword arguments:
+
+```python
+task = client.text_to_video(
+    prompt="A multilingual typography loop",
+    duration=15,
+    web_search=False,
+    generate_audio=True,
+)
+```
+
+## Prompt Library
+
+Need production prompts and preview examples? Use the companion prompt library:
+
+- [Seedance 2.5 prompt library](https://github.com/HiAPIAI/awesome-seedance-2-5-prompts)
+- [Seedance 2.0 prompt library](https://github.com/HiAPIAI/awesome-seedance-2-0-prompts)
+
+## Model Slug
+
+The default model is `seedance-2-5`. You can override it per client or per call:
+
+```python
+client = Seedance(model="seedance-2-5")
+task = client.text_to_video(prompt="...", model="seedance-2-0")
+```
+
+Use the fallback model while waiting for Seedance 2.5 availability on your account.
+
+## SEO Keywords
+
+Seedance 2.5 API, Seedance Python SDK, Seedance API Python, Seedance text to video API, Seedance image to video API, AI video generation API, text-to-video Python, image-to-video Python, HiAPI Seedance API.
+
+## License
+
+MIT

hiapi_seedance-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hiapi-seedance"
+description = "Python SDK for Seedance 2.5 and Seedance video generation through the HiAPI unified task API."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "HiAPI", email = "support@hiapi.ai" }]
+keywords = [
+    "hiapi",
+    "seedance",
+    "seedance 2.5",
+    "seedance 2.5 api",
+    "seedance python sdk",
+    "text to video api",
+    "image to video api",
+    "ai video generation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = []
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://www.hiapi.ai/en?utm_source=github&utm_medium=pyproject&utm_campaign=hiapi-seedance-python"
+Documentation = "https://docs.hiapi.ai/?utm_source=github&utm_medium=pyproject&utm_campaign=hiapi-seedance-python"
+Source = "https://github.com/HiAPIAI/hiapi-seedance-python"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "mypy>=1.0",
+    "ruff>=0.1",
+]
+
+[tool.hatch.version]
+path = "src/hiapi_seedance/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hiapi_seedance"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/hiapi_seedance", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.pyupgrade]
+keep-runtime-typing = true
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/hiapi_seedance"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hiapi_seedance-0.1.0/src/hiapi_seedance/__init__.py

@@ -0,0 +1,22 @@
+"""HiAPI Seedance Python SDK."""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .client import Seedance
+from .errors import APIConnectionError, APIError, PollTimeout, SeedanceError, TaskFailed
+from .models import CreatedTask, Output, Task, TaskError
+
+__all__ = [
+    "__version__",
+    "Seedance",
+    "CreatedTask",
+    "Output",
+    "Task",
+    "TaskError",
+    "SeedanceError",
+    "APIError",
+    "APIConnectionError",
+    "TaskFailed",
+    "PollTimeout",
+]

hiapi_seedance-0.1.0/src/hiapi_seedance/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

hiapi_seedance-0.1.0/src/hiapi_seedance/client.py

@@ -0,0 +1,278 @@
+"""Seedance-focused client for HiAPI's unified task API."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+from ._version import __version__
+from .errors import APIConnectionError, APIError, PollTimeout, TaskFailed
+from .models import CreatedTask, Task
+
+DEFAULT_BASE_URL = "https://api.hiapi.ai/v1"
+DEFAULT_MODEL = "seedance-2-5"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_POLL_INTERVAL = 3.0
+DEFAULT_WAIT_TIMEOUT = 900.0
+
+UrlList = Union[str, Iterable[str]]
+
+
+class Seedance:
+    """Python SDK for Seedance video generation through HiAPI.
+
+    Args:
+        api_key: HiAPI API key. Falls back to ``HIAPI_API_KEY``.
+        base_url: HiAPI base URL. Both ``https://api.hiapi.ai`` and
+            ``https://api.hiapi.ai/v1`` are accepted.
+        model: Default model slug. Defaults to ``seedance-2-5``.
+        timeout: HTTP request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        model: str = DEFAULT_MODEL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = api_key or os.environ.get("HIAPI_API_KEY")
+        if not key:
+            raise ValueError("missing API key: pass api_key=... or set HIAPI_API_KEY")
+        self.api_key = key
+        self.base_url = _normalize_base_url(base_url)
+        self.model = model
+        self.timeout = timeout
+
+    def text_to_video(
+        self,
+        *,
+        prompt: str,
+        duration: Optional[int] = None,
+        aspect_ratio: Optional[str] = None,
+        resolution: Optional[str] = None,
+        generate_audio: Optional[bool] = None,
+        model: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        wait: bool = True,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+        **extra: Any,
+    ) -> Union[Task, CreatedTask]:
+        """Create a Seedance text-to-video task.
+
+        Set ``wait=False`` to return immediately with ``CreatedTask``.
+        """
+        input_data = _clean(
+            {
+                "prompt": prompt,
+                "duration": duration,
+                "aspect_ratio": aspect_ratio,
+                "resolution": resolution,
+                "generate_audio": generate_audio,
+                **extra,
+            }
+        )
+        return self.create(
+            input=input_data,
+            model=model,
+            callback_url=callback_url,
+            wait=wait,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+    def image_to_video(
+        self,
+        *,
+        prompt: str,
+        image_urls: UrlList,
+        duration: Optional[int] = None,
+        aspect_ratio: Optional[str] = None,
+        resolution: Optional[str] = None,
+        model: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        wait: bool = True,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+        **extra: Any,
+    ) -> Union[Task, CreatedTask]:
+        """Create a Seedance image-to-video task with reference images."""
+        input_data = _clean(
+            {
+                "prompt": prompt,
+                "reference_image_urls": _as_list(image_urls),
+                "duration": duration,
+                "aspect_ratio": aspect_ratio,
+                "resolution": resolution,
+                **extra,
+            }
+        )
+        return self.create(
+            input=input_data,
+            model=model,
+            callback_url=callback_url,
+            wait=wait,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+    def video_edit(
+        self,
+        *,
+        prompt: str,
+        video_urls: UrlList,
+        image_urls: Optional[UrlList] = None,
+        model: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        wait: bool = True,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+        **extra: Any,
+    ) -> Union[Task, CreatedTask]:
+        """Create a Seedance video-edit task with source video references."""
+        input_data = _clean(
+            {
+                "prompt": prompt,
+                "reference_video_urls": _as_list(video_urls),
+                "reference_image_urls": _as_list(image_urls) if image_urls else None,
+                **extra,
+            }
+        )
+        return self.create(
+            input=input_data,
+            model=model,
+            callback_url=callback_url,
+            wait=wait,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+    def create(
+        self,
+        *,
+        input: Dict[str, Any],
+        model: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        wait: bool = False,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> Union[Task, CreatedTask]:
+        """Submit a raw HiAPI task for Seedance-compatible inputs."""
+        body: Dict[str, Any] = {"model": model or self.model, "input": input}
+        if callback_url:
+            body["callback"] = {"url": callback_url, "when": "final"}
+        env = self._request("POST", "/tasks", body=body)
+        created = CreatedTask.from_dict(_data(env))
+        if wait:
+            return self.wait(created.task_id, poll_interval=poll_interval, timeout=timeout)
+        return created
+
+    def retrieve(self, task_id: str) -> Task:
+        """Fetch a task by id."""
+        env = self._request("GET", "/tasks/" + urllib.parse.quote(task_id, safe=""))
+        return Task.from_dict(_data(env))
+
+    def wait(
+        self,
+        task_id: str,
+        *,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> Task:
+        """Poll a task until it succeeds, fails, or times out."""
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be > 0")
+        if timeout < 0:
+            raise ValueError("timeout must be >= 0")
+
+        deadline = time.monotonic() + timeout
+        while True:
+            task = self.retrieve(task_id)
+            if task.status == "success":
+                return task
+            if task.status == "fail":
+                raise TaskFailed(task)
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise PollTimeout(task_id, timeout)
+            time.sleep(min(poll_interval, remaining))
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = self.base_url + path
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"hiapi-seedance/{__version__}",
+        }
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return _decode(response.read(), response.status)
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            raise _api_error(exc.code, raw) from None
+        except OSError as exc:
+            raise APIConnectionError(str(getattr(exc, "reason", exc))) from exc
+
+
+def _normalize_base_url(base_url: str) -> str:
+    base = base_url.rstrip("/")
+    if not base.endswith("/v1"):
+        base += "/v1"
+    return base
+
+
+def _decode(raw: bytes, status: int) -> Dict[str, Any]:
+    try:
+        parsed = json.loads(raw.decode("utf-8")) if raw else {}
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise APIError(str(exc), status=status, body=raw.decode("utf-8", "replace")) from exc
+    if not isinstance(parsed, dict):
+        raise APIError("expected JSON object response", status=status, body=str(parsed))
+    return parsed
+
+
+def _api_error(status: int, raw: bytes) -> APIError:
+    message = f"HTTP {status}"
+    error_code = None
+    body = raw.decode("utf-8", "replace") if raw else None
+    try:
+        parsed = json.loads(raw.decode("utf-8")) if raw else {}
+        if isinstance(parsed, dict):
+            message = str(parsed.get("message") or message)
+            error_code = parsed.get("error_code")
+    except (UnicodeDecodeError, ValueError):
+        pass
+    return APIError(message, status=status, error_code=error_code, body=body)
+
+
+def _data(env: Dict[str, Any]) -> Dict[str, Any]:
+    data = env.get("data")
+    return data if isinstance(data, dict) else {}
+
+
+def _clean(data: Dict[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in data.items() if value is not None}
+
+
+def _as_list(value: UrlList) -> List[str]:
+    if isinstance(value, str):
+        return [value]
+    return [str(item) for item in value]

hiapi_seedance-0.1.0/src/hiapi_seedance/errors.py

@@ -0,0 +1,50 @@
+"""Exception hierarchy for hiapi-seedance."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SeedanceError(Exception):
+    """Base class for all SDK errors."""
+
+
+class APIError(SeedanceError):
+    """The API returned a non-2xx response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        error_code: Optional[str] = None,
+        body: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.error_code = error_code
+        self.body = body
+
+
+class APIConnectionError(SeedanceError):
+    """A network error prevented the request from completing."""
+
+
+class TaskFailed(SeedanceError):
+    """A polled task reached terminal status=fail."""
+
+    def __init__(self, task: object) -> None:
+        err = getattr(task, "error", None)
+        self.code = getattr(err, "code", None)
+        self.message = getattr(err, "message", None) or "task failed"
+        self.task = task
+        super().__init__(f"task {getattr(task, 'task_id', '?')} failed: {self.message}")
+
+
+class PollTimeout(SeedanceError):
+    """The task did not finish within the client-side timeout."""
+
+    def __init__(self, task_id: str, timeout: float) -> None:
+        self.task_id = task_id
+        self.timeout = timeout
+        super().__init__(f"task {task_id} did not finish within {timeout:g}s")

hiapi_seedance-0.1.0/src/hiapi_seedance/models.py

@@ -0,0 +1,81 @@
+"""Typed response models for the HiAPI Seedance SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+TERMINAL_STATUSES = frozenset({"success", "fail"})
+
+
+@dataclass
+class Output:
+    url: str
+    type: str = ""
+    expire_at: Optional[int] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Output:
+        return cls(
+            url=str(data.get("url", "")),
+            type=str(data.get("type", "")),
+            expire_at=data.get("expireAt"),
+            raw=data,
+        )
+
+
+@dataclass
+class TaskError:
+    code: Optional[str] = None
+    message: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> TaskError:
+        return cls(code=data.get("code"), message=data.get("message"), raw=data)
+
+
+@dataclass
+class CreatedTask:
+    task_id: str
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> CreatedTask:
+        return cls(task_id=str(data.get("taskId", "")), raw=data)
+
+
+@dataclass
+class Task:
+    task_id: str
+    model: str
+    status: str
+    output: List[Output] = field(default_factory=list)
+    error: Optional[TaskError] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in TERMINAL_STATUSES
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status == "success"
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Task:
+        outputs = [
+            Output.from_dict(item)
+            for item in (data.get("output") or [])
+            if isinstance(item, dict)
+        ]
+        err = data.get("error")
+        return cls(
+            task_id=str(data.get("taskId", "")),
+            model=str(data.get("model", "")),
+            status=str(data.get("status", "")),
+            output=outputs,
+            error=TaskError.from_dict(err) if isinstance(err, dict) else None,
+            raw=data,
+        )

hiapi_seedance-0.1.0/src/hiapi_seedance/py.typed

@@ -0,0 +1 @@
+