Skip to main content

Python SDK

The official Vidiking Python SDK for all API endpoints. Supports Python 3.8+.

Installation​

pip install vidiai

Setup​

from vidiai import Vidiai

client = Vidiking(
    api_key="your_api_key",  # or set VIDIKING_API_KEY env var
    sandbox=False,
)

Video Rendering​

Render​

result = client.render({
    "timeline": {
        "background": "#000000",
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {"type": "title", "text": "Hello World", "style": "minimal", "size": "large"},
                        "start": 0,
                        "length": 5,
                    }
                ]
            }
        ],
    },
    "output": {"format": "mp4", "resolution": "hd"},
})

print("Job ID:", result.job_id)

Get Render Status​

job = client.get_render(result.job_id)
print(job.status)  # QUEUED | PROCESSING | COMPLETE | FAILED
print(job.url)     # Available when COMPLETE

Poll Until Complete​

job = client.poll_job(result.job_id, interval=3, timeout=300)
print("Output:", job.url)

Stitch​

result = client.stitch({
    "clips": [
        {"src": "https://example.com/intro.mp4"},
        {"src": "https://example.com/main.mp4", "trim": 5, "length": 30},
        {"src": "https://example.com/outro.mp4"},
    ],
    "output": {"format": "mp4", "resolution": "hd"},
})

Trim​

result = client.trim({
    "src": "https://example.com/video.mp4",
    "start": 10,
    "length": 20,
    "output": {"format": "mp4", "resolution": "hd"},
})

Upscale​

result = client.upscale({
    "src": "https://cdn.vidiking.com/renders/job_abc123.mp4",
    "output": {"format": "mp4", "quality": "high"},
})

AI Features​

Image Generation​

image = client.ai.generate_image(
    prompt="A mountain landscape at sunset",
    model="flux",
    width=1920,
    height=1080,
)
print(image.url)

Video Generation​

result = client.ai.generate_video(
    prompt="Aerial shot of ocean waves crashing on rocks",
    model="runway-gen4-turbo",
    duration=5,
    aspect_ratio="16:9",
)

job = client.poll_job(result.job_id)
print(job.url)

Voiceover​

voiceover = client.ai.generate_voiceover(
    text="Welcome to our product tour.",
    model="elevenlabs-flash",
    voice="rachel",
    language="en",
    speed=1.0,
)
print(voiceover.url, voiceover.duration)

Subtitles​

result = client.ai.generate_subtitles(
    src="https://example.com/video.mp4",
    language="en",
    burn_in=True,
    style={"font_size": 36, "color": "#ffffff"},
)

job = client.poll_job(result.job_id)
print(job.url)

Script Generation​

script = client.ai.generate_script(
    topic="Product launch announcement",
    tone="energetic",
    format="ad",
    duration=30,
)
print(script.text)

Templates​

# List templates
templates = client.templates.list(category="marketing")

# Render template
result = client.templates.render("tpl_promo_001", {
    "merge_fields": {
        "headline": "Big Sale",
        "product_image": "https://example.com/product.png",
    },
    "output": {"format": "mp4", "resolution": "hd"},
})

Wallet​

wallet = client.get_wallet()
print(f"Balance: {wallet.balance}, Available: {wallet.available}")

Error Handling​

from vidiai.exceptions import VidiaiError, InsufficientFundsError, RateLimitError

try:
    client.render({...})
except InsufficientFundsError as e:
    print(f"Not enough balance: {e.balance}")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
except VidikingError as e:
    print(f"API error: {e.code} - {e.message}")

Async Support​

from vidiai import AsyncVidiking

client = AsyncVidiking(api_key="your_api_key")

async def main():
    result = await client.render({
        "timeline": {"tracks": [...]},
        "output": {"format": "mp4", "resolution": "hd"},
    })
    job = await client.poll_job(result.job_id)
    print(job.url)

Configuration​

client = Vidiking(
    api_key="your_api_key",       # Required (or VIDIKING_API_KEY env var)
    sandbox=False,                 # Sandbox mode (default: False)
    base_url="https://api.vidiking.com",  # Custom base URL
    timeout=30,                    # Request timeout in seconds (default: 30)
    max_retries=3,                 # Auto-retry on 5xx (default: 3)
)