SDKs

Sync provides official lip sync SDK libraries for Python and TypeScript. Both SDKs wrap the Sync 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.

1
import time
2
from sync import Sync
3
from sync.common import Audio, Video
4
5
sync = Sync()
6
7
# Create a lipsync generation
8
response = sync.generations.create(
9
    input=[
10
        Video(url="https://assets.sync.so/docs/example-video.mp4"),
11
        Audio(url="https://assets.sync.so/docs/example-audio.wav"),
12
    ],
13
    model="lipsync-2",
14
)
15
16
job_id = response.id
17
print(f"Job submitted: {job_id}")
18
19
# Poll until complete
20
generation = sync.generations.get(job_id)
21
while generation.status not in ["COMPLETED", "FAILED", "REJECTED"]:
22
    time.sleep(10)
23
    generation = sync.generations.get(job_id)
24
25
if generation.status == "COMPLETED":
26
    print(f"Output: {generation.output_url}")
27
else:
28
    print(f"Generation {job_id} failed")

1
import { SyncClient } from "@sync.so/sdk";
2
3
const sync = new SyncClient();
4
5
async function main() {
6
    // Create a lipsync generation
7
    const response = await sync.generations.create({
8
        input: [
9
            { type: "video", url: "https://assets.sync.so/docs/example-video.mp4" },
10
            { type: "audio", url: "https://assets.sync.so/docs/example-audio.wav" },
11
        ],
12
        model: "lipsync-2",
13
    });
14
15
    const jobId = response.id;
16
    console.log(`Job submitted: ${jobId}`);
17
18
    // Poll until complete
19
    let generation = await sync.generations.get(jobId);
20
    while (!["COMPLETED", "FAILED", "REJECTED"].includes(generation.status)) {
21
        await new Promise((r) => setTimeout(r, 10000));
22
        generation = await sync.generations.get(jobId);
23
    }
24
25
    if (generation.status === "COMPLETED") {
26
        console.log(`Output: ${generation.outputUrl}`);
27
    } else {
28
        console.log(`Generation ${jobId} failed`);
29
    }
30
}
31
32
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 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 production systems, implement retry logic with exponential backoff for 429 and 5xx errors. See the Python SDK Guide and TypeScript SDK Guide for code examples.

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