MachGen - Docs: API Reference

The request, configuration, and response models shared by the REST API and the Python client.

These models define the generation request body, its configuration objects, and the status response. They are identical across the REST API and the Python client.

TaskInput

The JSON body of POST /api/v0/generate (and the argument to the client's submit_task). model and task_type are required; the rest depend on the task type.

How is size determined?

For image/video sizing config, VideoConfig and ImageConfig take 3 optional params: width, height and aspect_ratio. The following strategy will be followed:

If both width and height are specified, they take precedence over aspect_ratio.
If aspect_ratio is missing, for image it defaults to 1:1 and for video it defaults to 16:9.
If only height is specified, the width will be calculated based on aspect_ratio (and rounded up if needed).
Other cases are considered invalid and rejected.

Some models accept only a fixed set of explicit width×height sizes and do not use the height + aspect_ratio derivation above; for those, pass one of the model's supported sizes. height is required for all documented image and video task types.

Field	Type	Required	Default	Description
`model`	`str`	Yes	-	Model id, e.g. 'Wan2.2-A14B', 'Kling-v3'.
`task_type`	`str`	Yes	-	one of T2I, I2I, T2V, I2V, R2V
`prompt`	`str`	Yes	-	Text prompt driving generation.
`enhance_prompt`	`bool \| None`	-	`None`	Whether prompt enhancement should be enabled. Enabling this would slow down generation but would improve quality. By default, if this is not explicitly set we will let the model determine the default behavior. Users can still explicitly force it to enable/disable by setting this field based on the requirement.
`video_config`	`VideoConfig \| None`	-	`None`	Required for video task types.
`image_config`	`ImageConfig \| None`	-	`None`	Required for image task types.
`seed`	`int \| None`	-	`None`	Seed for reproducible generation. If not specified, a random seed will be used.
`src_image_urls`	`list[str] \| None`	-	`None`	Source / reference image URLs. Only needed for tasks that require input images like I2I, I2V, R2V. Refer to the API docs for concrete examples of how to use this and what inputs are allowed. For I2V, entry 0 is the start frame and an optional entry 1 is the end frame on models that support it (Seedance-2.0, Kling-v3, LTX-2.3-Pro, Vidu-Q3-Turbo, Vidu-Q3-Pro); a second image returns 400 elsewhere.
`src_video_urls`	`list[str] \| None`	-	`None`	Reference video URLs. Only supported for Seedance-2.0 R2V, which accepts up to 3 clips of 2-15s each (15s combined).
`src_audio_urls`	`list[str] \| None`	-	`None`	Reference audio URLs. Only supported for Seedance-2.0 R2V, which accepts up to 3 clips totalling 15s. Audio may not be the only reference - at least one image or video is required.
`subject_to_image_ids`	`dict[str, list[int]] \| None`	-	`None`	R2V only: maps a subject name to the indices of its reference images in src_image_urls, e.g. {'alice': [0, 1], 'bob': [2]}. The prompt may address a subject via '@name'. Honored by vendors with named subjects (Vidu reference2video).
`subject_to_video_ids`	`dict[str, list[int]] \| None`	-	`None`	R2V only: subject_to_image_ids for src_video_urls. A name may appear in only one of the three subject maps. Seedance-2.0 only.
`subject_to_audio_ids`	`dict[str, list[int]] \| None`	-	`None`	R2V only: subject_to_image_ids for src_audio_urls. A name may appear in only one of the three subject maps. Seedance-2.0 only.
`moderate`	`bool`	-	`True`	Whether this request is screened by content moderation.

VideoConfig

Required for video task types (T2V, I2V, R2V).

Field	Type	Required	Default	Description
`fps`	`int \| None`	-	`None`	Video frames per second. If omitted the default FPS would be used based on the model.
`duration_secs`	`int`	Yes	-	Video duration in seconds.
`height`	`int \| None`	-	`None`	Output height in pixels. Required for generation (a missing height is rejected at submit).
`width`	`int \| None`	-	`None`	Output width in pixels.
`aspect_ratio`	`str \| None`	-	`None`	Output aspect ratio. The default is 16:9 if omitted. The width of the output will be updated to match the height based on the aspect ratio, rounded up to the nearest integer.
`bitrate_mode`	`str \| None`	-	`None`	Encode quality for the delivered video: 'standard' or 'high'. Only supported for Seedance-2.0. Omitted -> the vendor default.
`infer_steps`	`int \| None`	-	`None`	Number of denoising / inference steps. Higher values trade more compute for potentially finer detail. This is a best-effort match: if the model does not support it the model default is used.
`audio`	`bool \| None`	-	`None`	Whether the video should include audio. Note: some models do not support audio, or the audio is always on (e.g. Veo 3.1). In those cases this field has no effect.
`guidance_scale`	`list[float] \| None`	-	`None`	Classifier-free guidance scale(s). Controls how strongly the output adheres to the prompt: higher values follow the prompt more closely at the cost of diversity. If the model supports multiple guidance scales, these will be applied in a sequence (e.g. per stage or per denoising phase). This is a best-effort match: if the model does not support it, or does not support the number of scales provided, the model default is used.
`multi_prompt`	`list[str] \| None`	-	`None`	Per-shot text prompts for Kling-v3 multi-shot video (`shot_type` 'customize'). 1-6 shots, paired 1:1 with `shot_durations`. The top-level `prompt` is ignored when this is set.
`shot_type`	`str \| None`	-	`None`	Enables Kling-v3 multi-shot (T2V / I2V). 'customize' splits the video into the shots given by `multi_prompt` + `shot_durations`; 'intelligence' derives the shots from the single `prompt`. Omitted -> single-shot.
`shot_durations`	`list[int] \| None`	-	`None`	Per-shot durations in seconds for `shot_type` 'customize'; one per `multi_prompt` entry, each >= 1, summing to `duration_secs`.
`negative_prompt`	`str \| None`	-	`None`	What the video should avoid. Kling-v3 only. Omitted -> the vendor default ('blur, distort, and low quality').
`element_ids`	`list[int] \| None`	-	`None`	Kling-v3 only: ordered Kling element library ids (<=3) to include. The prompt references them via `@handle` (see `element_handles`), rewritten to Kling's positional `\<\<\<element_N>>>` at submit.
`element_handles`	`list[str] \| None`	-	`None`	Kling-v3 only: the `@handle` for each `element_ids` entry (same order). Each `@handle` in the prompt is rewritten to `\<\<\<element_N>>>` for the vendor while the stored prompt keeps it.

ImageConfig

Required for image task types (T2I, I2I).

Field	Type	Required	Default	Description
`height`	`int \| None`	-	`None`	Output height in pixels. Required for generation (a missing height is rejected at submit).
`width`	`int \| None`	-	`None`	Output width in pixels.
`aspect_ratio`	`str \| None`	-	`None`	Output aspect ratio. The default is 1:1 if omitted. The width of the output will be updated to match the height based on the aspect ratio, rounded up to the nearest integer.
`infer_steps`	`int \| None`	-	`None`	Number of denoising / inference steps. Higher values trade more compute for potentially finer detail. This is a best-effort match: if the model does not support it the model default is used.
`guidance_scale`	`list[float] \| None`	-	`None`	Classifier-free guidance scale(s). Controls how strongly the output adheres to the prompt: higher values follow the prompt more closely at the cost of diversity. If the model supports multiple guidance scales, these will be applied in a sequence (e.g. per stage or per denoising phase). This is a best-effort match: if the model does not support it, or does not support the number of scales provided, the model default is used.

TaskStatusResponse

Returned by GET /api/v0/tasks/{task_id} (and by the client's get_task_state and wait).

Field	Type	Required	Default	Description
`task_id`	`str`	Yes	-	Server-assigned id; poll status and download the asset with it.
`metadata`	`TaskMetadata`	Yes	-	Echo of the resolved task parameters.
`task_output`	`dict[TaskOutputType, str] \| None`	-	`None`	Per output-type asset locators, as they become available.
`moderation`	`ModerationResult \| None`	-	`None`	Structured moderation verdict when the task failed or was blocked by moderation.
`status`	`TaskStatus`	Yes	-	Current task status.
`error_msg`	`str \| None`	-	`None`	Failure reason, set when status is FAILED.
`generation_time_secs`	`float \| None`	-	`None`	Time spent on actual generation.
`upload_time_secs`	`float \| None`	-	`None`	Time spent uploading the asset after generation.
`queue_time_secs`	`float \| None`	-	`None`	Time spent waiting in the queue for generation to begin.
`execution_provider`	`str \| None`	-	`None`	Actual provider of the terminal execution trial.
`overflow_converted`	`bool`	-	`False`	Whether long queuing moved this task off self-hosted capacity to an on-demand provider. Readable before the task finishes.

API Reference

TaskInput

VideoConfig

ImageConfig

TaskStatusResponse

On this page