API Guides

Authentication

Sync 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:

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

You can also pass the key directly:

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

You can also pass the key directly:

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

API Key Security Best Practices

Your API key grants full access to the Sync 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 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.