Metadata-Version: 2.4
Name: byteplus-py
Version: 0.1.0
Summary: Python SDK for BytePlus ModelArk APIs, starting with Seedance video generation.
Project-URL: Homepage, https://github.com/ZeroSpaceStudios/byteplus-py
Project-URL: Repository, https://github.com/ZeroSpaceStudios/byteplus-py
Project-URL: Issues, https://github.com/ZeroSpaceStudios/byteplus-py/issues
Author: byteplus-py contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,ark,byteplus,modelark,sdk,seedance,video-generation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anyio<5,>=4
Requires-Dist: byteplus-python-sdk-v2[ark]<4,>=3.0.44
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: sniffio<2,>=1.3
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == 'dev'
Description-Content-Type: text/markdown

# byteplus-py

A small convenience SDK for BytePlus ModelArk APIs, starting with Seedance video generation.
It wraps the official `byteplus-python-sdk-v2` Ark runtime and adds fal-style `submit`,
`retrieve`, `wait`, and `subscribe` helpers.

## Install

```bash
python -m pip install -e ".[dev]"
```

## Configure

Create a `.env` file:

```bash
BYTEPLUS_API_KEY=ark-...
```

`ARK_API_KEY` is also supported.

## Usage

```python
from byteplus_py import BytePlus
from byteplus_py.seedance import image_url, text

client = BytePlus.from_env()

task = client.seedance.submit(
    model="dreamina-seedance-2-0-fast-260128",
    content=[
        text("A cinematic shot of fruit tea being prepared."),
        image_url(
            "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/r2v_tea_pic1.jpg",
            role="reference_image",
        ),
    ],
    generate_audio=True,
    ratio="16:9",
    duration=4,
    watermark=False,
)

print(task.id)
```

For fal-style polling:

```python
result = client.seedance.subscribe(
    model="dreamina-seedance-2-0-fast-260128",
    content=[text("A tiny robot waters a basil plant in morning light.")],
    duration=4,
)

print(result.video_url)
```

## Download a Completed Video

```python
from byteplus_py import BytePlus

client = BytePlus.from_env()
path = client.seedance.download_video("cgt-...", output_dir="downloads")

print(path)
```

## Estimate Video Cost

The Seedance API returns `usage.completion_tokens` for completed tasks. The SDK can
combine that with the video generation rates in `docs/byteplus-pricing.md`:

```python
task = client.seedance.retrieve("cgt-...")
cost = client.seedance.estimate_cost(task, input_includes_video=True)

print(cost.amount_usd)
```

## Smoke Test

The smoke script submits the multimodal sample from `docs/video-api-docs.md` and prints only non-secret task data:

```bash
python examples/seedance_smoke.py --no-wait
```

To poll until completion:

```bash
python examples/seedance_smoke.py --wait --timeout 900
```

To wait and download the completed video:

```bash
python examples/seedance_smoke.py --wait --download
```
