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
widthandheightare specified, they take precedence overaspect_ratio. - If
aspect_ratiois missing, for image it defaults to1:1and for video it defaults to16:9. - If only
heightis specified, the width will be calculated based onaspect_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 |
|---|---|---|---|---|
prompt | str | Yes | - | Text prompt driving generation. |
enhance_prompt | bool | - | False | Whether prompt enhancement should be enabled. Enabling this would slow down generation. |
multi_prompt | list[str] | None | - | None | Per-shot prompts for multi-shot passthrough vendors; length must match src_image_urls when used as reference frames. This is only supported/needed for Kling-v3 R2V. |
model | str | Yes | - | Model id, e.g. 'Wan2.2-A14B', 'Kling-v3'. |
task_type | str | Yes | - | one of T2I, I2I, T2V, I2V, R2V |
moderate | bool | - | True | Whether this request is screened by content moderation. |
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 image to video tasks, this can optionally specify 1 (first frame) or 2 (first & last frames) input images. |
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). |
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. |
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. |
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. |