---
title: "POST /v2/generate"
method: POST
path: "/v2/generate"
tags: ["Generate"]
---

# POST /v2/generate

`POST /v2/generate`

## Request body

- CreateGenerationDto
  - `model` 'lipsync-2' | 'lipsync-1.9.0-beta' | 'lipsync-2-pro' | 'lipsync-2-mini' | 'sync-3' | 'react-1' | 'appearence-1', required — name of the model to use for generation.
  - `input` union[], required — Array of input objects. Standard lipsync requests without segments require exactly one visual input (video or image) and one audio or text input. Multi-segment lipsync requests require exactly one video plus one or more audio/text inputs; give each audio/text input a unique refId and reference it from segments[].audioInput.refId. Dubbed lipsync requests using dubParams require exactly one video and no audio/text input because the dubbed audio is extracted from that video.
    - union
      - union
        - object
          - `type` 'video', required
          - `url` string, required — CDN/HTTP URL to a source video. Either `url` or `assetId` is required.
          - `assetId` string — Sync asset ID for a previously uploaded video. Either `url` or `assetId` is required.
          - `segments_secs` array[] — Start and end time in seconds for each video segment to apply generation to
            - number[] — First number is start time, second number is end time
          - `segments_frames` array[] — Start and end frames for each video segment to apply generation to
            - number[] — First number is start frame, second number is end frame
        - object
          - `type` 'video', required
          - `url` string — CDN/HTTP URL to a source video. Either `url` or `assetId` is required.
          - `assetId` string, required — Sync asset ID for a previously uploaded video. Either `url` or `assetId` is required.
          - `segments_secs` array[] — Start and end time in seconds for each video segment to apply generation to
            - number[] — First number is start time, second number is end time
          - `segments_frames` array[] — Start and end frames for each video segment to apply generation to
            - number[] — First number is start frame, second number is end frame
      - union
        - object
          - `type` 'image', required
          - `url` string, required — CDN/HTTP URL to a source image. Either `url` or `assetId` is required.
          - `assetId` string — Sync asset ID for a previously uploaded image. Either `url` or `assetId` is required.
        - object
          - `type` 'image', required
          - `url` string — CDN/HTTP URL to a source image. Either `url` or `assetId` is required.
          - `assetId` string, required — Sync asset ID for a previously uploaded image. Either `url` or `assetId` is required.
      - union
        - object
          - `type` 'audio', required
          - `refId` string — Reference id used by `segments[].audioInput.refId` when a generation has more than one audio or text input.
          - `url` string, required — CDN/HTTP URL to a source audio file. Either `url` or `assetId` is required.
          - `assetId` string — Sync asset ID for a previously uploaded audio file. Either `url` or `assetId` is required.
        - object
          - `type` 'audio', required
          - `refId` string — Reference id used by `segments[].audioInput.refId` when a generation has more than one audio or text input.
          - `url` string — CDN/HTTP URL to a source audio file. Either `url` or `assetId` is required.
          - `assetId` string, required — Sync asset ID for a previously uploaded audio file. Either `url` or `assetId` is required.
      - TextInputItem
        - `type` 'text', required
        - `refId` string — Reference id used by `segments[].audioInput.refId` when a generation has more than one audio or text input.
        - `provider` ProviderItem, required
          - `name` string, required
          - `voiceId` string, required — Sync voice ID (copied from cloned voices in the Studio) or ElevenLabs voice ID. Required.
          - `script` string, required
          - `stability` number — Voice stability (0-1). Lower = more expressive, higher = more stable.
          - `similarityBoost` number — Voice similarity boost (0-1). Lower = more creative, higher = stricter adherence.
  - `options` GenerationOptions
    - `prompt` string — Prompt for the generation. For appearence-1, this is the appearance edit instruction sent with the video and reference images.
    - `prompt_image_uris` string[] — Reference image URLs for appearance editing generations. API consumers can pass direct reference images here, or pass the imageUrl returned by POST /v2/appearence/preview.
    - `i2v_prompt` string — Prompt for image-to-video generation. Defaults to none.
    - `model_mode` 'lips' | 'face' | 'head' — mode of the model to use for animation.
    - `temperature` number — generation temperature randomness between 0 and 1. note: only works for lipsync-2 based models.
    - `sync_mode` 'cut_off' | 'bounce' | 'loop' | 'silence' | 'remap' — lipsync mode when audio and video durations are out of sync.
    - `reasoning_enabled` boolean — Whether to analyze and correct frames with artifacts, occlusions, or extreme poses during generation, slows down generation speed.
    - `refinement_enabled` boolean — Whether to enable the refinement pass for the generation.
    - `blending_mode` 'default' | 'advanced' | 'disabled' — Controls how blending is applied during generation.
    - `active_speaker_detection` ActiveSpeaker
      - `auto_detect` boolean — Whether to detect active speaker automatically and apply generation to them.
      - `use_v2` boolean — Deprecated. ASD v2 is now the default; use v3 to opt into ASD v3.
      - `v3` boolean — Whether to use asd v3
      - `frame_number` number — Frame number selected for speaker selection
      - `coordinates` number[] — Pixel coordinates [x, y] in the source video frame identified by frame_number. Coordinates are forwarded as-is to active speaker selection; they are not normalized ratios.
      - `face_image` string — Base64 encoded face image for selected speaker (128x128 WebP)
    - `face_boxes_url` string — URL for precomputed face bounding boxes.
    - `occlusion_detection_enabled` boolean — Whether to detect occlusion during generation, slows down generation speed.
    - `output_bucket_name` string — Name of the output bucket
    - `active_speaker` boolean — Whether to detect active speaker and apply generation to them.
    - `pads` number[] — Padding values
    - `speedup` 1 | 2 | 3 | 4 — downscale inputs for faster generations. used to preview changes.
    - `output_format` 'mp4' | 'mov' — format of the output media that is generated.
    - `fps` number — Frames per second (FPS) for the output video
    - `output_resolution` string[] — Resolution of the output video [width, height]
  - `segments` GenerationSegmentItem[] — one or more segments definition to apply edits to
    - `startTime` number — Segment start time in seconds
    - `endTime` number — Segment end time in seconds
    - `startFrame` number — Segment start frame (0-indexed)
    - `endFrame` number — Segment end frame (0-indexed)
    - `audioInput` SegmentAudioItem, required
      - `refId` string, required — Reference to an audio input by refId
      - `startTime` number — Start time (seconds) to crop audio
      - `endTime` number — End time (seconds) to crop audio
  - `projectId` string — Attach this generation to a project (from POST /v2/projects) so it appears in Studio under that project.
  - `webhookUrl` string — Webhook URL for generation status updates. When the generation reaches a terminal state, Sync sends a POST request with the generation payload and a Sync-Signature header (`t=<unix>,v1=<hmac_sha256>`). Verify the signature with the organization webhook secret from GET /v2/organizations/webhook/secret. HTTPS is strongly recommended.
  - `outputFileName` string — filename for the generated output (up to 255 characters). Characters outside letters, numbers, dashes and underscores are stripped and spaces become underscores, so "My Clip!.mp4" is stored as "My_Clipmp4".
  - `dubParams` DubDto
    - `providerName` 'elevenlabs' — Provider to use for dubbing. Defaults to ElevenLabs.
    - `targetLang` 'en' | 'gu' | 'no' | 'sl' | 'pa' | 'ta' | 'az' | 'gl' | 'is' | 'sw' | 'my' | 'fi' | 'el' | 'he' | 'lt' | 'ms' | 'sv' | 'fr' | 'ca' | 'hr' | 'lv' | 'ro' | 'sd' | 'th' | 'tn' | 'pl' | 'ceb' | 'da' | 'hu' | 'mr' | 'tl' | 'ug' | 'wo' | 'zu' | 'zh' | 'hi' | 'as' | 'ha' | 'kk' | 'ki' | 'rn' | 'ky' | 'st' | 'te' | 'war' | 'ak' | 'be' | 'cs' | 'ka' | 'mn' | 'bo' | 'ts' | 'ar' | 'ss' | 'nl' | 'tr' | 'af' | 'bs' | 'et' | 'rw' | 'ne' | 'ko' | 'it' | 'es' | 'sq' | 'eu' | 'kn' | 'sk' | 'su' | 've' | 'pt' | 'am' | 'hy' | 'doi' | 'de' | 'jv' | 'mk' | 'ja' | 'vi' | 'cy' | 'nso' | 'uk' | 'bg' | 'id' | 'lg' | 'yo' | 'ml' | 'fa' | 'tg' | 'ur' | 'uz' | 'ru' | 'fil', required — Target language code for dubbing (e.g., "es" for Spanish, "fr" for French).
    - `sourceLang` 'auto' | 'en' | 'gu' | 'no' | 'sl' | 'pa' | 'ta' | 'az' | 'gl' | 'is' | 'sw' | 'my' | 'fi' | 'el' | 'he' | 'lt' | 'ms' | 'sv' | 'fr' | 'ca' | 'hr' | 'lv' | 'ro' | 'sd' | 'th' | 'tn' | 'pl' | 'ceb' | 'da' | 'hu' | 'mr' | 'tl' | 'ug' | 'wo' | 'zu' | 'zh' | 'hi' | 'as' | 'ha' | 'kk' | 'ki' | 'rn' | 'ky' | 'st' | 'te' | 'war' | 'ak' | 'be' | 'cs' | 'ka' | 'mn' | 'bo' | 'ts' | 'ar' | 'ss' | 'nl' | 'tr' | 'af' | 'bs' | 'et' | 'rw' | 'ne' | 'ko' | 'it' | 'es' | 'sq' | 'eu' | 'kn' | 'sk' | 'su' | 've' | 'pt' | 'am' | 'hy' | 'doi' | 'de' | 'jv' | 'mk' | 'ja' | 'vi' | 'cy' | 'nso' | 'uk' | 'bg' | 'id' | 'lg' | 'yo' | 'ml' | 'fa' | 'tg' | 'ur' | 'uz' | 'ru' | 'fil' — Source language code. Defaults to "auto" for automatic detection.
    - `numSpeakers` number — Deprecated and ignored by Dubbing v2; speaker count is detected automatically.

## Response `201`

Job created successfully

- Generation
  - `id` string, required — A unique identifier for the generation.
  - `createdAt` string, date-time, required — The date and time the generation was created.
  - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'REJECTED', required — The status of the generation.
  - `model` string, required — The name of the model used for generation.
  - `projectId` string, nullable — 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.
  - `input` object[], required — An array of input objects containing type and URL.
    - `type` string
    - `url` string
  - `segments` object[], required — The segments definition for the generation.
  - `webhookUrl` string, nullable — The URL to the webhook endpoint.
  - `options` object — Options for the generation.
  - `outputUrl` string, nullable — The URL of the output media.
  - `outputDuration` number, nullable — The duration of the output media.
  - `segmentOutputUrl` string, nullable — The URL of the segment output media.
  - `outputFileName` string, nullable — The sanitized filename applied to the output media. Non-alphanumeric characters (except dashes and underscores) are stripped and spaces become underscores, so the value here is the canonical name used for the downloaded file - it may differ from what was submitted. Null when no name was provided.
  - `synthesizedAudioUrl` string — The URL of the audio synthesized from a text input. Only present for generations created with a TTS text input; reuse it as an audio input to keep the same take across generations.
  - `error` string — The error message if the generation failed.
  - `errorCode` string, nullable — Stable machine-readable error code if the generation failed. The full catalog with messages and suggested fixes is served at GET /v2/errors.
  - `progress_percent` number — The progress percentage of the generation (0-100). Only included when include=progress.

## Other responses

- `400` — Bad Request - Invalid input or unsupported model
- `401` — Unauthorized - Invalid or missing authentication
- `409` — Conflict - the controller rejected a duplicate backend submission (errorCode generation_conflict). Public create requests do not currently accept a client-supplied generation id or idempotency key, so do not blindly retry ambiguous network failures.
- `422` — Unprocessable Entity - submit-time validation failed (e.g. an optional projectId was provided but does not reference a project in your organization)
- `429` — Too Many Requests - concurrency limit reached (errorCode concurrency_limit_reached). Includes activeGenerations, concurrencyLimit, retryAfterSeconds and the Retry-After / X-Sync-Concurrency-Limit / X-Sync-Active-Generations headers
- `500` — Internal Server Error - unexpected failure (errorCode internal_error). Includes the requestId for support
- `503` — Service Unavailable - the generation service or a dependency is temporarily unavailable, or media validation exceeded its bounded deadline (errorCode controller_unavailable / controller_dependency_error / generation_media_probe_unavailable / generation_media_probe_timeout). Includes a Retry-After header
- `504` — Gateway Timeout - controller submission exceeded its bounded deadline with an unknown outcome (errorCode controller_timeout). Do not blindly retry. Includes a Retry-After header

## Changes

- **2026-08-27** `595901a0ee97` — 8 info
  - added the optional property `suggestion` to the response with the `400` status
  - added the optional property `suggestion` to the response with the `401` status
  - added the optional property `suggestion` to the response with the `409` status
  - added the optional property `suggestion` to the response with the `422` status
  - …4 more
- **2026-08-08** `9b2af21c2e0e` — 258 info
  - request property `dubParams/allOf[#/components/schemas/DubDto]/numSpeakers` deprecated (media type: application/json)
  - request property `dubParams/allOf[#/components/schemas/DubDto]/numSpeakers` deprecated (media type: multipart/form-data)
  - added the new `af` enum value to the request property `dubParams/allOf[#/components/schemas/DubDto]/sourceLang` (media type: application/json)
  - added the new `af` enum value to the request property `dubParams/allOf[#/components/schemas/DubDto]/sourceLang` (media type: multipart/form-data)
  - …254 more
- …earlier changes not shown

[Full history](https://skmtc.dev/sync/apis/sync-api-v2/changes/v2/generate/post.md)

---

[API](https://skmtc.dev/sync/apis/sync-api-v2.md) · [All operations](https://skmtc.dev/sync/apis/sync-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sync/sync-api-v2/revisions/595901a0ee97/schema)