Post v2generate — sync-api-v2

Request body

name of the model to use for generation.

projectIdstring

Attach this generation to a project (from POST /v2/projects) so it appears in Studio under that project.

webhookUrlstring

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.

outputFileNamestring

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

Example request

{
  "model": "lipsync-1.9.0-beta",
  "input": [
    {
      "type": "video",
      "url": "https://assets.sync.so/videos/samples/influencer.mp4"
    },
    {
      "type": "audio",
      "url": "https://assets.sync.so/audios/samples/re-record.mp3"
    }
  ],
  "options": {
    "prompt": "add a red hat to the speaker",
    "prompt_image_uris": [
      "https://example.com/appearance-preview.png"
    ],
    "i2v_prompt": "make the subject smile and look at the camera",
    "model_mode": "face",
    "temperature": 0.5,
    "sync_mode": "bounce",
    "blending_mode": "default",
    "active_speaker_detection": {
      "auto_detect": true,
      "use_v2": true,
      "v3": true,
      "frame_number": 123,
      "coordinates": [
        10,
        20
      ],
      "face_image": "data:image/webp;base64,..."
    },
    "face_boxes_url": "https://example.com/face-boxes.json",
    "occlusion_detection_enabled": true,
    "output_bucket_name": "my-bucket",
    "active_speaker": true,
    "pads": [
      0,
      5,
      0,
      0
    ],
    "speedup": 1,
    "output_format": "mp4",
    "fps": 25,
    "output_resolution": [
      1280,
      720
    ]
  },
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "webhookUrl": "https://your-server.com/webhook",
  "outputFileName": "generated_video.mp4",
  "dubParams": {
    "providerName": "elevenlabs",
    "targetLang": "es",
    "sourceLang": "en",
    "numSpeakers": 1
  }
}

Response

Job created successfully

idstring required

A unique identifier for the generation.

createdAtstring date-time required

The date and time the generation was created.

status'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'REJECTED' required

The status of the generation.

modelstring required

The name of the model used for generation.

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

segmentsobject[] required

The segments definition for the generation.

webhookUrlstring nullable

The URL to the webhook endpoint.

optionsobject

Options for the generation.

outputUrlstring nullable

The URL of the output media.

outputDurationnumber nullable

The duration of the output media.

segmentOutputUrlstring nullable

The URL of the segment output media.

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

synthesizedAudioUrlstring

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.

errorstring

The error message if the generation failed.

errorCodestring 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_percentnumber

The progress percentage of the generation (0-100). Only included when include=progress.

Example response

{
  "errorCode": "generation_input_video_inaccessible"
}