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 (image), T2V, I2V, R2V, F2F (video), UPSCALE (image or video, following the model's upscale surface), T2S, T2D, T2SFX, T2M (audio)
`prompt`	`str`	Yes	-	Text prompt driving generation. Unused for T2D, whose text lives in audio_config.turns.
`enhance_prompt`	`bool \| None`	-	`None`	Enhance the prompt to get expected output. Most users should leave this in default setting. For new generation of models (LTX, MiniMax-H3 and beyond), turning off prompt enhancement would severely degrade quality. One should only disable for debugging purpose or advanced use cases.
`video_config`	`VideoConfig \| None`	-	`None`	Required for video task types.
`image_config`	`ImageConfig \| None`	-	`None`	Required for image task types.
`audio_config`	`AudioConfig \| None`	-	`None`	Required for audio task types.
`upscale_config`	`UpscaleConfig \| None`	-	`None`	Engine and tuning knobs for UPSCALE.
`seed`	`int \| None`	-	`None`	Seed for reproducible generation. If not specified, a random seed will be used.
`optimization_level`	`str \| None`	-	`None`	Speed/quality trade-off tier: 'STANDARD/FAST/EXPRESS'. Higher optimization level means more aggressive optimizations, while lower level means more quality details. When not set, default levels are automatically applied.
`src_image_urls`	`list[str] \| None`	-	`None`	Source / reference image URLs. For I2V, entry 0 is the start frame and an optional entry 1 is the end frame. For R2V, these are used as references, and `subject_to_image_ids` must be used if any @ handles are used in the prompt as references to the subjects. Public image URLs or base64 encoded data URLs can be used.
`src_video_urls`	`list[str] \| None`	-	`None`	Reference video URLs. Public http(s) URLs only.
`src_audio_urls`	`list[str] \| None`	-	`None`	Reference audio URLs for R2V surfaces that declare audio-reference support. Limits and whether audio may be sent alone are model-specific and enforced by the synced capability contract.
`src_task_ids`	`list[str] \| None`	-	`None`	The output artifact (video or image) generated from the upstream task(s) will be used as the input together with its input unless overridden in this task. For most tasks (UPSCALE etc.), this should be a singleton list only. Invalid input will be rejected.
`src_file_urls`	`list[str] \| None`	-	`None`	Public HTTPS document URLs or local paths for R2V surfaces that declare file input support. This mode may be mutually exclusive with ordinary media references on a given model. Local paths are uploaded by the Python client before submission.
`src_webpage_urls`	`list[str] \| None`	-	`None`	Publicly reachable HTTPS webpage URLs for R2V surfaces that can use a linked page as input. This mode may be mutually exclusive with files and ordinary media references on a given model.
`reference_video_operation`	`Literal[reference, edit, extend] \| None`	-	`None`	How the primary reference video is used on R2V surfaces that declare these operations. 'reference' conditions a new video, 'edit' modifies the primary clip while matching its framing and length, and 'extend' continues it with a requested output length. The primary clip is src_video_urls[0]. Omitted preserves legacy provider-classified behavior.
`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 family 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 family only.
`reference_order`	`list[ReferenceOrderItem] \| None`	-	`None`	R2V only: original order across image, video, and audio references. Each entry points to the matching src_*_urls list.
`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. Where a surface allows it, -1 asks the model to determine the length from the request, such as matching a reference clip or selecting a smart output duration. Allowed values are enforced by the synced capability contract.
`height`	`int \| None`	-	`None`	Output height in pixels. Required for generation (a missing height is rejected at submit). For UPSCALE on a video upscale model this is the target resolution tier - the output's shorter side - and both output dimensions are derived from the source, preserving its aspect ratio.
`width`	`int \| None`	-	`None`	Output width in pixels.
`aspect_ratio`	`str \| None`	-	`None`	Output aspect ratio. The model capability contract declares the omission default; most models use 16:9, while source-aware models may use adaptive. 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'. Supported for Seedance-2.0 and Seedance-2.0-Fast. 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 Video 3.0 and Omni 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 Video 3.0 or Omni multi-shot. '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 Video 3.0 and Omni 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 Video 3.0 and Omni 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.

AudioConfig

Required for audio task types (T2S speech, T2D dialogue, T2SFX sound effects, T2M music). Each field belongs to exactly one surface, named in its description.

Field	Type	Required	Default	Description
`voice_id`	`str \| None`	-	`None`	T2S only: the voice to speak the prompt.
`turns`	`list[DialogueTurn] \| None`	-	`None`	T2D only: ordered speaker turns. The prompt is unused for T2D - all spoken text lives here.
`duration_secs`	`float \| None`	-	`None`	T2SFX and T2M: length of the generated audio in seconds.
`stability`	`float \| None`	-	`None`	T2S and T2D: 0-1. Lower is more emotionally variable, higher is more consistent. eleven_v3 accepts only 0.0, 0.5, or 1.0. Omitted uses the model default.
`speed`	`float \| None`	-	`None`	T2S only: speaking rate multiplier. Omitted uses the model default.
`similarity_boost`	`float \| None`	-	`None`	T2S only: 0-1. How closely the output tracks the original voice. Omitted uses the model default.
`style`	`float \| None`	-	`None`	T2S only: 0-1. Style exaggeration. Higher values cost more latency. Omitted uses the model default.
`use_speaker_boost`	`bool \| None`	-	`None`	T2S only: boost similarity to the original speaker.
`output_format`	`str \| None`	-	`None`	All audio surfaces: codec_samplerate_bitrate, e.g. 'mp3_44100_128'. Only mp3 variants are accepted - generated audio is stored as .mp3. Omitted uses mp3_44100_128.
`apply_text_normalization`	`str \| None`	-	`None`	T2S and T2D: 'auto' (default), 'on', or 'off'. Controls whether numbers, dates, and abbreviations are spelled out before synthesis.
`prompt_influence`	`float \| None`	-	`None`	T2SFX only: 0-1. How literally the sound follows the prompt. Omitted uses the model default.
`loop`	`bool \| None`	-	`None`	T2SFX only: generate a seamlessly looping clip.
`force_instrumental`	`bool \| None`	-	`None`	T2M only: generate without vocals.
`composition_plan`	`CompositionPlan \| None`	-	`None`	T2M only: build the track segment by segment instead of from a prompt. Mutually exclusive with `prompt`, and the track length is the sum of the segment durations rather than `duration_secs`.

CompositionPlan

T2M only: build a track segment by segment instead of from a prompt. Mutually exclusive with prompt, and the segment durations are the track length.

Field	Type	Required	Default	Description
`chunks`	`list[MusicChunk]`	Yes	-	Ordered segments of the track.

MusicChunk

One segment of a CompositionPlan.

Field	Type	Required	Default	Description
`text`	`str`	-	`''`	Sung or spoken text for this segment. Empty for instrumental.
`duration_ms`	`int`	Yes	-	Segment length in milliseconds.
`positive_styles`	`list[str] \| None`	-	`None`	Styles this segment should have.
`negative_styles`	`list[str] \| None`	-	`None`	Styles this segment should avoid.
`context_adherence`	`str \| None`	-	`None`	How closely this segment follows the surrounding ones: 'low', 'medium', or 'high'. Omitted uses the model default.

DialogueTurn

One speaker turn in a T2D request. All spoken text lives in these turns, not in prompt.

Field	Type	Required	Default	Description
`voice_id`	`str`	Yes	-	Voice speaking this turn.
`text`	`str`	Yes	-	What this speaker says.

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`	The executor's measured generation duration once COMPLETED.
`active_generation_time_secs`	`float \| None`	-	`None`	Current wall-clock elapsed duration for the active RUNNING attempt; unset outside RUNNING.
`upload_time_secs`	`float \| None`	-	`None`	Time spent uploading the asset after generation.
`queue_time_secs`	`float \| None`	-	`None`	Current queue elapsed time while PENDING; the final queue wait through the control-plane trial insert after generation begins.
`execution_provider`	`str \| None`	-	`None`	Who ran the execution - "machgen" whenever any stage of the task ran on MachGen GPUs, otherwise "partner".
`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

On this page