Create Video Generation Tuning Job API - Alibaba Cloud Model Studio

Create a model fine-tuning training job for video generation. Datasets can be uploaded via API or mounted from OSS.

Prerequisites

Supported regions: The features described in this topic are only available in the Singapore region, and you must use an API Key from this region.
Account permissions: If you use an Alibaba Cloud sub-account (RAM user), you need to grant the sub-account permissions for model invocation, training, and deployment.
Configure environment variables: You have successfully obtained an API Key and configured it as an environment variable.
Preparation: You have read Fine-tuning video generation models to understand the supported models for fine-tuning, fine-tuning steps, data formats, and billing.

Create a fine-tuning job

Singapore

POST https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes

For Windows CMD, replace $DASHSCOPE_API_KEY with %DASHSCOPE_API_KEY%. For PowerShell, replace with $env:DASHSCOPE_API_KEY

Request Parameters

Headers

Content-Type string (Required)

Fixed value: application/json

Authorization string (Required)

API Key authentication, format: Bearer sk-xxxx.

Request Body

model string (Required)

Specifies the base model for fine-tuning.

Image-to-video based on first frame:

wan2.7-i2v: Supports both first-frame and first-and-last-frame fine-tuning. Switch via hyperparameter task_type; defaults to first-frame (i2v).
wan2.6-i2v
wan2.5-i2v-preview
wan2.2-i2v-flash

Image-to-video based on first and last frames:

wan2.7-i2v: Requires setting hyperparameter task_type to kf2v.
wan2.2-kf2v-flash

training_file_ids array[string] (Conditionally required)

Training dataset file ID array, supports multiple IDs. Use either this or training_datasets . If using training_datasets, this parameter is not needed. File IDs are obtained from the Upload File API.

validation_file_ids array[string] (Optional)

Validation dataset file ID array, supports multiple IDs. Use either this or validation_datasets . If using validation_datasets, this parameter is not needed. If neither is provided, the system will automatically split from the training set. File IDs are obtained from the Upload File API.

training_type string (Required)

Fine-tuning type. Currently only supports efficient_sft (LoRA efficient fine-tuning).

hyper_parameters object (Optional)

Hyperparameter configuration. For initial training, it is recommended to use the default hyperparameters. If the model performance is poor or training does not converge, you can try adjusting parameters such as n_epochs or learning_rate.

Hyperparameter properties

batch_size int (Required)

Batch size. The number of data samples sent to the model for training at once.

This parameter is a per-instance configuration. We recommend using the default value for each model. Do not adjust unless necessary.

wan2.7-i2v: Recommended value: 1.
wan2.6-i2v: Recommended value: 1.
wan2.5-i2v-preview: Recommended value: 4.
wan2.2-i2v-flash: Recommended value: 4.
wan2.2-kf2v-flash: Recommended value: 4.

NoteThe actual number of instances running for a training job is determined by platform scheduling. The Global Step output in training logs may differ from estimated results, but this does not change the total amount of training data or affect the final model performance.

n_epochs int (Required)

Number of training epochs. Recommended value: 50.

steps = n_epochs × ⌈dataset_size / batch_size⌉. It is recommended that total steps >= 800.

Example: With 5 data samples and batch_size=4, steps per epoch = ceil(5/4) = 2, minimum n_epochs = 800/2 = 400.

The recommended number of training epochs adjusts automatically based on data volume. Less data requires more epochs for sufficient learning; more data means each epoch contains more samples, thus fewer epochs are needed.
50 epochs is mainly suitable for small datasets with around 2 samples; when the data volume reaches 50-60 videos, it is usually recommended to train for about 3000-5000 steps.

ImportantThis parameter affects training billing. Please set it appropriately.

learning_rate float (Required)

Learning rate. Recommended value: 2e-5. Controls the magnitude of model weight updates. Too high may degrade the model, too low may result in minimal changes.

eval_epochs int (Required)

Validation interval. Recommended value: 20. Must be >= n_epochs/10. Specifies how many epochs between each validation evaluation during training.

max_pixels int (Required)

Maximum resolution for training videos. Sets the total pixel count (width x height) limit for training video resolution. The system only scales videos that exceed this value.

wan2.7-i2v: Recommended: 102400. Value range: 36864 (192x192) to 123904 (352x352).
wan2.6-i2v: Recommended: 36864. Value range: 16384 (128x128) to 36864 (192x192).
wan2.5-i2v-preview: Recommended: 36864. Value range: 16384 (128x128) to 36864 (192x192).
wan2.2-i2v-flash: Recommended: 262144. Value range: 65536 (256x256) to 262144 (512x512).
wan2.2-kf2v-flash: Recommended: 262144. Value range: 65536 (256x256) to 262144 (512x512).

split float (Optional)

Training set split ratio. Recommended value: 0.9. Value range: (0, 1).

Only effective when validation_file_ids. This parameter automatically splits a validation set from the training set proportionally. For example, 0.9 means 90% training set and 10% validation set.

max_split_val_dataset_sample int (Optional)

Maximum number of samples to automatically split from the training set as validation set. Recommended value: 5. Must be >= 1.

Only effective when validation_file_ids is not specified. This parameter sets an upper limit for the validation set size: validation_count = min(total_dataset × (1 - split), max_split_val_dataset_sample)

save_total_limit int (Optional)

Checkpoint save limit. Recommended value: 10. Limits the maximum number of models saved; the system will only keep the last N checkpoints.

lora_rank int (Optional)

LoRA low-rank matrix dimension. Recommended value: 32. This value determines the size of fine-tuning parameters; larger values provide stronger fitting capability but slower training speed. Must be a power of 2ⁿ (e.g., 16, 32, 64).

lora_alpha int (Optional)

LoRA weight scaling factor. Recommended value: 32. Used to adjust the influence of fine-tuned parameters on the original model weights. Must be a power of 2ⁿ (e.g., 16, 32, 64).

task_type string (Optional)

Fine-tuning task type. Only effective for the wan2.7-i2v model; other models do not need to set this parameter.

i2v (default): First-frame-to-video fine-tuning.
kf2v: First-and-last-frame-to-video fine-tuning.

training_datasets Array of Dataset (Conditionally required)

Training dataset file list. Use either this or training_file_ids. If using training_file_ids, this parameter is not needed.

Dataset structure

data_source_type string (Required)

Data source type. Available values:

oss_mount (Mount OSS file)
file_id (File uploaded via File Management API)

mount_storage object (Conditionally required)

Required when data source type is oss_mount. OSS mount information.

Properties

region string (Required)

The region of the OSS Bucket to mount. Supports Beijing (cn-beijing) and Singapore (ap-southeast-1).

bucket string (Required)

The name of the OSS Bucket to mount.

file_path string (Required)

The OSS file path (object key) to mount. For datasets containing multiple files, use the path to data.jsonl. Unlike the file_id method, you need to upload the uncompressed dataset folder to OSS. Zip files are not supported.

file_id string (Conditionally required)

Required when data source type is file_id. File ID, generated by the Upload File API.

validation_datasets Array of Dataset (Optional)

Validation dataset file list. Same structure as training_datasets.

Use either this or validation_file_ids. If neither is provided, the system will automatically split from the training set.

job_name string (Optional)

Tuning job name.

model_name string (Optional)

Model name after tuning is complete.

Image-to-Video - First Frame (Wan2.7)

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.7-i2v",
    "training_file_ids": [
        "<Replace with training dataset file ID>"
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "task_type": "i2v",
        "n_epochs": 50,
        "batch_size": 1,
        "learning_rate": 2e-5,
        "split": 0.9,
        "max_split_val_dataset_sample": 5,
        "eval_epochs": 20,
        "max_pixels": 102400,
        "save_total_limit": 10,
        "lora_rank": 32,
        "lora_alpha": 32
    }
}'

Image-to-Video - First & Last Frame (Wan2.7)

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.7-i2v",
    "training_file_ids": [
        "<Replace with training dataset file ID>"
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "task_type": "kf2v",
        "n_epochs": 50,
        "batch_size": 1,
        "learning_rate": 2e-5,
        "split": 0.9,
        "max_split_val_dataset_sample": 5,
        "eval_epochs": 20,
        "max_pixels": 102400,
        "save_total_limit": 10,
        "lora_rank": 32,
        "lora_alpha": 32
    }
}'

Image-to-Video - First & Last Frame (Wan2.2)

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.2-kf2v-flash",
    "training_file_ids": [
        "<Replace with training dataset file ID>"
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "n_epochs": 50,
        "batch_size": 4,
        "learning_rate": 2e-5,
        "split": 0.9,
        "max_split_val_dataset_sample": 5,
        "eval_epochs": 20,
        "max_pixels": 262144,
        "save_total_limit": 10,
        "lora_rank": 32,
        "lora_alpha": 32
    }
}'

Using OSS-mounted Dataset

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.7-i2v",
    "training_datasets": [
        {
            "data_source_type": "oss_mount",
            "mount_storage": {
                "region": "ap-southeast-1",
                "bucket": "example_bucket",
                "file_path": "dataset/data.jsonl"
            }
        }
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "n_epochs": 50,
        "batch_size": 1,
        "learning_rate": 2e-5,
        "split": 0.9,
        "max_split_val_dataset_sample": 5,
        "eval_epochs": 20,
        "max_pixels": 102400,
        "save_total_limit": 10,
        "lora_rank": 32,
        "lora_alpha": 32
    }
}'

Response Parameters

request_id string

Unique identifier for the request.

output object

Job details.

Properties

job_id string

Unique identifier for the fine-tuning job, used to query job details, logs, cancel, or delete the job. Generation rule: ft-{yyyyMMddHHmm}-{4 char uuid}.

job_name string

Fine-tuning job name.

status string

Status of the fine-tuning job:

PENDING: Training pending.
QUEUING: Training is queuing (only one fine-tuning job can run at a time).
RUNNING: Training in progress.
SUCCEEDED: Training succeeded.
FAILED: Training failed.
CANCELED: Training canceled.
CANCELING: Training is being canceled.

finetuned_output string

The new model ID produced after fine-tuning, needed for deployment and invocation. Returned when job status is SUCCEEDED.

model string

The base model used.

base_model string

The base model used.

training_file_ids array

Legacy field for backward compatibility, always returns an empty array for new jobs. Please use training_datasets.

training_datasets Array of Dataset

Training dataset list.

validation_file_ids array

Legacy field for backward compatibility, always returns an empty array for new jobs. Please use validation_datasets.

validation_datasets Array of Dataset

Validation dataset list. Empty array if no validation set is specified.

hyper_parameters object

Actual hyperparameters used.

training_type string

The training method for model fine-tuning.

create_time string

Job creation time.

end_time string

Job end time. Returned when job status is SUCCEEDED, FAILED, or CANCELED.

usage integer

Token consumption of the fine-tuning job. Returned when job status is SUCCEEDED or CANCELED.

workspace_id string

The workspace ID associated with the Alibaba Cloud Model Studio API Key. See Get the Workspace ID.

user_identity string

User identity, Alibaba Cloud account ID.

creator string

Creator's Alibaba Cloud account ID.

modifier string

Modifier's Alibaba Cloud account ID.

group string

Fine-tuning job group.

max_output_cnt integer

Maximum number of checkpoints saved during training. Equivalent to the save_total_limit hyperparameter value.

code string

Error code. Returned when the call fails. Refer to the error code table below.

message string

Detailed error description. Returned when the call fails.

Success Response Example

Key fields: output.job_id (Job ID), output.finetuned_output (New model name produced after fine-tuning).

{
    "request_id": "0eb05b0c-02ba-414a-9d0c-xxxxxxxxx",
    "output": {
        "job_id": "ft-202511111122-xxxx",
        "job_name": "ft-202511111122-xxxx",
        "status": "PENDING",
        "finetuned_output": "wan2.5-i2v-preview-ft-202511111122-xxxx",
        "model": "wan2.5-i2v-preview",
        "base_model": "wan2.5-i2v-preview",
        "training_file_ids": [],
        "training_datasets": [
            {
                "data_source_type": "file_id",
                "file_id": "xxxxxxxxxxxx"
            }
        ],
        "validation_file_ids": [],
        "validation_datasets": [],
        "hyper_parameters": {
            "n_epochs": 50,
            "batch_size": 2,
            "learning_rate": 2.0E-5,
            "split": 0.9,
            "eval_epochs": 20
        },
        "training_type": "efficient_sft",
        "create_time": "2025-11-11 11:22:22"
    }
}

Error Response Example

{
    "code": "InvalidParameter",
    "request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
    "message": "The model wan2.7-i2v does not support training_type: full_sft"
}

Error Codes

If the call fails and returns an error message, refer to the table below for troubleshooting.

HTTP Status Code	Error Codes	Solution
400	InvalidParameter	Parameter error: missing parameters or parameter format issues. Correct your parameters based on the error message.
400	UnsupportedOperation	The resource cannot be operated on when it is in a specific state. Wait until the resource reaches an operable state before performing the operation.
404	NotFound	The resource to query/operate does not exist. Check if the resource ID is incorrect.
409	Conflict	A deployment instance with the same name already exists. Specify a suffix to differentiate.
429	Throttling	Resource creation triggered platform limits. Delete models that are no longer in use.
500	InternalError	Internal error. Record the request_id and contact Alibaba Cloud engineers via a ticket for troubleshooting.

Next Step

Tuning is an asynchronous operation. After calling this API, you can use the Query and Manage Tuning Jobs API to check the tuning job status.