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

Create an API Key

1. Open the API Keys page.
2. Optional: Enter a name for the key, such as production or staging. The name helps you tell keys apart, and it appears in the API Key column of usage exports. If you leave it blank, the key is named API key.
3. Select Create new key.
4. Copy the key from the dialog and store it securely. The full key is shown only once.

Rename or Revoke an API Key

Organization members see and manage only the keys they created. Organization admins and owners see every key in the organization and can rename or revoke any of them.

• Rename a key: On the API Keys page, select Edit key in the key’s row, enter the new name, then select Save key.
• Revoke a key: Select Revoke in the key’s row, then select Confirm. Revoking is permanent and immediately stops any service or application that uses the 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()

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();

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, and name each one after its environment. A compromised dev key then does not affect production traffic, and you can tell the keys apart when you revoke one or review usage.
• 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.