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

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

Configure

Create a .env file:

BYTEPLUS_API_KEY=ark-...

ARK_API_KEY is also supported.

Usage

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:

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

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:

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:

python examples/seedance_smoke.py --no-wait

To poll until completion:

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

To wait and download the completed video:

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