Video generation - GENGEN API

Video generation is asynchronous. First create a task, then retrieve it until it reaches a terminal state.

Request structure

{
  "model": "dreamina-seedance-2-0-260128",
  "mode": "image_first_frame",
  "prompt": "The product slowly rotates on a clean studio turntable.",
  "contentPreFilter": true,
  "assets": {
    "firstFrameImage": "https://example.com/product.jpg"
  },
  "controls": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive",
    "generateAudio": false
  },
  "providerOptions": {}
}

Generation modes

Mode	Required input	Typical use
`text_to_video`	`prompt`	Generate a new video from text
`image_first_frame`	`assets.firstFrameImage`	Animate a starting image
`image_first_last_frame`	First and last frame images	Control both ends of a shot
`multimodal_reference`	Reference image, video, or supported audio	Guide subject, style, or motion
`video_modify`	`assets.sourceVideo` and an explicit edit prompt	Modify an existing video
`video_extend`	`assets.sourceVideo` and an explicit extension prompt	Extend an existing video

If mode is omitted, GENGEN can infer the request shape from the supplied assets. Set it explicitly when you want predictable validation.

Seedance 2.5 task-type validation

For Seedance 2.5 omni-reference workflows, GENGEN maps an explicitly supplied normalized mode to BytePlus’s task-type hint:

GENGEN mode	BytePlus task type	Task-specific constraints
`multimodal_reference`	`reference`	No additional ratio or duration constraint
`video_modify`	`edit`	At least one 4–30 second source video, `ratio: "adaptive"`, and `duration: -1`
`video_extend`	`extend`	At least one source video and `ratio: "adaptive"`

An edit prompt must clearly describe the intended edit, such as adding, removing, replacing, or changing content. An extension prompt must clearly ask to extend or continue the source video. When mode is omitted, GENGEN leaves the upstream task-type hint at its default auto behavior. BytePlus classifies the request from its assets and prompt during processing. Constraint failures found after automatic classification are asynchronous and can use InvalidParameter.TaskTypeConstraint.

An explicit task type enables submission-time constraint validation, but BytePlus still checks prompt intent while processing the task. If the prompt describes a different operation, the task can fail asynchronously with InvalidParameter.TaskTypeMismatch.

Media inputs

assets accepts HTTPS URLs and owned asset:// references where supported.

firstFrameImage and lastFrameImage control boundary frames.
referenceImages accepts up to 30 references for Seedance 2.5 and up to 9 for Seedance 2.0 variants.
referenceVideos accepts up to 10 references for Seedance 2.5 and up to 3 for Seedance 2.0 variants.
referenceAudios accepts up to 10 audio references for Seedance 2.5. Audio can be its only multimodal reference input.
referenceAudio is the compatibility form for a single audio reference.
sourceVideo is used by video modification and extension.

Use GENGEN asset references for files already registered in the same workspace. Requests cannot use private assets owned by another workspace.

Output controls

Common controls include:

duration: model-dependent output duration in seconds; supported Seedance models also accept -1 for model-selected duration.
resolution: 480p, 720p, 1080p, or 4k, subject to model support.
ratio: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, or adaptive.
generateAudio: request synchronized audio when supported.
watermark: add a provider watermark.
returnLastFrame: return a last-frame image when supported.
outputFormat: mp4 or mov for Seedance 2.5. The default is mp4; this control is not available for other Seedance models.
serviceTier: default or flex, subject to model support.

Seedance 2.5 supports 4–30 second output at 480p, 720p, or 1080p. Its first-frame, first/last-frame, edit, and extend modes require adaptive ratio; video editing uses model-selected duration (-1). mp4 uses standard color precision and has broad compatibility with browsers, mobile devices, media players, and distribution platforms. mov preserves higher color precision and more consistent color and brightness for grading, keying, compositing, and other professional post-production workflows. For editing and extension, using MOV for both input and output is recommended.

Seedance 2.5 MOV output uses H.264 video encoding, YUV 4:4:4 chroma sampling, and PCM audio. Some players may not support this combination. VLC, mpv, and ffplay support it on macOS and Windows; IINA supports it on macOS.

Seedance 2.5 video editing with MOV output

{
  "model": "dreamina-seedance-2-5-260628",
  "mode": "video_modify",
  "prompt": "Replace the product in the source video with the product from the reference image.",
  "assets": {
    "sourceVideo": "https://example.com/source.mov",
    "referenceImages": [
      "https://example.com/product.png"
    ]
  },
  "controls": {
    "duration": -1,
    "resolution": "1080p",
    "ratio": "adaptive",
    "outputFormat": "mov",
    "generateAudio": true,
    "watermark": false
  }
}

Task lifecycle

Poll the retrieve endpoint at a reasonable interval. Treat succeeded, failed, cancelled, and the compatibility status completed as terminal. Do not treat a Seedance provider status of expired as terminal: continue polling the same task because it can resume and later succeed. GENGEN normalizes new responses where possible.

Creating a task reserves wallet balance. Retrieving a successful terminal result can finalize the corresponding charge. Deleting or cancelling a task changes remote and local task state.

Compatibility

Older integrations may still send provider-native content[] bodies or snake_case fields. They remain compatibility inputs, but new integrations should use assets, controls, and providerOptions.

​Request structure

​Generation modes

​Seedance 2.5 task-type validation

​Media inputs

​Output controls

​Seedance 2.5 video editing with MOV output

​Task lifecycle

​Compatibility

Request structure

Generation modes

Seedance 2.5 task-type validation

Media inputs

Output controls

Seedance 2.5 video editing with MOV output

Task lifecycle

Compatibility