Skip to navigation
Developer Guides

Python SDK Guide

The Sync Labs Python SDK (syncsdk) wraps the Sync Labs REST API with typed methods for Python 3.8+. It provides methods for creating lip sync generations, polling for results, estimating costs, and managing assets.

Source code: sync-python-sdk on GitHub

Installation

Requires Python 3.8+. Install from PyPI:

pip install syncsdk

This guide covers syncsdk 0.4.0 and later. Check your version with pip show syncsdk and upgrade with pip install --upgrade syncsdk. Version 0.4.0 adds image inputs, dub_params, dialogue_edit and project_id on generation create, asset uploads, projects, voices, text-to-speech, transcriptions, dialogue edits, account.get(), feedback.submit(), output_audio and lipsync=False segments, and a working estimate_cost. In 0.4.0, estimate_cost takes a model and a duration (it previously took a full generation request), and generations.delete returns the stored-generation shape.

We recommend using a virtual environment to avoid dependency conflicts:

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
pip install syncsdk

Authentication

The SDK reads your API key from the SYNC_API_KEY environment variable automatically:

export SYNC_API_KEY="your-api-key"
from sync import Sync
sync = Sync()  # picks up SYNC_API_KEY from environment

You can also pass the key directly:

sync = Sync(api_key="your-api-key")

Create an API key from the API Keys page in your dashboard. See the Authentication guide for security best practices.

Quick Start

Create a lip sync generation, poll until it finishes, and print the output URL.

quickstart.py
import time
from sync import Sync
from sync.common import Audio, Video, GenerationOptions
from sync.core.api_error import ApiError
sync = Sync()
try:
    response = sync.generations.create(
        input=[
            Video(url="https://assets.sync.so/docs/example-video.mp4"),
            Audio(url="https://assets.sync.so/docs/example-audio.wav"),
        ],
        model="lipsync-2",
        options=GenerationOptions(sync_mode="cut_off"),
    )
except ApiError as e:
    print(f"Request failed: {e.status_code} - {e.body}")
    exit()
job_id = response.id
print(f"Job submitted: {job_id}")
# Poll until complete
generation = sync.generations.get(job_id)
while generation.status not in ["COMPLETED", "FAILED", "REJECTED"]:
    time.sleep(10)
    generation = sync.generations.get(job_id)
if generation.status == "COMPLETED":
    print(f"Output: {generation.output_url}")
else:
    print(f"Generation {job_id} failed: {generation.error}")

Run it:

python quickstart.py

Core Operations

Creating Generations

Video + Audio

The most common use case. Provide a video and an audio file, and Sync Labs generates matching lip movements.

from sync import Sync
from sync.common import Audio, Video, GenerationOptions
sync = Sync()
response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/video.mp4"),
        Audio(url="https://your-cdn.com/audio.wav"),
    ],
    model="lipsync-2",
    options=GenerationOptions(sync_mode="cut_off"),
    output_file_name="my_output",
)

Video + Text-to-Speech

Use the built-in ElevenLabs integration to go straight from text to lip-synced video. No separate TTS step needed.

from sync import Sync
from sync.common import Video, TTS, GenerationOptions
sync = Sync()
response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/video.mp4"),
        TTS(
            provider={
                "name": "elevenlabs",
                "voiceId": "EXAVITQu4vr4xnSDxMaL",
                "script": "Hello, this is a demo of the Sync Labs lip sync API.",
                "stability": 0.5,
                "similarityBoost": 0.75,
            }
        ),
    ],
    model="lipsync-2",
    options=GenerationOptions(sync_mode="cut_off"),
)

The script field has a maximum of 5,000 characters per generation. For longer scripts, split them into segments. See the Text-to-Speech Lip Sync Guide for details.

Polling vs Webhooks

Polling is the simplest approach. Call generations.get() in a loop until the status is terminal:

import time
generation = sync.generations.get(job_id)
while generation.status not in ["COMPLETED", "FAILED", "REJECTED"]:
    time.sleep(10)
    generation = sync.generations.get(job_id)

Webhooks are better for production. Pass a webhook_url when creating the generation, and Sync Labs sends a POST request when the job finishes:

response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/video.mp4"),
        Audio(url="https://your-cdn.com/audio.wav"),
    ],
    model="lipsync-2",
    webhook_url="https://your-server.com/webhook",
)

See the Webhooks guide for payload format and signature verification.

Listing Generations

Retrieve your recent generations. Optionally filter by status:

# List all generations
all_generations = sync.generations.list()
# Filter by status
completed = sync.generations.list(status="COMPLETED")
pending = sync.generations.list(status="PENDING")
for gen in completed:
    print(f"{gen.id} - {gen.status} - {gen.output_url}")

Getting Generation Details

Fetch the full details of a single generation by ID:

generation = sync.generations.get("your-generation-id")
print(f"Status: {generation.status}")
print(f"Model: {generation.model}")
print(f"Created: {generation.created_at}")
print(f"Duration: {generation.output_duration}s")
if generation.output_url:
    print(f"Output: {generation.output_url}")

Cost Estimation

Estimate a generation from its model and billable duration in seconds. The response is a single object; estimated_credits is None for dollar-billed organizations, and duration_check says whether your plan allows that duration.

estimate = sync.generations.estimate_cost(model="lipsync-2", duration=10, fps=30)
print(f"Estimated cost: ${estimate.estimated_generation_cost}")
print(f"Estimated frames: {estimate.estimated_frame_count}")
print(f"Estimated credits: {estimate.estimated_credits}")

Pass workflow="translate-and-dub" to quote dubbing plus lip sync; the response then carries a breakdown.

Working with Files

URL Inputs

The simplest approach — pass publicly accessible URLs for your video and audio:

from sync.common import Video, Audio
Video(url="https://your-cdn.com/video.mp4")
Audio(url="https://your-cdn.com/audio.wav")

Image Inputs

sync-3 can animate a still image instead of a video:

from sync.common import Audio, Image
response = sync.generations.create(
    input=[
        Image(url="https://your-cdn.com/portrait.png"),
        Audio(url="https://your-cdn.com/audio.wav"),
    ],
    model="sync-3",
)

Asset IDs

If you have uploaded files to the Sync Labs media library (via the dashboard or Assets API), reference them by asset ID:

from sync.common import Video, Audio
Video(asset_id="550e8400-e29b-41d4-a716-446655440000")
Audio(asset_id="660e8400-e29b-41d4-a716-446655440001")

Uploading Assets

For large or reused local files, upload them once and generate from the asset ID. See Asset Uploads for the full flow:

import os
import httpx
from sync.common import Video
size = os.path.getsize("video.mp4")
presign = sync.assets.create_upload(file_name="video.mp4", content_type="video/mp4", size=size)
with open("video.mp4", "rb") as f:
    httpx.put(presign.upload_url, content=f, headers={"Content-Type": "video/mp4"}).raise_for_status()
asset = sync.assets.create(url=presign.url, type="VIDEO", name="video.mp4")
video = Video(asset_id=asset.id)

File Uploads

Upload local files directly using the multipart endpoint:

with open("video.mp4", "rb") as video_file, open("audio.wav", "rb") as audio_file:
    response = sync.generations.create_with_files(
        video=video_file,
        audio=audio_file,
        model="lipsync-2",
    )

The application parser limits file uploads to 5 GiB per file, subject to your plan and any lower proxy limits. For large files, upload them as assets and pass the returned asset ID, so retries don’t resend the file. You can also host them at a public URL and use the URL-based input.

Browsing Assets

List and retrieve assets from your media library:

# List assets with pagination
assets = sync.assets.list(limit=10, sort_by="dateDesc")
for asset in assets.items:
    print(f"{asset.name} ({asset.type}) - {asset.duration_seconds}s")
# Get a specific asset
asset = sync.assets.get("550e8400-e29b-41d4-a716-446655440000")
print(f"URL: {asset.url}")

Other Resources

Every public endpoint in the API Reference has a client method:

ResourceMethods
sync.accountget(): plan, limits, credits and active jobs
sync.generationscreate, create_with_files, get, list, estimate_cost, download, delete
sync.assetscreate_upload, create, list, get, update, delete
sync.projectscreate, list, get, update, delete, attach_asset, detach_asset
sync.batchcreate (JSONL file), create_from_rows, get, list
sync.voiceslist, get, clone, delete
sync.ttscreate, create_job, get_job
sync.transcriptions / sync.dialogue_editscreate, get
sync.models / sync.errorslist
sync.organizationsget_webhook_secret
sync.feedbacksubmit: report an unclear error, a wrong result or a workaround to the sync. team

Error Handling

The SDK raises ApiError for HTTP errors. Wrap your calls in try/except blocks:

from sync import Sync
from sync.core.api_error import ApiError
sync = Sync()
try:
    response = sync.generations.create(
        input=[
            Video(url="https://your-cdn.com/video.mp4"),
            Audio(url="https://your-cdn.com/audio.wav"),
        ],
        model="lipsync-2",
    )
except ApiError as e:
    print(f"Status: {e.status_code}")
    print(f"Error: {e.body}")

Common Errors

Status CodeCauseFix
400Invalid input (bad URL, unsupported format, missing fields)Check your input parameters and media formats
401Missing or invalid API keyVerify SYNC_API_KEY is set correctly
402Feature requires a higher planUpgrade your plan at sync.so
429Rate or concurrency limit exceededWait and retry, or reduce concurrency
500Server errorFor creation, follow idempotent retry guidance; confirm an unkeyed outcome before resubmitting

Retry Logic

For generation creation, use the Idempotent Requests contract to protect retries after timeouts and uncertain failures. Save the key before the first attempt and preserve it and the inputs across retries. Send it with idempotency_key= on generations.create, or through request options on any method:

response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/video.mp4"),
        Audio(url="https://your-cdn.com/audio.wav"),
    ],
    model="lipsync-2",
    request_options={"additional_headers": {"Idempotency-Key": key}},
)

The unkeyed example below retries only explicit HTTP 429 rejections. It does not retry 5xx or transport failures, which may have an unknown submission outcome:

import time
from sync.core.api_error import ApiError
def create_with_retry(sync, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return sync.generations.create(**kwargs)
        except ApiError as e:
            if e.status_code == 429 and attempt < max_retries - 1:
                wait = 2 ** attempt * 5  # 5s, 10s, 20s
                print(f"Retrying in {wait}s (attempt {attempt + 1}/{max_retries})")
                time.sleep(wait)
            else:
                raise

The client’s own max_retries request option also retries HTTP 409. For an unkeyed create, a retry within 60 seconds of an identical request receives DUPLICATE_SUBMISSION instead of a second generation; poll the returned generationId. See Requests without a key.

Async Usage

The SDK includes an async client for use with asyncio. Use AsyncSync instead of Sync:

import asyncio
from sync import AsyncSync
from sync.common import Audio, Video
async def main():
    sync = AsyncSync()
    response = await sync.generations.create(
        input=[
            Video(url="https://your-cdn.com/video.mp4"),
            Audio(url="https://your-cdn.com/audio.wav"),
        ],
        model="lipsync-2",
    )
    job_id = response.id
    print(f"Job submitted: {job_id}")
    # Poll until complete
    generation = await sync.generations.get(job_id)
    while generation.status not in ["COMPLETED", "FAILED", "REJECTED"]:
        await asyncio.sleep(10)
        generation = await sync.generations.get(job_id)
    if generation.status == "COMPLETED":
        print(f"Output: {generation.output_url}")
asyncio.run(main())

The async client supports the same methods as the sync client, on every resource.

The async client works with any asyncio-compatible framework like FastAPI, Sanic, or aiohttp.

Type Hints

The SDK is fully typed. All request parameters, response objects, and enums have type annotations. Your editor will provide autocomplete and inline documentation out of the box.

from sync.common import (
    Audio,
    Video,
    TTS,
    GenerationOptions,
    Generation,
    GenerationStatus,
    Model,
)
# Response objects are typed -- your editor knows all available fields
generation: Generation = sync.generations.get("job-id")
status: GenerationStatus = generation.status  # "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED" | "REJECTED"
model: Model = generation.model               # "lipsync-2" | "lipsync-2-pro" | ...
output_url: str | None = generation.output_url

Available Models

ModelBest ForSpeed
sync-3Highest quality, 4K output, image inputs, obstructions and extreme anglesSlower
lipsync-2General purpose lip syncFast
lipsync-2-proPremium content, fine detail (beards, teeth)Slower
lipsync-1.9.0-betaMaximum speedFastest
react-1Expressive results with emotion (short clips)Fast

See the Models page for detailed comparisons.

Next Steps

Frequently Asked Questions

Yes. The SDK includes an AsyncSync client for use with asyncio. Import AsyncSync instead of Sync and use await with all SDK methods. The async client supports the same operations as the sync client and works with frameworks like FastAPI, Sanic, and aiohttp.

Wrap SDK calls in try/except blocks. A generation create timeout can mean the server accepted the request. Retry with the same key and payload if the first attempt used an Idempotency-Key; otherwise confirm the outcome before submitting again. Poll an existing generation ID for status instead of creating another generation.

The Sync Labs API does not currently provide a cancel endpoint for in-progress generations. Once a generation is submitted, it will run to completion or fail. You only pay for successfully completed generations. Monitor status via polling or webhooks to track progress.