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). 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. 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 and references/typescript.md. REST with curl: references/api.md.