sync. labs

View saved version →

---
name: ai-video-to-talking
description: Add or replace dialogue in AI-generated video with sync. labs (sync.so). Takes a clip from Veo, Kling, Sora, Runway, Hailuo, Luma, Seedance, Wan or any other video generator, with the user's audio or a line that sync. voices, and lip-syncs the character so they actually speak. Also plans the source clip so it lip-syncs well, and handles scenes with several shots or two characters talking. Use when the user wants an AI character, avatar, UGC-style ad actor or generated presenter to talk, add a voice to an AI video, or make a talking AI video from a prompt. Not for real footage that already has a voiceover to match (lipsync), still images (talking-photo), or translating a video (translate-and-dub).
license: MIT
compatibility: Needs the sync. MCP server or a SYNC_API_KEY. See references/connect.md. sync. doesn't generate video; the clip comes from the user or another tool.
---

# Make an AI video talk

Delivers an MP4 of the generated character speaking the agreed line, in a voice that fits them, with matching lips. sync. doesn't make the clip itself. It comes from the user, or from a video-generation tool you can use in this session.

If no sync. tools are available, follow [references/connect.md](references/connect.md) first. Without the MCP tools, use the REST requests in [references/api.md](references/api.md).

## Steps

1. **Get the clip.**
   - **The user has one:** save it as in [references/media-input.md](references/media-input.md).
   - **The user only has an idea:** if you can generate video here, write the prompt with [references/source-clip.md](references/source-clip.md) so the face lip-syncs well. If you can't, give the user that prompt to paste into their video tool, and continue once they have the clip.
2. **Check the clip** before spending anything: one clearly visible face per shot, the mouth unobstructed, and how many shots or cuts it has. If it has cuts or two characters, plan which part each line covers now. The timeline is built in step 7, after the lines, voices and cost are agreed.
3. **The line.** Use the user's exact words. If they want you to write it, draft a line that fits the character and the clip's length, about 2.5 words per second (an 8-second clip holds about 20 words), and get approval.
4. **The voice.** Either the user's own audio (save it like the clip), or a script and a voice: call `voices_list` and suggest two or three that fit the character's age, energy and setting. Clone a voice with `voices_clone` only if the user explicitly asks and owns, or has permission to use, the sample. Cloning saves a voice to the account, can count against plan limits, and isn't idempotent: confirm the sample and the name, call it once, and after a lost or failed response list voices with `voices_list` to see whether it was saved before trying again. Never retry it on your own or change the sample or name to get around an error.
5. **Fit the timing.** Generated clips are short, so the speech often runs longer:
   - Speech a little longer: `bounce` (the default) or `loop` keeps the character on screen.
   - Speech much longer: shorten the line, generate a longer clip, or use `remap` to slow the video down to fit.
   - Speech shorter: `silence` keeps the rest of the clip without speech, `cut_off` ends the video with the speech.
6. **Quote, confirm, create.** Call `generations_estimate-cost` with `model: "sync-3"` and the `script` or `audioDuration`, plus `videoDuration` and `syncMode` when the mode is `cut_off` or `silence`. This prices the lipsync only; for a script, say the length is approximate and that speech synthesis is billed separately. Show the clip, the line, the voice and the estimate, and wait for approval. Then call `lipsync_create` once with `videoAssetId`, the speech (`script` with `voiceId`, or the audio), `model: "sync-3"`, any `options.sync_mode`, a new `idempotencyKey`, a new UUID as `projectCreationKey` and a short `projectName`. sync-3 handles styliz

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: batch-lipsync
description: Lip-sync many videos at once with sync. labs (sync.so), from a CSV, spreadsheet, folder or list. Pairs each video or avatar with its own audio or script, quotes the whole run, works within the plan's concurrency limit or uses the Batch API, resumes safely without paying twice, and collects every output. Use for bulk or batch lipsync of supplied audio or scripts, personalized video at scale (one video per lead, customer or recipient name), ad and creative variants, many voiceovers onto one presenter, or any "do this for each row" lipsync job. Not for one video (lipsync), translating videos into other languages (translate-and-dub for one video, localize-campaign for several).
license: MIT
compatibility: Needs the sync. MCP server or a SYNC_API_KEY. The Batch API and the bundled script need a SYNC_API_KEY and Python 3.9+.
---

# Lipsync many videos

Delivers one MP4 per row of the user's list, plus a results table that maps each row to its output.

If no sync. tools are available and there's no `SYNC_API_KEY`, follow [references/connect.md](references/connect.md) first.

## 1. Build the manifest

Turn whatever the user gave you (a CSV, a spreadsheet, a folder of files, "this video with each of these 30 audio files") into a CSV in the working directory, one row per output video:

| Column | Meaning |
| --- | --- |
| `id` | A unique, stable row name, such as `lead-042` or `es-ad1`. It names the output and keys retries. |
| `video` | A local path, `https://` URL or sync. asset ID. Use `image` instead for a still picture (sync-3). |
| `audio` | A local path, URL or asset ID. Leave it empty when the row uses `script`. |
| `script`, `voice_id` | The words and a voice from `voices_list` (or `GET /v2/voices`), when there's no audio. |
| `sync_mode` | Optional: `bounce`, `loop`, `cut_off`, `silence` or `remap`. |

Show the user the row count and a few sample rows, and fix gaps before spending anything: missing files, rows with neither audio nor script, duplicate IDs. Columns the run doesn't use stay local. Scripts, media, file names and the row IDs (used as output names) are sent to sync., so use plain row IDs like `lead-042` rather than names or emails.

## 2. Quote the whole run

Sum one estimate per row: `generations_estimate-cost` with `model: "sync-3"` and each row's `audioDuration` or `script` (plus `videoDuration` and `syncMode` for `cut_off` or `silence`), or `python3 scripts/sync_batch.py estimate manifest.csv`. Show the total, the row count and the most expensive rows, and wait for approval of the total. Script rows are approximate and exclude speech synthesis. If some rows can't be priced, show the known subtotal and which rows are missing; don't present it as the total.

Offer a **pilot**: run the first one or two rows, let the user check them, then run the rest. A mistake in a shared input, such as a wrong voice or a badly framed avatar, then costs two generations instead of two hundred.

## 3. Run it

Pick the route:

- **The bundled script (preferred with a `SYNC_API_KEY` and a shell).** `python3 scripts/sync_batch.py run manifest.csv --out ./lipsync-out` uploads each local file once, creates one generation per row with a stable idempotency key, keeps to the plan's concurrency limit, waits, and downloads each result. Re-running the same command resumes: finished rows are skipped, submitted rows are polled instead of resubmitted, and a row whose inputs changed after submission is refused until it gets a new ID. Progress and output URLs are saved to `manifest.csv.state.json` and `results.csv`.
- **MCP batch tools, on Scale and above with 20 or more rows.** Call `batches_create` with one item per row (`requestId` set to the row's `id`, `payload` the generate body) and `dryRun: true` first. After approval, call it once without `dryRun`, then `batches_get` with `wait: true` until it finishes; its results list each row's `outputMediaUrl` or error. Batch creation isn't idempotent: after an uncl

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: edit-dialogue
description: Change or remove a few spoken words in a single-speaker video with sync. labs (sync.so), keeping the speaker's own voice and re-syncing the lips, with no reshoot. Use for fixing a misspoken word, a wrong name, number, price or date, a mispronunciation, a typo in a spoken line, or cutting a filler word or phrase. Not for replacing a whole script (lipsync with a new script), translation (translate-and-dub), or switching to a different voice.
license: MIT
compatibility: Needs the sync. MCP server. See references/connect.md.
---

# Fix spoken words

Delivers one MP4 where only the agreed words change. Everything else keeps the original picture and voice.

If no sync. tools are available, follow [references/connect.md](references/connect.md) first. The REST version of this workflow is in early access and needs features enabled per organization; see https://sync.so/docs/developer-guides/dialogue-editing.

## Inputs

- **Video:** one person speaking, up to 10 minutes, as a local file, public URL or sync. video asset ID.
- **The fix:** which words to change or remove, and what to say instead. Never guess the replacement words.

## Tools

| Step | Tool |
| --- | --- |
| Check support | `dialogue_get-options` |
| Create the project | `projects_create` |
| Save the video | `assets_upload`, `assets_create-upload-url` + `assets_create` (local files), or `assets_create` (URLs) |
| Transcribe | `dialogue-transcriptions_create`, `dialogue-transcriptions_get` |
| Preview the new audio | `dialogue-previews_create`, `dialogue-previews_get` |
| Quote | `dialogue-videos_estimate` |
| Create | `dialogue-videos_create` |
| Wait | `generations_get` |

## Steps

1. **Support.** Call `dialogue_get-options`. If Edit Dialogue isn't available for this account, say so and stop. Note whether it reports `keyedPreview`.
2. **Project.** Call `projects_create` with a new random UUID as `id`, a short `name` and `defaultWorkflow: "edit_dialogue"`. Save the returned `id` as `projectId`. Pass it wherever a tool asks for `projectId`, and add `projectIntent: "explicit"` only on tools that take that field.
3. **Save the video** into that project. Follow [references/media-input.md](references/media-input.md).
4. **Transcribe.** Call `dialogue-transcriptions_create` with the `projectId` and `videoAssetId`, then `dialogue-transcriptions_get` with the returned `id` until it completes. If the result includes a new `videoAssetId`, the video was copied into sync. storage: use that ID from here on. If more than one speaker is detected, explain that this workflow handles one speaker, and stop.
5. **Agree the edits.** Show the transcript lines around the fix. Turn the request into edits that use the transcript's word IDs:
   - `{"kind": "change", "wordId": "w35", "replacement": "Mia"}`, adding `"pronunciation": "meeah"` only for a name the voice might say wrong. Write respellings as plain words, without hyphens or capitals, which the voice may spell out.
   - `{"kind": "remove", "wordIds": ["w12", "w13"]}` for consecutive words.

   Confirm the edits with the user.
6. **Preview.** The preview clones the speaker's voice and can incur synthesis charges, so mention that when you confirm the edits. Call `dialogue-previews_create` with the edits and the `transcriptionJobId`, plus a new `idempotencyKey` saved before the call when `keyedPreview` is reported. If that call's outcome is unclear, retry only the identical request with the same key. Poll `dialogue-previews_get` until it completes, and share the preview audio. If some edits failed (a partial completion), for example because a replacement is too long for the gap it fills, say which, suggest shorter wording, confirm the revised edits, and make a new preview with `previousPreviewId`.
7. **Quote.** Call `dialogue-videos_estimate` with the completed preview's ID as `dialogueEditId` and `model: "sync-3"`. Show the estimate and wait for approval of both the preview and the cost.
8. **Create.** C

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: lipsync
description: Lip-sync one existing video of a real person to new speech with sync. labs (sync.so), so their mouth matches a new voiceover, re-recorded take, song, or a typed script that sync. voices. Accepts local files, URLs, sync. assets and YouTube, TikTok, Instagram or Facebook links. Use whenever the user wants to lipsync, lip sync or sync lips, match mouth movement to audio, "make him say…", replace the audio in a talking-head clip, or sync a clip to a song, even if they don't say "lipsync". Not for AI-generated characters or clips from Veo, Kling, Sora and similar tools (ai-video-to-talking), still pictures (talking-photo), translation (translate-and-dub), changing a few words in the original voice (edit-dialogue), or many videos at once (batch-lipsync).
license: MIT
compatibility: Needs the sync. MCP server or a SYNC_API_KEY. See references/connect.md.
---

# Lipsync a video

Delivers one MP4 of the video with the lips matched to the new speech.

If no sync. tools are available, follow [references/connect.md](references/connect.md) first. Without the MCP tools, use the REST requests in [references/api.md](references/api.md) for the same steps.

## Inputs

- **Video:** a local file, a public URL, a sync. video asset ID, or a social link.
- **Speech:** an audio file, URL or asset, or a script plus a voice.

Ask only for what's missing. Never invent the words.

## Tools

| Step | Tool |
| --- | --- |
| Save files | `assets_upload` (chat apps), or `assets_create-upload-url` then `assets_create` (local files) |
| Import a social link | `projects_create`, `assets_create` |
| Pick a voice (script only) | `voices_list` |
| Quote | `generations_estimate-cost` |
| Shorten long audio | `audio-trims_create`, `audio-trims_get` |
| Create | `lipsync_create` |
| Wait | `generations_get` |

## Steps

1. **Save the inputs.** Follow [references/media-input.md](references/media-input.md). Save each file once, and reuse the returned asset ID for every later step and retry. Check the input-quality list there and mention problems now, such as several faces or music under the voice.
2. **Voice.** For a script, call `voices_list`. Unless the user named a voice, suggest two or three that fit, and use the chosen voice's `id` as `voiceId`.
3. **Length.** When the speech and the video differ noticeably in length, ask how to handle it and pass the answer as `options.sync_mode`:
   - `bounce` (default): play the video forward, then in reverse, to cover longer speech
   - `loop`: repeat the video from the start
   - `cut_off`: stop the speech when the video ends
   - `silence`: keep the video going silently after the speech ends
   - `remap`: speed the video up or slow it down to fit the speech exactly

   If the audio is over the plan's length limit, offer `audio-trims_create` to keep its first part.
4. **Speaker.** If more than one face is visible, ask who should speak. Leave `options.active_speaker_detection` unset unless the user picks someone.
5. **Quote.** Call `generations_estimate-cost` with the model (`sync-3` unless the user chose another) and the speech's `audioDuration`, or the `script`. For `cut_off` or `silence`, also pass `videoDuration` and `syncMode`. This prices the lipsync only. For a script, say the length is approximate and that speech synthesis is billed separately.
6. **Confirm.** Show the video, the speech, the voice, any sync mode and the estimate, and wait for approval. Skip the wait only if the user already approved this exact request and cost.
7. **Create.** Call `lipsync_create` once with the video (`videoAssetId` or `videoUrl`), the speech (`audioAssetId`, `audioUrl`, or `script` with `voiceId`), the model, any `options`, a new `idempotencyKey`, and either the `projectId` of a project you created in step 1 (with `projectIntent: "explicit"`) or a new random UUID as `projectCreationKey` plus a short `projectName`. Save the keys before calling. If the response is lost or times out, the job may still have 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: lipsync-video
description: Lip-sync an existing video to new speech with sync. labs, from a voiceover, a re-recorded take, a song, or a typed script that sync. labs voices, including AI-generated clips and YouTube, TikTok, Instagram or Facebook links. Use for "lipsync this video to this audio", "make him say…", "match the lips to my voiceover" or "sync this clip to the song". Not for still pictures (talking-photo), translating speech into another language (translate-and-dub) or changing a few words in the original voice (edit-dialogue).
---

# Lipsync a video

Delivers one MP4 of the video with lips matched to the new speech.

## Inputs

- **Video**: a video file in this conversation, a public video URL, a Sync video asset ID, or a YouTube, TikTok, Instagram or Facebook link.
- **Speech**: an audio file, audio URL or Sync audio asset, or a script plus a voice.

Ask only for what is missing. Never invent the words.

## Tools

| Step | Tool |
| --- | --- |
| Save files from the chat | `upload-media` |
| Import a social link | `projects_create`, `assets_create` |
| Pick a voice (script only) | `voices_get-voices` |
| Quote | `generate_estimate-cost` |
| Shorten long audio | `trim-audio`, `get-audio-trim` |
| Create | `create-lipsync` |
| Wait for the result | `generate_get-generation` |

## Steps

1. **Save files.** For each file in this conversation (the video, or the user's audio), call `upload-media` once with `mediaType` `video` or `audio`. Use the returned asset IDs from here on, including for every retry; a file re-sent later becomes a different asset.
2. **Social links.** Create a project first with `projects_create`, using a new random UUID as `id`, a short `name` and `defaultWorkflow: "lipsync"`. Then call `assets_create` with the link, `type: "VIDEO"`, that `projectId` and `projectIntent: "explicit"`.
   - A 409 `import_in_progress` means the import is still running. Wait `retryAfterMs` (15 seconds if absent) and repeat the identical request until it returns an asset.
   - On `import_failed`, `import_not_enabled`, `import_unavailable` or a limit error, explain the reason, offer a file upload instead, and stop.
3. **Voice.** For a script, call `voices_get-voices`, suggest two or three fitting voices unless one was named, and use the returned `id` as `voiceId`.
4. **Length.** If the audio is noticeably longer or shorter than the video, ask how to handle it, and pass the answer as `options.sync_mode`:
   - `cut_off`: trim the longer one to match
   - `loop`: repeat the video from the start
   - `bounce`: play the video forward, then in reverse
   - `silence`: keep the video silent where the audio runs out
   - `remap`: speed up or slow down the video to match the audio

   If the audio is over a length limit, offer `trim-audio` to keep its first part, then quote again.
5. **Speakers.** If more than one face is visible, ask which person should speak. Leave `options.active_speaker_detection` unset unless the user picks a speaker.
6. **Quote.** Call `generate_estimate-cost` with the model (default `sync-3`) and the measured `audioDuration`, or the `script` for script input. For `cut_off` or `silence`, also pass `videoDuration` and `syncMode`. Label script quotes approximate and say speech synthesis is excluded.
7. **Confirm.** Show the video, speech, voice, any sync mode and the estimate, then wait for approval, unless this exact request and cost were already approved.
8. **Create.** Call `create-lipsync` once with:
   - the video as `videoAssetId` (saved or imported above) or `videoUrl`;
   - the speech as `audioAssetId`, `audioUrl`, or `script` with `voiceId`;
   - the model and any `options`;
   - a new `idempotencyKey`.

   For a project you just created in step 2, pass its `projectId` with `projectIntent: "explicit"`. Otherwise pass a new random UUID as `projectCreationKey` and a short `projectName`. On a lost response, retry once with the same keys and inputs.
9. **Wait and deliver.** Poll `generate_get-genera

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: localize-campaign
description: Localize a whole video campaign into several languages and markets with sync. labs (sync.so). Plans the video × language matrix, maps markets to languages, pilots one video so names and terms are right before spending on the rest, dubs and lip-syncs every version, and delivers consistently named files plus a review sheet per market. Use for several source videos across languages or markets, such as "make these ads in Spanish, German and Japanese", launching a campaign or a course in new markets, international or multi-market rollouts. Not for one video into a few languages (translate-and-dub), new speech in the same language (lipsync, batch-lipsync), or subtitles only.
license: MIT
compatibility: Needs the sync. MCP server or a SYNC_API_KEY. See references/connect.md.
---

# Localize a campaign

Delivers every video in every target language as a dubbed, lip-synced MP4 with a predictable name, plus a sheet the regional teams can review from.

If no sync. tools are available, follow [references/connect.md](references/connect.md) first. Without the MCP tools, each version is one `POST /v2/generate` with `dubParams`, as in [references/api.md](references/api.md).

## 1. Plan the matrix

1. **Videos.** List each source video with its name, length and where it comes from (a file, URL or social link).
2. **Markets to languages.** Turn markets into languages and confirm them with the user. Germany, Austria and Switzerland are all German; Brazil is Portuguese; most of LATAM is Spanish. Call `dubbing_get-options` and check that every language is supported, naming the closest option for any that isn't. Don't guess regional variants the options don't list.
3. **The matrix.** Show it as a table: one row per video, one column per language, and the total number of versions.
4. **Files.** Agree a naming pattern up front, by default `<campaign>_<video>_<lang>.mp4`, for example `spring24_hero-30s_de.mp4`.

## 2. Check what dubbing won't change

Before spending anything, tell the user what stays the same, so nobody is surprised in review:

- Text on screen, burned-in captions, logos and end cards stay in the source language.
- Music and sound effects carry over. Very loud music under the voice can lower the dub's quality.
- Brand names, product names and slogans can be translated or mispronounced. Ask which must stay untranslated.
- The lips can only be matched where a speaker is on screen. Voiceover-only shots still get the dubbed audio.

## 3. Quote, then pilot

1. **Project and inputs.** Call `projects_create` once for the campaign, with a new UUID `id`, the campaign name and `defaultWorkflow: "translate_and_dub"`. Save the returned `id` as `projectId`. Pass it wherever a tool asks for `projectId`, and add `projectIntent: "explicit"` only on tools that take that field. Save each source video into it once, as in [references/media-input.md](references/media-input.md).
2. **Quote.** Call `generations_estimate-cost` with `workflow: "translate-and-dub"`, `model: "sync-3"` and each video's length as `duration`. Multiply by the number of languages, and show the per-video, per-language and total cost, using the returned breakdown. If it reports external provider charges as excluded, say they're extra. Wait for approval of the total.
3. **Pilot.** Run one version first, usually the most important video in the most important language. Use `dubbing_create` with `videoAssetId`, `targetLang`, `sourceLang: "auto"`, `model: "sync-3"`, the `projectId` with `projectIntent: "explicit"`, and a new `idempotencyKey`. Wait for it with `generations_get` and `wait: true`. Ask the user, or a speaker of that language, to check names, terms and tone. Fix anything you can before the rest.

## 4. Run the rest

- Read `generationLimits.concurrency` from `account_get-context`, and keep that many versions in flight at most. On `concurrency_limit_reached`, wait `error.retryAfterMs` milliseconds and retry the identical request with the 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: setup
description: Connect sync. labs (sync.so) to this agent and get a first lip-synced video. Use when the user explicitly asks to install, set up, connect or get started with sync. labs, when sync. tools are missing or signed out, or for questions about their sync. account, plan or remaining credits. Media requests go to their workflow skill, which links to the same connection steps.
license: MIT
compatibility: Uses the hosted sync. MCP server (https://mcp.sync.so/mcp) or a SYNC_API_KEY.
---

# Set up sync. labs

Gets a new user from install to a first result in a couple of minutes. Setup itself never starts paid work.

## Steps

1. **Check the connection.** If sync. tools such as `account_get-context` are available, call `account_get-context` and `account_get-usage`, then go to step 3.
2. **Connect.** Follow [references/connect.md](references/connect.md) for this client: the hosted MCP server with sign-in for most people, or an API key for scripts and CI. If the client needs a restart to load the server, say so and stop there.
3. **Account.** Greet the user by organization name and say what's available: credits, the free allowance, or the plan's limits (`generationLimits.maxOutputDurationSeconds`, `generationLimits.concurrency`). Don't promote plans.
4. **What it can do.** Offer these, one example prompt each:
   - **Lipsync a video:** "Lipsync ./interview.mp4 to ./new-take.wav"
   - **Make a photo talk:** "Make this portrait say: welcome to the team"
   - **Make an AI clip talk:** "My Veo clip has no dialogue. Make the character say this line."
   - **Translate and dub:** "Dub this YouTube video into Spanish"
   - **Fix a few spoken words:** "Change the price I say in this video to $49"
   - **Localize a campaign:** "Make these 3 ads in Spanish, German and Japanese"
   - **Many videos at once:** "Lipsync each row of this CSV"
   - **Build it into an app:** "Add sync. lipsync to my Next.js app"
5. **Fastest first win.** If the user isn't sure, suggest a talking photo: one image and one line of text, no recording needed. Then follow the talking-photo skill: quote, get approval, create.

## Rules

- Quote before every paid generation and wait for approval.
- If there are no credits or free generations left, say so plainly and point to https://sync.so/billing/subscription. Don't start a job that will fail.
- Keep it to one short message for the account and the choices, then follow the user's lead.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: sync-api
description: Build sync. labs (sync.so) lipsync, dubbing and talking-image generation into an app, backend, script or pipeline with the sync. REST API or the official Python (syncsdk) and TypeScript (@sync.so/sdk) SDKs. Covers API keys, uploads, creating generations with idempotency keys, webhooks with signature checks, polling, models, cost estimates, error handling, concurrency limits and the Batch API. Use whenever code calls or should call the sync. API, for example "add lipsync to my Next.js app", "write a Python script that dubs videos with sync.", "handle sync. webhooks", "why does my sync. request return 429", or reviewing an existing sync. integration. Not for making one video in this chat (lipsync, talking-photo, translate-and-dub).
license: MIT
compatibility: Needs network access and a sync. API key in SYNC_API_KEY. Python 3.8+ or Node 18+ for the SDKs.
---

# Build with the sync. API

Builds a server-side integration that uploads media, saves each request before submitting it, tracks jobs to completion, and retries without starting duplicate paid work.

## Ground rules

- **Server-side only.** The API key goes in `SYNC_API_KEY` on the server, never in browser or mobile code. Browsers talk to your backend, and your backend talks to sync. Keys come from https://sync.so/settings/api-keys.
- **Base URL** `https://api.sync.so/v2`, header `x-api-key`.
- **SDKs:** Python `pip install syncsdk` (`from sync import Sync`), TypeScript `npm i @sync.so/sdk` (`new SyncClient()`). Both read `SYNC_API_KEY`. The SDKs cover generations (`create`, `get`, `list`) and batches. Some newer request fields can lag behind the API: image inputs, `dubParams`, `dialogueEdit`, `projectId`, uploads and cost estimates. When the installed SDK's types don't include one, call the endpoint over HTTP as the references show, instead of forcing the types.
- **Docs for anything not covered here:** https://sync.so/docs/llms-full.txt, plus the error catalog at `GET https://api.sync.so/v2/errors`, which needs no key.

## The flow to implement

1. **Get the media into sync.** Public `https://` URLs work directly. For user uploads or local files, use the three-step asset upload (presigned URL, `PUT`, register) and keep the returned asset ID. Don't proxy large files through your own API.
2. **Create the generation** with `POST /v2/generate` (SDK `generations.create`): the `model`, one visual input (video, or an image with sync-3) and one speech input (audio, or text with an ElevenLabs `voiceId`), plus optional `options`, `webhookUrl` and `outputFileName`. Send an `Idempotency-Key` header. Create the key once per user action, store it with your job record before the request, and reuse it on every retry. A retry with the same key and body replays the original generation instead of starting a paid duplicate.
3. **Find out when it's done.** Prefer a `webhookUrl`, and verify the `Sync-Signature` header ([references/webhooks.md](references/webhooks.md)). Keep polling `GET /v2/generate/{id}` as a fallback: with `?wait=true&timeout=10` the server holds the request open up to 10 seconds. Terminal statuses are `COMPLETED`, `FAILED` and `REJECTED`. The video is at `outputUrl`. Copy it to your own storage if you need to keep it.
4. **Handle errors.** Use the table in [references/api.md](references/api.md). The cases that matter most are a `429 concurrency_limit_reached` (wait `retryAfterSeconds`, then retry with the same key), plan and credit errors (stop and tell the user), and unknown outcomes after a timeout (retry with the same key, never a new one).

Full examples: [references/python.md](references/python.md) and [references/typescript.md](references/typescript.md). REST with curl: [references/api.md](references/api.md).

## Choosing options

- **Model:** default to `sync-3`, the most capable: it handles close-ups, profile angles, occlusion and still images. `lipsync-2-pro` and `lipsync-2` cost less per second. Take current model names from `GET /v2

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: talking-photo
description: Make a still image talk with sync. labs (sync.so). Turns a photo, portrait, headshot, or an illustrated or AI-generated character with a human-like face into a lip-synced video from a typed script (sync. voices it) or the user's own audio. Use for "make this photo talk", "make this picture say…", talking avatars, talking headshots, animating a portrait or character with speech, or image-to-video with dialogue, including when the user has no picture yet and wants one made first. Not for moving video footage (lipsync or ai-video-to-talking), translation (translate-and-dub) or changing words in an existing video (edit-dialogue).
license: MIT
compatibility: Needs the sync. MCP server or a SYNC_API_KEY. See references/connect.md.
---

# Make a photo talk

Delivers one MP4 of the picture speaking the user's words. The video is as long as the speech.

If no sync. tools are available, follow [references/connect.md](references/connect.md) first. Without the MCP tools, use the REST requests in [references/api.md](references/api.md) for the same steps.

## Inputs

- **Picture:** a local image, an image attached in chat, a public URL, or a sync. image asset ID. If the user has no picture and you can generate images, offer to make one: one clear face, looking at the camera, mouth closed, head and shoulders, plain background. Otherwise ask for one.
- **Speech:** a script, which needs a voice, or an audio file, URL or asset.

Ask only for what's missing. Never invent the words. If the user asks you to write them, draft a short script and get approval before quoting.

## Tools

| Step | Tool |
| --- | --- |
| Save files | `assets_upload` (chat apps), or `assets_create-upload-url` then `assets_create` (local files) |
| Pick a voice (script only) | `voices_list` |
| Quote | `generations_estimate-cost` |
| Create | `lipsync_create` |
| Wait | `generations_get` |

## Steps

1. **Save the inputs.** Follow [references/media-input.md](references/media-input.md) for the picture and any audio. Public URLs and asset IDs need no upload. Before spending money, check that the image shows exactly one clear, reasonably large human or human-like face. Animals and non-humanoid characters aren't supported.
2. **Voice.** For a script, call `voices_list`. Unless the user named a voice, suggest two or three that fit the character, each with a few words on its style. Use the chosen voice's `id` as `voiceId`; never invent one.
3. **Quote.** Call `generations_estimate-cost` with `model: "sync-3"`, `visualType: "image"`, and either the `script` or the audio's `audioDuration`. This prices the lipsync only. For a script, say the length is approximate and that speech synthesis is billed separately.
4. **Confirm.** Show the picture, the script or audio, the voice and the estimate, and wait for approval. Skip the wait only if the user already approved this exact request and cost.
5. **Create.** Call `lipsync_create` once with the picture (`imageAssetId` or `imageUrl`), the speech (`script` with `voiceId`, or `audioAssetId` or `audioUrl`), `model: "sync-3"`, a new `idempotencyKey`, a new random UUID as `projectCreationKey`, and a short `projectName` such as "Talking portrait". Images work only with sync-3, and `sync_mode` doesn't apply to them. Save the keys before calling. If the response is lost or times out, retry once with the same keys and inputs, which returns the original generation if it exists.
6. **Wait and deliver.** Call `generations_get` with the returned `id` and `wait: true`, repeating until the status is final. Give the exact `outputMediaUrl` unchanged, and offer one next step: another line, another voice, or dubbing it into another language.

## When something fails

- **The picture is rejected** (no clear face, several faces, too small): explain why and suggest a clearer head-and-shoulders picture.
- **Out of credits or over a plan limit:** quote the message plainly, without promoting plans.
- **Any other rejection:** 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: translate-and-dub
description: Translate one source video's speech into another language with sync. labs (sync.so) and re-sync the speaker's lips to the dubbed audio, from a local file, URL, or YouTube, TikTok, Instagram or Facebook link, into one or several languages. Use for "dub this video into Spanish", "translate my YouTube video to Japanese", AI dubbing, video translation, or a multilingual version of one video. Not for subtitles or captions only, translating a text document, lip-syncing audio the user already has (lipsync), or a whole campaign of several videos across markets (localize-campaign).
license: MIT
compatibility: Needs the sync. MCP server or a SYNC_API_KEY. See references/connect.md.
---

# Translate and dub a video

Delivers one dubbed MP4 per target language, with lips matched to the new audio. The dubbed voice follows the original speaker's.

If no sync. tools are available, follow [references/connect.md](references/connect.md) first. Without the MCP tools, use `dubParams` on `POST /v2/generate` as shown in [references/api.md](references/api.md).

## Inputs

- **Video:** a local file, a public URL, a sync. video asset ID, or a social link. It needs its original speech on the audio track.
- **Target languages:** ask if none were given. Use `sourceLang: "auto"` unless the user names the spoken language.

## Tools

| Step | Tool |
| --- | --- |
| Check languages | `dubbing_get-options` |
| Create the project | `projects_create` |
| Save the video | `assets_upload`, `assets_create-upload-url` + `assets_create`, or `assets_create` with a link |
| Quote | `generations_estimate-cost` |
| Create | `dubbing_create` |
| Wait | `generations_get` |

## Steps

1. **Languages.** Call `dubbing_get-options` and check every requested language. For any that isn't supported, name the closest supported option.
2. **Project.** Call `projects_create` with a new random UUID as `id`, a short `name` and `defaultWorkflow: "translate_and_dub"`. Save the returned `id` as `projectId`. Pass it wherever a tool asks for `projectId`, and add `projectIntent: "explicit"` only on tools that take that field.
3. **Save the video** into that project. Follow [references/media-input.md](references/media-input.md).
4. **Quote.** Call `generations_estimate-cost` with `workflow: "translate-and-dub"`, `model: "sync-3"` and the video's length as `duration` in seconds. Show the returned estimate and its breakdown per language and in total. If it reports external provider charges as excluded, say they're extra.
5. **Confirm.** Show the video, the languages and the estimate, and wait for approval. Skip the wait only if the user already approved this exact request and cost.
6. **Create.** For each language, call `dubbing_create` once with `videoAssetId`, `targetLang`, `sourceLang`, `model: "sync-3"`, the `projectId` with `projectIntent: "explicit"`, and its own new `idempotencyKey`. If a response is lost, retry that language once with the same key and inputs.
7. **Wait and deliver.** Poll `generations_get` with each `id` and `wait: true` until each is final. Dubbing takes longer than plain lipsync, so tell the user it may take several minutes. Give each exact `outputMediaUrl`, unchanged and labelled with its language.

## Rules

- One paid job per language. Never resubmit a language to check progress.
- If one language fails, report it and keep the others.
- Text on screen isn't translated, and the output is dubbed video only. Don't offer subtitles or a translated transcript as a substitute.
- If dubbing fails with a voice-provider error and the user connected their own ElevenLabs key to sync., the cause is usually that key's credits or validity. Say so.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: troubleshoot
description: Diagnose and recover sync. labs (sync.so) work that failed, stalled, was rejected or errored, then resume it safely without paying twice. Covers sign-in and missing tools, rejected inputs, plan, credit and concurrency limits, stuck or slow jobs, lost responses after a timeout, dubbing provider errors and poor lipsync quality, and can report the problem to the sync. team. Use for "my lipsync failed", "why was this rejected", "it's been processing forever", "I got a 429 or 402", "the sync tools disappeared", or any sync. error message. Not for first-time setup (setup) or writing integration code (sync-api).
license: MIT
compatibility: Works best with the sync. MCP server connected. See references/connect.md.
---

# Troubleshoot sync. work

Finds out what actually happened, says it plainly, and resumes the work without starting a second paid job.

## 1. Gather the facts

Collect what's known before guessing: the tool or request that failed, the exact error text and code, and any generation, batch, project, asset or job ID. Then read the current state:

- A generation: `generations_get` with its `id`. Note `status`, `error` and `errorCode`.
- No ID: `generations_list` with a small `limit`, or `batches_list` for batches, to find it.
- The account: `account_get-context` for plan limits and concurrency, `account_get-usage` for credits.

Never ask for the user's API key or password, and don't paste signed media links into anything public.

## 2. Find the cause

| What you see | What it means | What to do |
| --- | --- | --- |
| Sign-in error, or the sync. tools are missing | The MCP connection is signed out, or the client hasn't loaded it | Reconnect with [references/connect.md](references/connect.md). Signing in in a browser tab doesn't sign in the agent's connection. A tool that's missing here may only exist in another client, such as Studio tools in ChatGPT. |
| `PENDING` or `PROCESSING` for a while | Normal for long or busy jobs. Dubbing and batches take longer than plain lipsync. | Keep polling the same ID. Pending isn't failed, and a second create won't make it faster. |
| A timeout or lost response after a create | The job may or may not have started | Look for it with `generations_list` (or `batches_list`), or retry the identical request with the same idempotency key, which returns the original if it exists. Never switch to a new key to "recover". |
| `concurrency_limit_reached` | The plan's limit on simultaneous jobs is reached | Wait `error.retryAfterMs` (or for a running job to finish), then retry the same request. More creates won't clear it. |
| `insufficient_credits`, `free_tier_generations_exhausted`, `generation_plan_duration_exceeded`, `plan_feature_unavailable` | A plan or balance limit | Quote the message and point to https://sync.so/billing/subscription. Don't retry, and don't switch accounts to get around it. |
| A 4xx about the input (format, resolution, face, length, speaker) | sync. refused the media or settings | Explain which input and why, and fix only that. Don't quietly change the model, speaker, language or trim. [references/media-input.md](references/media-input.md) has the input checklist. |
| `import_in_progress` | A social-link import is still running | Wait `retryAfterMs`, then repeat the identical call. |
| `FAILED` with a voice-provider error during dubbing | Often the user's own ElevenLabs key, if they connected one to sync. | Check that key's credits and validity. Removing it from sync. falls back to sync.'s own. |
| `COMPLETED`, but the lipsync looks wrong | Usually the source: a turned or covered face, several faces, music under the voice, low resolution | Go through the input checklist. If an older model was used, suggest `sync-3`. A new attempt is a new paid generation, so quote it first. |
| The result is there but the link or download failed | The output exists | Recover the link with `generations_get`. Don't generate again. |

Failed generations aren't c

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.