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. 'MiniMax-H3', 'Kling-v3'.
`task_type`	`str`	Yes	-	one of: T2I, I2I (image), T2V, I2V, R2V (video), UPSCALE (image or video based on input type), SHARPEN (video), 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.
`prompt_enhancer`	`str \| None`	-	`None`	What prompt enhancer to use. Options are: default, native. If not specified, the default will be used. default: use MachGen fine-tuned prompt enhancer for faster, quality output native: the original enhancer paired with the model (This is slower and should only be used if the default one shows issues.) If the model does not have one, this option will fallback to the default.
`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.
`mode`	`str \| None`	-	`None`	TRAINING only: what to produce. 'LORA' trains an adapter over the frozen base model; 'FULL_MODEL' tunes every weight.
`train_config`	`TrainConfig \| None`	-	`None`	Required for the TRAINING task type.
`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.
`adapter`	`str \| None`	-	`None`	LoRA selector for the model, if supported. Omit to use the model's default. Currently supported on `MiniMax-H3-Turbo` (T2V, I2V, R2V): `larryvrh_v4_step600_ema` - 6 steps. `lightx2v_fl2v_8step_v10_native` - 8 steps. `silveroxides_dareties_fro099_v2` - 6 steps. `plaguekind_parasyte_turbo` - 6 steps. `silveroxides_4to8_dareties_v2` - 6 steps. `hyperflow` - 8 steps.
`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.
`keyframe_indices`	`list[Literal[0, -1]] \| None`	-	`None`	I2V only: where each src_image_urls entry sits in the output, aligned 1:1 with that list. 0 is the first frame and -1 the last frame, so [0], [0, -1] and [-1] are the accepted values. Omitted keeps the positional reading (entry 0 first, entry 1 last). [-1] alone animates towards a single end frame and is honored only by models that declare it (MiniMax-H3).
`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.
`reference_video_start_secs`	`list[float] \| None`	-	`None`	R2V only: where each reference video starts being read, in seconds from the beginning of the clip, aligned 1:1 with src_video_urls as it stands after src_task_ids routing. Each value is >= 0 and must fall inside the clip; the remaining length is what the model sees and what is billed. Omitted reads every clip from 0. A non-zero start is honored only by models that declare it (MiniMax-H3).
`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.
`sharpen`	`bool`	-	`False`	Sharpens MiniMax-H3 480p/768p/2K videos
`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
`lyrics`	`str \| None`	-	`None`	T2M models that accept separate lyrics: the words to sing, with section labels such as [Verse] and [Chorus]. Required for YuE2; provide the musical style in TaskInput.prompt. Omit for models that do not support separate lyrics.
`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 models that support a requested duration: target audio length in seconds. Accepted ranges and defaults depend on the model. Omit for YuE2, which generates variable-length audio and does not accept a requested duration.
`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`	Audio encoding; supported values and defaults depend on the model. YuE2 supports only `flac`, which is also its default, and produces a `.flac` file. ElevenLabs T2S, T2D and T2SFX support `mp3_22050_32`, `mp3_24000_48`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`, `mp3_44100_192`, `opus_48000_32`, `opus_48000_64`, `opus_48000_96`, `opus_48000_128` and `opus_48000_192`. ElevenLabs T2M also supports `mp3_48000_128`, `mp3_48000_192`, `mp3_48000_240` and `mp3_48000_320`. ElevenLabs defaults to `mp3_44100_128`. MP3 is stored as `.mp3` and Opus as `.ogg`.
`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.
`progress`	`TaskProgress \| None`	-	`None`	Step progress while a TRAINING task is RUNNING; unset for task types that do not report it.

AccountResponse

Returned by GET /api/v0/billing/account (and by the client's get_account).

Field	Type	Required	Default	Description
`account_id`	`str`	Yes	-	ID of this account
`balance_micros`	`int`	Yes	-	Balance of this account (in microdollars)
`autoreload_enabled`	`bool`	-	`False`	If auto-reload is enabled on this account
`pending_tasks`	`int \| None`	-	`None`	Current number of scheduled but not running tasks under this account
`running_tasks`	`int \| None`	-	`None`	Current number of running tasks under this account

API Reference

On this page