> 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. # List Generations GET https://api.sync.so/v2/generations Reference: https://sync.so/docs/api-reference/api/generate-api/list ## Authentication - `x-api-key` header (required) — API Key authentication via header ## Servers - `https://api.sync.so` (Default, default) - `https://dev-api.sync.so` (dev) - `http://localhost:3001` (local) ## Request ### Query parameters - `status` (list of enum, optional) — Filter generations by status. Accepts multiple statuses as a comma-separated list. - Allowed values: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `REJECTED` - `ids` (list of string, optional) — Filter generations by ID. Accepts multiple IDs as a comma-separated list. - `source` (list of string, optional) — Filter generations by source. Accepts multiple sources as a comma-separated list. - `projectId` (string, optional) — Return only generations in this project. Must be a UUID. A project you can't access returns an empty list. - `limit` (integer, optional) — Maximum number of generations to return (1-100). When set, results are ordered newest first and can be paged with `cursor`. - `cursor` (string, optional) — ID of the last generation on the previous page. Requires `limit`. ## Response ### 200 Generations retrieved successfully - `list of Generation` ## Errors ### 400 Bad Request Error Bad Request - Invalid input or unsupported model - `message` (GenerationErrorMessage, required) — A message describing the error. - `statusCode` (double, required) — The type of error that occurred. - `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors. - `suggestion` (string, optional) — A suggested fix an agent can act on. - `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId). - `docsUrl` (string, optional) — Link to the documentation page for the failing operation. - `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly. - `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN. - `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again. ### 401 Unauthorized Error Unauthorized - Invalid or missing authentication - `message` (GenerationErrorMessage, required) — A message describing the error. - `statusCode` (double, required) — The type of error that occurred. - `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors. - `suggestion` (string, optional) — A suggested fix an agent can act on. - `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId). - `docsUrl` (string, optional) — Link to the documentation page for the failing operation. - `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly. - `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN. - `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again. ### 500 Internal Server Error Internal Server Error - An unexpected failure on our side. The body carries errorCode internal_error and a requestId; include the requestId when contacting support. - `message` (GenerationErrorMessage, required) — A message describing the error. - `statusCode` (double, required) — The type of error that occurred. - `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors. - `suggestion` (string, optional) — A suggested fix an agent can act on. - `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId). - `docsUrl` (string, optional) — Link to the documentation page for the failing operation. - `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly. - `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN. - `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again. ## Types ### Generation - `createdAt` (datetime, required) — The date and time the generation was created. - `id` (string, required) — A unique identifier for the generation. - `input` (list of Input, required) — An array of input objects used for generation. - `model` (enum, required) — The name of the model used for generation. - Allowed values: `sync-3`, `lipsync-2`, `lipsync-1.9.0-beta`, `lipsync-2-pro`, `react-1` - `status` (enum, required) — The status of the generation. - Allowed values: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `REJECTED` - `error` (string, optional) — The error message if the generation failed. - `errorCode` (string, optional) — Stable, machine-readable error code if the generation failed (e.g. generation_input_video_inaccessible). The full catalog of codes, messages and suggested fixes is served unauthenticated at GET /v2/errors. - `options` (GenerationOptions, optional) — Options for the generation. - `outputDuration` (double, optional) — The duration of the output media. - `outputUrl` (string, optional) — The URL of the output media. - `outputFileName` (string, optional) — The sanitized filename applied to the output media. Characters outside letters, numbers, dashes and underscores are stripped and spaces become underscores, so this can differ from the value submitted. Null when no name was provided. - `segments` (list of GenerationSegment, optional) — The segments of the generation. - `segmentOutputUrl` (string, optional) — The URL of the segment output media. - `synthesizedAudioUrl` (string, optional) — The URL of the audio synthesized from a text (TTS) input. Only present for generations created with a TTS text input; reuse it as an audio input to keep the same take across generations. - `webhookUrl` (string, optional) — The URL to the webhook endpoint. - `projectId` (string, optional) — The id of the project this generation is attached to, or null when it belongs to no project. Set via the projectId field on the create request. - `generationEstimate` (GenerationEstimate, optional) — A completion-time estimate captured once when the generation is accepted. Populated only for generations created in sync's own apps, such as Sync Studio; the field is absent for generations created through the API today. ### GenerationErrorMessage A message describing the error. ### DialogueEditRetimeFailureSection The dialogue-edit section that removes too much speech to stay in sync. - `slotIndex` (integer, required) — Zero-based index of the section in the preview's `resultSlots`. - `sourceStartMs` (integer, optional) — Start of the section in the source video, in absolute milliseconds. - `sourceDurationMs` (integer, optional) — Length of the section in the source video, in milliseconds. ### Input An input item for a generation. ### GenerationOptions - `sync_mode` (enum, optional, default: bounce) — Defines how to handle duration mismatches between video and audio inputs. Ignored for image inputs (images have no intrinsic duration). See the [Sync Mode](/developer-guides/sync-mode) guide for the full behavior matrix. - Allowed values: `bounce`, `loop`, `cut_off`, `silence`, `remap` - `model_mode` (enum, optional, default: face) — edit region for the model. only works with react-1. defaults to face, which affects lipsync + emotions in the face region. Available options are lips/face/head. When head is selected, model generates natural talking head movements along with emotions + lipsync. - Allowed values: `lips`, `face`, `head` - `prompt` (string, optional, default: neutral) — Prompt for the generation. React-1 accepts emotion prompts; the appearance model accepts a free-form appearance edit instruction. - `prompt_image_uris` (list of string, optional) — Reference image URLs for appearance editing generations. - `i2v_prompt` (string, optional) — Prompt for image-to-video generation. - `temperature` (double, optional, default: 0.5) — option to control how expressive lipsync can be. 0 -> least expressive, 1 -> most expressive. default:0.5 - `active_speaker_detection` (ActiveSpeaker, optional) — Active speaker detection configuration. When enabled, automatically detects and applies lipsync only to the active speaker in videos with multiple people. Not supported for image inputs. - `face_boxes_url` (string, optional) — URL for precomputed face bounding boxes. - `refinement_enabled` (boolean, optional) — Whether to enable the refinement pass for the generation. - `blending_mode` (enum, optional) — Controls how generated frames blend into the source media. - Allowed values: `default`, `advanced`, `disabled` - `occlusion_detection_enabled` (boolean, optional, default: false) — Whether to detect occlusion during generation, slows down generation speed. - `output_format` (enum, optional, default: mp4, deprecated) — Deprecated output container setting; defaults to mp4. - Allowed values: `mp4`, `mov` - `fps` (double, optional, deprecated) — Deprecated output frame-rate setting. - `output_resolution` (list of double, optional, deprecated) — Deprecated output resolution setting, as exactly [width, height]. Each value must be finite and between 180 and 4096 inclusive. Invalid values are discarded and the option is treated as omitted. ### GenerationSegment Defines a video segment with its corresponding audio input. Used for multi-segment lipsync generations where different audio tracks can be applied to different video segments. - `audioInput` (SegmentAudioInput, required) — Audio configuration for this segment - `startTime` (double, optional) — Segment start time in seconds. Must be less than or equal to endTime. - `endTime` (double, optional) — Segment end time in seconds. Must be greater than or equal to startTime. - `startFrame` (double, optional) — Segment start frame. Use with endFrame instead of time bounds. - `endFrame` (double, optional) — Segment end frame. Use with startFrame instead of time bounds. - `optionsOverride` (SegmentOptionsOverride, optional) — Override generation options for this specific segment. ### GenerationEstimate A completion-time estimate produced when a generation is accepted. - `estimatedDurationSeconds` (double, required) — Estimated generation duration in seconds. - `estimatedFinishAt` (datetime, required) — Estimated completion timestamp a client shows for the remaining wait. - `delayedAt` (datetime, required) — Timestamp after which the generation is considered delayed relative to the estimate. - `supportAt` (datetime, required) — Timestamp after which contacting support is suggested. - `estimatedAt` (datetime, required) — When the estimate was computed. - `serverTime` (datetime, required) — Current server time, stamped when the response was built. - `calibrationAsOf` (datetime, required) — When the calibration snapshot behind the estimate was last refreshed. - `estimatorVersion` (string, required) — Version of the estimator that produced the estimate. - `confidence` (enum, required) — The estimate's confidence level. - Allowed values: `measured`, `approximate`, `fallback` - `source` (enum, required) — The data source the estimate was derived from. - Allowed values: `cohort`, `duration_neighbor`, `resolution_neighbor`, `model_pool`, `global_pool`, `fallback` - `sampleCount` (integer, required) — Number of historical samples that informed the estimate. - `scope` (enum, required) — Whether the generation is a Studio or non-Studio generation. - Allowed values: `studio`, `non_studio` - `durationBand` (string, required) — Duration bucket used to match the estimate against similar past generations. - `resolutionBand` (string, required) — Resolution bucket used to match the estimate against similar past generations. - `resolutionSource` (enum, required) — Whether the resolution came from the requested output, the input asset, or is unknown. - Allowed values: `input`, `requested_output`, `unknown` ### Video Video input for generation. Provide either `url` or `assetId` (one is required). - `type` ("video", required) - `refId` (string, optional) — Optional reference identifier for segment definitions. Use this when a segment needs to refer back to a specific visual input item. - `url` (string, optional) — URL of the video to be used for generation. Either `url` or `assetId` must be provided. - `assetId` (string, optional) — ID of a video asset from your media library. Either `url` or `assetId` must be provided. - `segments_secs` (list of list of double, optional, deprecated) — [DEPRECATED] Use the top-level [segments](/api-reference/api/generate-api/create#request.body.segments) array instead for multi-segment support. - `segments_frames` (list of list of integer, optional, deprecated) — [DEPRECATED] Use the top-level [segments](/api-reference/api/generate-api/create#request.body.segments) array instead for multi-segment support. frames 100 and 200 of the video ### Image Image input for sync-3 model. Use instead of video when generating from a static image. Provide either `url` or `assetId` (one is required). - `type` ("image", required) - `refId` (string, optional) — Optional reference identifier for segment definitions. Use this when a segment needs to refer back to a specific visual input item. - `url` (string, optional) — URL of the image to be used for generation. Either `url` or `assetId` must be provided. - `assetId` (string, optional) — ID of an image asset from your media library. Either `url` or `assetId` must be provided. ### Audio Recorded/Captured audio input - `type` ("audio", required) - `url` (string, optional) — URL of the audio to be used for generation. Either `url` or `assetId` must be provided. - `assetId` (string, optional) — ID of an audio asset from your media library. Either `url` or `assetId` must be provided. - `refId` (string, optional) — Reference identifier for this audio input, used to link audio inputs to specific segments when using [segments](/api-reference/api/generate-api/create#request.body.segments). Required when using segments array. ### TTS Text to speech input - `type` ("text", required) - `provider` (TTSProviderConfig, required) — Integration provider configuration - `refId` (string, optional) — Reference identifier for this audio input, used to link audio inputs to specific segments when using [segments](/api-reference/api/generate-api/create#request.body.segments). Required when using segments array. ### ActiveSpeaker Active speaker detection configuration - `auto_detect` (boolean, optional, default: false) — Whether to automatically detect and apply generation to the active speaker - `v3` (boolean, optional) — Whether to use ASD v3 - `frame_number` (integer, optional) — Frame index that corresponds to the provided coordinates for manual speaker selection - `coordinates` (list of integer, optional) — Pixel coordinates [x, y] in the source video frame identified by frame_number. They are forwarded as-is to active speaker selection; they are not normalized ratios. - `bounding_boxes` (list of list of integer, optional) — Per-frame array of bounding boxes [x1, y1, x2, y2] for the detected face, or null if no box for that frame. Use instead of frame_number + coordinates when you already have detection data. - `bounding_boxes_url` (string, optional) — URL to a JSON file containing bounding boxes. Use instead of inline bounding_boxes to avoid large payloads. The JSON must have a "bounding_boxes" array with one entry per frame. - `face_image` (string, optional) — Base64-encoded reference face image (128x128 WebP) for selected-speaker detection. ### SegmentAudioInput Audio input configuration for a specific segment. References an audio input by refId and optionally crops the audio to a specific time range. - `refId` (string, required) — Reference ID of the audio/text-to-speech input to use for this segment - `startTime` (double, optional) — Optional start time (in seconds) to crop the referenced audio. When specified, endTime must also be provided, and startTime must be less than or equal to endTime. - `endTime` (double, optional) — Optional end time (in seconds) to crop the referenced audio. When specified, startTime must also be provided, and must be greater than or equal to startTime. ### SegmentOptionsOverride Override generation options for a specific segment. Any options set here will override the top-level generation options for this segment only. - `sync_mode` (enum, optional, default: bounce) — Override the sync mode for this segment. - Allowed values: `bounce`, `loop`, `cut_off`, `silence`, `remap` - `temperature` (double, optional) — Override temperature (0-1) for this segment. - `occlusion_detection_enabled` (boolean, optional) — Override occlusion detection for this segment. - `active_speaker_detection` (ActiveSpeaker, optional) — Override active speaker detection for this segment. Useful when different segments have different speakers. ### TTSProviderConfig ### ElevenLabs - `name` ("elevenlabs", required) - `voiceId` (string, required) — sync voice id (copied from cloned voices in the Studio) or ElevenLabs voice ID. Required. - `script` (string, required) — script to be used for generation - `stability` (double, optional, default: 0.5) — determines how stable the voice is and the randomness between each generation. lower values introduce broader emotional range for the voice. higher values can result in a monotonous voice with limited emotion. - `similarityBoost` (double, optional, default: 0.75) — determines how closely the ai should adhere to the original voice when attempting to replicate it. ## Examples **Response** ```json [ { "createdAt": "2024-01-15T09:30:00Z", "id": "id", "input": [ { "type": "video", "url": "https://example.com/video.mp4" } ], "model": "lipsync-2", "status": "PENDING", "error": "error", "options": {}, "outputDuration": 1.1, "outputUrl": "", "webhookUrl": "" } ] ``` **SDK Code** ```python import requests url = "https://api.sync.so/v2/generations" headers = {"x-api-key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.sync.so/v2/generations'; const options = {method: 'GET', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.sync.so/v2/generations" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.sync.so/v2/generations") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.sync.so/v2/generations") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.sync.so/v2/generations', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.sync.so/v2/generations"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.sync.so/v2/generations")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```