Authentication

Sync Labs uses API key authentication via the x-api-key header. Create an API key from the API Keys page, then include it in every request.

$
x-api-key: your-api-key

Sample Request

You can run the following sample request to generate a lipsynced video rightaway. Be sure to replace <apiKey> with your actual API key.

$
curl -X POST https://api.sync.so/v2/generate \
>
     -H "x-api-key: <apiKey>" \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
  "model": "lipsync-2",
>
  "input": [
>
    {
>
      "type": "video",
>
      "url": "https://assets.sync.so/docs/example-video.mp4"
>
    },
>
    {
>
      "type": "audio",
>
      "url": "https://assets.sync.so/docs/example-audio.wav"
>
    }
>
  ],
>
  "outputFileName": "my_custom_output"
>
}'

SDK Authentication

The official Python and TypeScript SDKs automatically read your API key from the SYNC_API_KEY environment variable. Set the variable once and the SDK handles lip sync API authentication for every request.

$
export SYNC_API_KEY="your-api-key"

No additional configuration is needed. The SDK picks up the key at initialization:

1
from sync import Sync
2
3
# Reads SYNC_API_KEY from the environment automatically
4
sync = Sync()

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

1
import { SyncClient } from "@sync.so/sdk";
2
3
// Reads SYNC_API_KEY from the environment automatically
4
const sync = new SyncClient();

1
const sync = new SyncClient({ apiKey: "your-api-key" });

API Key Security Best Practices

Your API key grants full access to the Sync Labs API on your behalf. Treat it like a password.

• Never commit keys to source control. Add .env to your .gitignore and use a secrets manager or environment variables instead.
• Use environment variables in production. Store SYNC_API_KEY in your hosting platform’s secrets or environment config rather than hardcoding it.
• Rotate keys regularly. Generate a new key from the API Keys page periodically, then revoke the old one.
• Use separate keys per environment. Create distinct keys for development, staging, and production so a compromised dev key does not affect production traffic.
• Restrict access. Only share your API key with team members and services that need it.

Error Handling

If a request is missing a valid API key, the Sync Labs API returns a 401 Unauthorized response.

Common causes:

• Missing header — The x-api-key header was not included in the request.
• Invalid key — The key is misspelled, expired, or revoked.
• Wrong environment variable — The SYNC_API_KEY environment variable is not set or points to the wrong key.

When you receive a 401, verify that:

1. Your API key is copied correctly with no extra whitespace.
2. The x-api-key header (not Authorization) is present in the request.
3. The key is still active on the API Keys page.

For a full list of error codes and resolution steps, see the Error Handling guide.