> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Troubleshooting

> Common issues and solutions for the sync. labs lip sync API. Fix authentication errors, stuck generations, rate limits, lip sync quality, billing, TTS failures, upload formats, and more.

Running into an issue? Check the common problems and solutions below. Most issues can be resolved quickly with the right steps.

#### Why am I getting a 401 Unauthorized error?

A 401 error means your API key is missing or invalid. To fix this:

1. Make sure you're including the `x-api-key` header in every API request
2. Verify your API key is correct — copy it directly from [Settings > API Keys](https://sync.so/settings/api-keys)
3. If your key still doesn't work, regenerate a new one in the [Sync Labs Studio](https://sync.so/settings/api-keys)

See the [Authentication guide](/api-reference/guides/authentication) for full details on setting up your API key.

#### My generation is stuck in PENDING

Generations typically complete in 30 to 120 seconds depending on video length and model. If your generation appears stuck:

1. Use [polling](/api-reference/api/generate-api/get) or [webhooks](/api-reference/guides/webhooks) to check the current status
2. Wait at least 2 minutes before assuming something is wrong — longer videos take more time
3. If a generation is still in PENDING after 5 minutes, contact support at [support@sync.so](mailto:support@sync.so)

Avoid re-submitting the same job repeatedly, as this may increase queue times.

#### Studio says 'Media validation is temporarily unavailable'

This message indicates a temporary failure while checking the input media. Retry with backoff and check that any hosted input URL is reachable. If it persists, contact [support@sync.so](mailto:support@sync.so) with the project link, event or request ID if shown, and the file type, size, and duration. Check the project's generation history before submitting again if the earlier submission's outcome is unclear.

#### I'm hitting 429 Rate Limit errors

A 429 can indicate a request-rate limit or your plan's generation concurrency limit. Check the response body and headers before retrying.

1. For `rate_limit_exceeded`, wait for the reported retry interval and use exponential backoff.
2. For `concurrency_limit_reached`, wait for an active generation to finish. Check `Retry-After`, `X-Sync-Concurrency-Limit`, and `X-Sync-Active-Generations` when present.
3. Use [List Generations](/api-reference/api/generate-api/list) to inspect active jobs and [Concurrency & Rate Limits](/api-reference/guides/rate-limits) to understand the limits.
4. Use the [Batch API](/api-reference/guides/batch-processing) for eligible large workloads.

#### The lip sync quality is poor

Output quality depends heavily on your input video, audio, and model choice. For best results, ensure the speaker's face is front-facing, well-lit, and occupies a reasonable portion of the frame at a minimum of 480p resolution. Avoid obstructions like hands, microphones, or hair covering the mouth area. Use clean audio without background music or overlapping speakers, as noise degrades lip-to-audio alignment. For model selection, [lipsync-2](/models/lipsync) handles the majority of videos well and preserves natural speaking style, while [lipsync-2-pro](/models/lipsync#lipsync-2-pro) uses diffusion-based super resolution for the best results with beards, teeth, and fine facial detail. For longer videos, audio-video duration mismatches can cause drift — use the [`sync_mode`](/developer-guides/sync-mode) parameter (e.g., `cut_off`, `bounce`, or `remap`) to control how mismatches are handled.

See [Media Content Tips](/compatibility-and-tips/media-content-tips) for detailed guidance on input quality.

#### Output colors look different or seams appear after compositing

For color-sensitive pipelines, especially when you composite Sync Labs output back onto the original source, use SDR BT.709 input with explicit color tags and prefer H.264 `yuv444p` (4:4:4) instead of `yuv420p` (4:2:0) or `yuv422p` (4:2:2). Sync Labs processes frames in RGB, so 4:2:0 and 4:2:2 input requires chroma upsampling during YUV to RGB conversion and can make small color shifts more visible at composite boundaries. H.264 outputs are re-encoded and may not preserve the original bitrate exactly; matching bitrate is not a reliable fix for color differences. See [Preserving Color During Generation](/compatibility-and-tips/media-formats-support#preserving-color-during-generation) for recommended export settings.

#### My media format is not supported

Sync Labs supports a wide range of video and audio formats. If your file isn't accepted:

1. Check the [Media Formats Support](/compatibility-and-tips/media-formats-support) page for the full list of supported formats
2. Convert your file using FFmpeg:
   ```bash
   # Convert video to MP4
   ffmpeg -i input.avi -c:v libx264 -c:a aac output.mp4

   # Convert audio to WAV
   ffmpeg -i input.ogg -ar 16000 output.wav
   ```

#### My webhook isn't receiving events

If your [webhook](/api-reference/guides/webhooks) endpoint isn't getting called:

1. **HTTPS required** — Your endpoint must be a publicly accessible HTTPS URL
2. **Check firewall rules** — Make sure incoming POST requests from Sync Labs' servers aren't blocked
3. **Verify the URL** — Double-check the webhook URL you passed in your API call
4. **Test locally** — Use a tool like [ngrok](https://ngrok.com/) to expose a local server for testing
5. **Check response codes** — Your endpoint must return a 2xx status code to acknowledge receipt

#### Python SDK installation fails

If you're having trouble installing the Python SDK:

1. **Check your Python version** — The SDK requires Python 3.8 or higher
   ```bash
   python --version
   ```
2. **Upgrade the package** — Try reinstalling with the latest version:
   ```bash
   pip install --upgrade syncsdk
   ```
3. **Use a virtual environment** — Avoid conflicts with other packages:
   ```bash
   python -m venv .venv
   source .venv/bin/activate
   pip install syncsdk
   ```

See the [Python SDK Guide](/developer-guides/sdk-python) for full setup instructions.

#### TypeScript SDK issues

If the TypeScript SDK isn't working as expected:

1. **Check your Node.js version** — The SDK requires Node.js 18 or higher
   ```bash
   node --version
   ```
2. **Reinstall the package**:
   ```bash
   npm i @sync.so/sdk
   ```
3. **Check your package.json** — Make sure `@sync.so/sdk` is listed in your dependencies
4. **TypeScript version** — Ensure you're using TypeScript 4.7 or higher if using TypeScript

See the [TypeScript SDK Guide](/developer-guides/sdk-typescript) for full setup instructions.

#### Output has watermarks

Watermarks appear on free accounts and watermark-required plans. To access clean outputs:

* Upgrade to **Creator or higher** on legacy usage billing, or **Starter or higher** on credit billing.
* See our [Billing](/docs/product/billing) page for plan details and pricing
* Eligible existing videos use the clean output automatically when it is available; regeneration is not needed for those videos. Refresh Studio after upgrading.
* An upgrade cannot remove a watermark burned into a historical output. Those videos require a new generation for a clean result.

#### Face not detected or wrong face selected

If Sync Labs can't detect a face or selects the wrong person:

1. **Ensure face is clearly visible** — The face should be unobstructed, well-lit, and occupy a reasonable portion of the frame
2. **Check face angle** — Frontal or near-frontal faces work best; extreme side profiles may not be detected
3. **Multi-person videos** — If there are multiple faces in the frame, use the [Speaker Selection](/developer-guides/speaker-selection) feature to target the correct person
4. **Resolution** — Very low-resolution video may make face detection unreliable; use at least 480p

See the [Speaker Selection guide](/developer-guides/speaker-selection) for details on selecting specific faces in multi-person videos.

#### How long does generation take and what if it seems stuck?

Generation time depends on the model, video length, and resolution. As a general guide: **lipsync-1.9.0-beta** is the fastest model, typically completing a 30-second clip in well under a minute. **lipsync-2** takes a few minutes for most videos and is the recommended default. **lipsync-2-pro** is 1.5--2x slower than lipsync-2 due to its diffusion-based super resolution step, so expect longer waits for premium quality. Higher resolution inputs and longer video durations increase processing time proportionally. To monitor progress, use [polling](/api-reference/api/generate-api/get) (check the `status` field on GET `/v2/generate/{id}`) or set up [webhooks](/api-reference/guides/webhooks) for real-time status callbacks when the job completes. If your generation remains in PENDING or PROCESSING for more than 10 minutes, the job may have encountered an infrastructure issue. Avoid resubmitting the same request repeatedly, as this creates duplicate queue entries and slows processing further. Instead, contact [support@sync.so](mailto:support@sync.so) with your generation ID for investigation.

#### I have a billing or payment issue — what should I do?

Sync Labs uses a subscription-plus-usage billing model processed through Stripe. Common payment issues include declined cards, unexpected charges appearing after cancellation (usage charges still apply until the end of your billing cycle), and unpaid usage invoices blocking new generations. If your card is declined, update your payment method at [sync.so/billing/subscription](https://sync.so/billing/subscription) — Stripe retries failed charges for up to 5 days before automatically cancelling the subscription. If you see a charge you do not recognize, check your usage history at [sync.so/billing/usage](https://sync.so/billing/usage) — usage invoices are generated automatically each time your accumulated spend hits your tier's threshold (6 dollars for Hobbyist, 20 for Creator, 50 for Growth, 250 for Scale). For refund requests, go to your billing page and click **Manage billing** to access Stripe's Cancel + refund flow directly. For any billing issue not resolved through the dashboard, email [support@sync.so](mailto:support@sync.so). See the [Billing](/docs/product/billing) page for full pricing and payment details.

#### Why does the lip sync look mismatched or out of sync on longer videos?

Lip sync drift on longer videos typically happens when the audio and video durations do not match precisely, or when the video contains segments where the speaker is not actively talking. Sync Labs processes long videos in 30--40 second chunks internally, so scene changes or cuts within those chunks can confuse face tracking and cause brief misalignment. To fix drift, set the [`sync_mode`](/developer-guides/sync-mode) parameter to `cut_off` (uses the shorter input duration) or `remap` (adjusts video speed to match audio). For videos over 1 minute with multiple scenes, consider splitting them into segments using the [Segments API](/developer-guides/segments), where each segment gets its own audio input for tighter control. Using [lipsync-2-pro](/models/lipsync#lipsync-2-pro) also improves quality in challenging footage. Ensure the input video shows the speaker actively talking throughout — static or still frames cannot produce good lip movements.

#### My text-to-speech generation failed or produced no audio

TTS works out of the box on all plans using Sync Labs' built-in ElevenLabs integration — no setup required. If you want more control, you can optionally bring your own ElevenLabs API key on Creator plans and above by configuring it at [Integrations settings](https://sync.so/settings/integrations). TTS failures most commonly stem from an invalid ElevenLabs voice ID or exceeding the 5,000-character script limit. Verify your `voiceId` is a valid ElevenLabs voice ID string (not a voice name or display label), and keep your `script` under 5,000 characters per generation request. For longer scripts, use the [Segments API](/developer-guides/segments) to split text across multiple TTS inputs with different time ranges. If the generation completes but produces audio-only output without video, ensure you included a valid video input in your request alongside the TTS input. For persistent `generation_text_length_exceeded` or `generation_input_validation_failed` errors, see the [Error Handling](/developer-guides/error-handling) page for detailed resolution steps.

#### My video or audio file won't upload or is rejected

Sync Labs accepts **MP4, MOV, WebM, and AVI** for video, and **WAV, MP3, OGG, FLAC, ALAC, and MP4 audio** with full support (WMA, M4A, and AAC have limited support due to licensing restrictions). If your file is rejected, first check the format against the [Media Formats Support](/compatibility-and-tips/media-formats-support) page. When using a `url` input, provide a publicly reachable URL that returns media bytes, not an HTML sharing or preview page. Private, authenticated, or expired URLs can fail. For local files or private media, use [Asset Uploads](/developer-guides/asset-uploads) and pass the returned `assetId`. The recommended video codec is **H.264 (High Profile)** at a maximum resolution of 4K (4096x2160 pixels); videos above 4K are rejected outright. Audio should use a 44.1kHz or 48kHz sample rate for best results. If your file uses an unsupported codec, convert it with FFmpeg: `ffmpeg -i input.avi -c:v libx264 -c:a aac output.mp4`. Videos missing an audio track or required metadata fields (duration, frame rate) will return a `generation_media_metadata_missing` error. Note that HDR (10-bit color) video is automatically normalized to SDR, which may alter your color grading.

#### How do I lip sync a video with multiple speakers?

For videos with multiple people visible in the frame, use the [Speaker Selection](/developer-guides/speaker-selection) feature to target the correct face. Set `options.active_speaker_detection.auto_detect` to `true` to let Sync Labs automatically identify the active speaker, or provide a manual `frame_number` and `coordinates` pointing to the target speaker's face for fully deterministic control. You can also supply per-frame `bounding_boxes` if you already run your own face detection. If your video has multiple speakers talking at different times (such as a two-person podcast or interview), use the [Segments API](/developer-guides/segments) to assign different audio inputs to different time ranges within the video — each segment can target a different speaker with its own audio. For best results, ensure each speaker's face is clearly visible and front-facing during their speaking segment. If Sync Labs selects the wrong face, provide explicit coordinates rather than relying on auto-detection. See the [Speaker Selection API guide](/developer-guides/speaker-selection) and [Segments guide](/developer-guides/segments) for complete code examples.

## Troubleshooting Quick Reference

### Generation Speed by Model

| Model                | Typical Speed                      | Best For                                       |
| -------------------- | ---------------------------------- | ---------------------------------------------- |
| `lipsync-1.9.0-beta` | Fastest — under 1 min for 30s clip | Fast legacy lipsync, cost-sensitive batch jobs |
| `lipsync-2`          | A few minutes for most videos      | General purpose, preserves speaking style      |
| `lipsync-2-pro`      | 1.5--2x slower than lipsync-2      | Premium quality, beards, teeth, facial detail  |

### Common Issues and Solutions

| Issue                           | Likely Cause                                               | Solution                                                                              |
| ------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| 401 Unauthorized                | Missing or invalid API key                                 | Include `x-api-key` header; regenerate key at sync.so/settings/api-keys               |
| 429 Rate Limit                  | Exceeded plan concurrency                                  | Implement exponential backoff; upgrade plan for higher limits                         |
| Generation stuck >10 min        | Infrastructure issue                                       | Do not resubmit; contact [support@sync.so](mailto:support@sync.so) with generation ID |
| Poor lip sync quality           | Bad input video/audio                                      | Front-facing face, good lighting, 480p+, clean audio; try lipsync-2-pro               |
| Color shift or compositing seam | 4:2:0 or 4:2:2 chroma upsampling or missing color metadata | Export SDR BT.709 with explicit tags and use H.264 `yuv444p`                          |
| Lip sync drift on long video    | Audio/video duration mismatch                              | Use sync\_mode (cut\_off, remap); split with Segments API                             |
| TTS generation failed           | Invalid voice ID or script >5,000 chars                    | Verify ElevenLabs voiceId; keep script under 5,000 characters                         |
| File rejected on upload         | Unsupported format or codec                                | Use MP4 (H.264) video, WAV/MP3 audio; max 4K resolution                               |
| Wrong face selected             | Multiple faces in frame                                    | Use Speaker Selection with auto\_detect or manual coordinates                         |
| Watermarks on output            | Free or Hobbyist plan                                      | Upgrade to Creator plan or higher                                                     |
| Billing charge unexpected       | Usage invoice hit threshold                                | Check usage at sync.so/billing/usage; thresholds: 6/20/50/250 dollars by tier         |

### Supported Input Formats

* **Video:** MP4, MOV, WebM, AVI (H.264 codec recommended, max 4K)
* **Audio:** WAV, MP3, OGG, FLAC, ALAC, MP4 audio (44.1kHz or 48kHz recommended)
* **TTS:** ElevenLabs integration, max 5,000 characters per generation

### Key Links

* Check generation status: GET `/v2/generate/{id}` or use webhooks
* Billing dashboard: sync.so/billing/usage
* Refund requests: sync.so/billing/subscription > Manage billing
* Support email: [support@sync.so](mailto:support@sync.so)