SDKs

Sync Labs provides official lip sync SDK libraries for Python and TypeScript. Both SDKs wrap the Sync Labs API and give you typed methods for creating generations, polling status, and retrieving results — so you can add video lip sync integration to your app in minutes.

Installation

pip install syncsdk

npm i @sync.so/sdk

Authentication

Both SDKs read your API key from the SYNC_API_KEY environment variable automatically. Set it before running your code:

export SYNC_API_KEY="your-api-key"

You can create an API key from the API Keys page in your dashboard. See the Authentication guide for more details and security best practices.

Quick Start

The example below creates a lip sync generation and polls until the result is ready.

import time
from sync import Sync
from sync.common import Audio, Video
sync = Sync()
# Create a lipsync generation
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",
)
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")

import { SyncClient } from "@sync.so/sdk";
const sync = new SyncClient();
async function main() {
    // Create a lipsync generation
    const response = await sync.generations.create({
        input: [
            { type: "video", url: "https://assets.sync.so/docs/example-video.mp4" },
            { type: "audio", url: "https://assets.sync.so/docs/example-audio.wav" },
        ],
        model: "lipsync-2",
    });
    const jobId = response.id;
    console.log(`Job submitted: ${jobId}`);
    // Poll until complete
    let generation = await sync.generations.get(jobId);
    while (!["COMPLETED", "FAILED", "REJECTED"].includes(generation.status)) {
        await new Promise((r) => setTimeout(r, 10000));
        generation = await sync.generations.get(jobId);
    }
    if (generation.status === "COMPLETED") {
        console.log(`Output: ${generation.outputUrl}`);
    } else {
        console.log(`Generation ${jobId} failed`);
    }
}
main();

For a full walkthrough with error handling, see the Quickstart guide.

When should I use the SDK vs the raw API?

Use the SDK when you want typed methods, automatic authentication, and less boilerplate. Use the raw REST API when you need full control over HTTP requests, work in a language without an official SDK, or want to minimize dependencies.

Feature comparison

Both SDKs cover the full Sync Labs API surface with equivalent functionality:

Error handling overview

Both SDKs raise typed exceptions for API errors. Wrap your calls in try/except (Python) or try/catch (TypeScript) and inspect the status code to decide how to respond:

For generation creation, send an Idempotency-Key on the first attempt and preserve it and the payload across retries. Use backoff and honor Retry-After; do not blindly retry an unkeyed create after a timeout or 5xx response. The idempotency guide includes raw HTTP examples you can use independently of your installed SDK version. See the Python SDK Guide and TypeScript SDK Guide for error handling.

For the complete list of methods, parameters, and response types, see the API Reference.