Troubleshooting

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
3. If your key still doesn’t work, regenerate a new one in the Sync Labs Studio

See the Authentication guide for full details on setting up your API key.

PENDING means the job is queued, not that it has failed. Queue and processing times depend on the model, video length, resolution, and current load. See Generation Times & Performance for model-specific estimates. If your generation appears stuck:

1. Use polling or 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

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

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 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.

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 to inspect active jobs and Concurrency & Rate Limits to understand the limits.
4. Use the Batch API for eligible large workloads.

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 handles the majority of videos well and preserves natural speaking style, while 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 parameter (e.g., cut_off, bounce, or remap) to control how mismatches are handled.

See Media Content Tips for detailed guidance on input quality.

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 for recommended export settings.

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

1. Check the Media Formats Support page for the full list of supported formats
2. Convert your file using FFmpeg:

   # 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

If your webhook 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 to expose a local server for testing
5. Check response codes — Your endpoint must return a 2xx status code to acknowledge receipt

If you’re having trouble installing the Python SDK:

1. Check your Python version — The SDK requires Python 3.8 or higher

   python --version
2. Upgrade the package — Try reinstalling with the latest version:

   pip install --upgrade syncsdk
3. Use a virtual environment — Avoid conflicts with other packages:

   python -m venv .venv
   source .venv/bin/activate
   pip install syncsdk

See the Python SDK Guide for full setup instructions.

If the TypeScript SDK isn’t working as expected:

1. Check your Node.js version — The SDK requires Node.js 18 or higher

   node --version
2. Reinstall the package:

   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 for full setup instructions.

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

• Upgrade to Creator or higher on usage billing, or Starter or higher on credit billing.
• See our 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.

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 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 for details on selecting specific faces in multi-person videos.

Generation time depends on the model, video length, resolution, and queue load. Check Generation Times & Performance for model-specific estimates; sync-3 and longer clips can normally take more than 10 minutes. Elapsed time alone does not establish an infrastructure failure. Monitor the status field with polling or use webhooks. If the job runs well past its estimate, check service status and contact support@sync.so with the generation ID, model, and elapsed time. Avoid resubmitting while the original job is still PENDING or PROCESSING, since a new request does not cancel it.

If a payment fails, update your payment method at sync.so/billing/subscription and retry it. If generations pause because of an unpaid invoice, open the Billing page and pay it. Check your usage history at sync.so/billing/usage if you do not recognize a charge. For refund requests, open the Billing page and select Manage billing and payment methods. For any billing issue that the dashboard does not resolve, email support@sync.so. See the Billing page for full pricing and payment details.

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. Scene changes or cuts can make face tracking harder. To fix drift, set the 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, where each segment gets its own audio input for tighter control. Using 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.

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. 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 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 page for detailed resolution steps.

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 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 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.

For videos with multiple people visible in the frame, use the 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 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 and Segments guide for complete code examples.

On a finished Studio result, select Generate subtitles to download an .srt file. Load it in your video player or editor. Subtitles are not burned into the video. Videos with no speech, no audio track, or a duration over 60 minutes cannot be subtitled. The button explains unavailable states; retry it after a temporary failure.

Open Settings > General. In profile picture, paste an HTTPS link to a hosted image and select save. The link must be no more than 1,024 characters. Image uploads and removing the picture are not supported. If saving fails, your previous picture remains.

Choose a voice and select Preview to hear its sample. Select Stop to end playback. Previewing the sample does not generate speech or change your script. Use Generate speech to create audio from your script. If Preview is unavailable, its tooltip explains why.

Select Download audio beside the finished speech preview to save the existing take. Downloading keeps the audio attached and does not regenerate it. Saved audio is also available from your Studio Library.

The Studio Pro Voice panel saves completed speech takes in Assets. Open Assets to reuse an earlier take. Apply adds the latest saved take without creating another copy. For an unsaved project, look under All Projects until you apply the take.

If the picker says you are offline, reconnect to load voices. Retry is unavailable while offline. If it says Couldn’t load voices. Try again., select Retry. If failures continue, try later or contact support.