API Guides

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:

from sync import Sync
# Reads SYNC_API_KEY from the environment automatically
sync = Sync()

You can also pass the key directly:

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

You can also pass the key directly:

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.