Create a tuning job-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Create a model fine-tuning job.

Create a fine-tuning job

For Windows CMD, replace ${DASHSCOPE_API_KEY} with %DASHSCOPE_API_KEY%. In PowerShell, use $env:DASHSCOPE_API_KEY.

Text generation

curl --location --request POST "https://dashscope.aliyuncs.com/api/v1/fine-tunes" \
      --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
      --header 'Content-Type: application/json' \
      --data '{
          "model":"qwen3-14b",
          "training_file_ids":[
              "86a9fe7f-dd77-43b0-9834-2170e12339ec",
              "03ead352-6190-4328-8016-61821c23d4fc"
          ],
          "hyper_parameters":{
              "n_epochs":3,
              "batch_size":32,
              "max_length":8192,
              "learning_rate":"1.6e-5",
              "lr_scheduler_type":"linear",
              "split":0.9
          },
          "training_type":"sft",
          "finetuned_output_suffix":"suffix"
      }'

Video generation

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

Image generation

curl --location 'https://dashscope.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.7-image-pro",
    "training_file_ids": ["<your-training-dataset-file-id>"],
    "validation_file_ids": ["<your-validation-dataset-file-id>"],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "learning_rate": 3e-5,
        "max_steps": 800,
        "eval_steps": 200,
        "max_token_length": "1k",
        "gradient_clip": 0.5,
        "weight_decay": 0.02,
        "max_pixels": "1k",
        "val_img_size": "1k",
        "generation_type": "t2i",
        "lora_rank": 32,
        "save_total_limit": 10
    }
}'

Input parameters

Parameter	Required	Type	Location	Description
training_file_ids	Yes	Array	Body	A list of file IDs for the training set. File IDs are generated by the File Management API.
validation_file_ids	No	Array	Body	A list of file IDs for the validation set. File IDs are generated by the File Management API.
model	Yes	String	Body	The ID of the model to fine-tune. This can be a base model ID or the ID of a model from a previous tuning job. Video/image generation models support the following `model` values: Image-to-Video - Based on First Frame: `wan2.5-i2v-preview`, `wan2.2-i2v-flash` Image-to-Video - Based on First and Last Frame: `wan2.2-kf2v-flash` Image generation (text-to-image/image-to-image): `wan2.7-image-pro`, `wan2.7-image`
hyper_parameters	No	Map	Body	An object that contains the hyperparameters for the tuning job. The supported parameters and their default values vary by model. To view the default values, select the model and tuning method in the console. For text generation, visual understanding, and similar models: Use parameters such as `n_epochs` (number of epochs), `batch_size` (batch size), and `max_length` (sequence length). The `n_epochs`, `batch_size`, and `max_length` parameters affect tuning costs and are required. For details about each parameter, see hyper_parameters Description. CosyVoice speech synthesis model (`cosyvoice-v3-flash` only): All eight LM/FM hyperparameters are required. For details about each parameter, see "CosyVoice speech synthesis model hyper_parameters" below.
training_type	No	String	Body	The tuning method. Valid values are `cpt`, `sft`, `efficient_sft`, `dpo_full`, or `dpo_lora`. Video/image generation models only support `efficient_sft` (LoRA efficient fine-tuning).
job_name	No	String	Body	A name for the tuning job.
model_name	No	String	Body	The name of the resulting fine-tuned model.

Text generation model

`hyper_parameters`: Supported settings

Supported parameters and their default values vary by model. Go to the Console, select the same model and training method to view the actual default values.

Parameter

Recommended setting

Type

Description

n_epochs

(Number of epochs) [Required]

Data size < 10,000: 3~5

Data size > 10,000: 1~2

Integer

The number of times the model iterates through the training data. Adjust based on your experience with model fine-tuning.

More epochs lead to longer training times and higher costs.

learning_rate

(Learning rate)

Use the recommended default value.

Float

Controls the intensity of model weight adjustments.

A high learning rate causes drastic changes in model parameters, which may lead to poor or worse performance.
A low learning rate results in minimal changes to the model's performance.

freeze_vit

(Freeze visual backbone)

Adjust as needed

Boolean

Freezes the parameters of the visual backbone so its weights are not updated during training. This applies only to Qwen-VL models.

Warning

Billing by token usage is available only when freeze_vit is set to "true".

batch_size

(Batch size) [Required]

Use the recommended default value.

Integer

The number of data entries fed into the model for training at one time. A small value can significantly extend training time. Default values vary by model; check the console.

eval_steps

(Evaluation steps)

Adjust as needed

Integer

The step interval for model validation during training, used for periodic evaluation of training accuracy and loss.

This parameter affects the display frequency of Validation Loss and Validation Token Accuracy during model fine-tuning.

logging_steps

(Logging steps)

Adjust as needed

Integer

The step interval for logging fine-tuning progress.

lr_scheduler_type

(Learning rate scheduler)

Recommended: linear or Inverse_sqrt

String

The strategy for dynamically adjusting the learning rate during training.

For details on each strategy, see Fine-tune a model in the console.

max_length

(Sequence length) [Required]

8192

Integer

The maximum token length supported for a single training data entry. If a data entry exceeds this value, it will be discarded and not used for training.

For the relationship between characters and tokens, see How to convert between tokens and characters.

max_split_val_dataset_sample

(Max validation set samples)

Use the recommended default value.

Integer

If "validation_file_ids" is not set, the automatically split validation set will have a maximum of 1,000 samples.

This parameter is ignored if "validation_file_ids" is set.

split

(Training set ratio)

Use the recommended default value.

Float

If "validation_file_ids" is not set, 80% of the training file is automatically used as the training set and 20% as the validation set.

This parameter is ignored if "validation_file_ids" is set.

warmup_ratio

(Warm-up ratio)

Use the recommended default value.

Float

The proportion of the total training process dedicated to learning rate warm-up, where the learning rate linearly increases from a small value to the set value.

This parameter helps stabilize training by limiting parameter changes in the initial phase.

A high ratio has the same effect as a low learning rate, leading to minimal changes. A low ratio has the same effect as a high learning rate, potentially degrading performance.

A ratio that is too small has the same effect as a learning rate that is too high, which can cause the performance of the tuned model to not improve or even to degrade.

This parameter has no effect on the "Constant" learning rate scheduler.

weight_decay

(Weight decay)

Use the recommended default value.

Float

The strength of L2 regularization, which helps maintain the model's generalizability. An overly large value can diminish the effect of fine-tuning.

Efficient fine-tuning (efficient_sft or dpo_lora) parameters

Note

When you efficiently fine-tune a model for a second time, the lora_rank, lora_alpha, and lora_dropout parameters must remain consistent.

lora_rank

(LoRA rank)

Integer

The rank of the low-rank matrices in LoRA training. A higher rank improves fine-tuning effectiveness but slightly slows down training.

lora_alpha

(LoRA alpha)

Use the recommended default value.

Integer

The scaling factor that controls the combination of original model weights and the LoRA low-rank correction term.

A larger alpha gives more weight to the LoRA correction, making the model rely more on task-specific information.

A smaller alpha makes the model retain more knowledge from the original pre-trained model.

lora_dropout

(LoRA dropout)

Use the recommended default value.

Float

The dropout rate for the values in the low-rank matrices during LoRA training.

Using the recommended value enhances the model's generalization capabilities.

An overly large value can diminish the fine-tuning effect.

Data augmentation (supports efficient_sft and sft) parameters

data_augmentation

(Enable mixed training)

Mix based on the model's use case.

Boolean

When enabled, your training data is mixed with general-purpose datasets (multi-domain/industry/scenario):

- Effect: Improves training results and prevents catastrophic forgetting.

- Billing: Mixed data is included in the total training tokens and billed at the standard rate.

augmentation_types

(Preset data types)

Mix based on the model's use case.

Example: "augmentation_types": "dialogue_CN,general_purpose_CN,NLP"

Must be used with augmentation_ratio.

String

Dataset code	Dataset name	Supported models
`dialogue_cn`	Chinese-Dialogue	Qwen2 series
`math_cn`	Chinese-Math
`general_coding_cn`	Chinese-Code
`general_purpose_cn`	Chinese-General
`nlp`	NLP-Understanding
`dialogue_en`	English-Dialogue
`math_en`	English-Math
`general_coding_en`	English-Code
`general_purpose_en`	English-General
`mix_v2`	General-V2	Qwen3 series
`vl_mix`	General	Qwen3 VL series

augmentation_ratio

(Mixing ratio)

Mix based on the model's use case.

String

Format: Must correspond to augmentation_types.
Example: "0.1,0.05,0.15" (The values correspond to the three datasets listed in augmentation_types, respectively.)
Description: Randomly sample and mix 10%/5%/15% of the training data.
Range: 0.0 ~ 2.0

Model Parameter Snapshot Publishing (for efficient_sft or sft only) Parameters

save_strategy

(Snapshot save strategy)

You can set this to epoch or steps.

When set to steps, you can adjust the save interval by setting the save_steps parameter.

String

Sets the save interval and maximum number of model parameter snapshots (checkpoints) to save during fine-tuning.

save_steps

(Save steps)

If you need to manually modify the value, you should set it to an integer multiple of the eval_steps parameter.

Integer

Sets the step interval for saving model parameter snapshots (checkpoints).

save_total_limit

(Snapshot save limit)

Integer

Limits the maximum number of model parameter snapshots (checkpoints) that can be saved for publishing.

CosyVoice

These parameters apply only to the cosyvoice-v3-flash model. They are distinct from the n_epochs, batch_size, and max_length parameters for text generation models.

Parameter	Required	Recommended	Value	Description
lm_max_epoch	Yes	60	[1, 2147483647]	Number of epochs for LM tuning.
lm_step	Yes	5	[1, 2147483647]	Interval, in epochs, for saving LM checkpoints.
lm_num	Yes	3	[1, 2147483647]	Maximum number of LM checkpoints to keep.
lm_batch_size	Yes	1000	[1, 2147483647]	Batch size for LM tuning.
fm_max_epoch	Yes	100	[1, 2147483647]	Number of epochs for FM tuning.
fm_step	Yes	10	[1, 2147483647]	Interval, in epochs, for saving FM checkpoints.
fm_num	Yes	3	[1, 2147483647]	Maximum number of FM checkpoints to keep.
fm_batch_size	Yes	2000	[1, 2147483647]	Batch size for FM tuning.

Note

CosyVoice tuning currently supports only efficient_sft for the training_type parameter. For a complete request example and an end-to-end workflow, refer to the CosyVoice model tuning user guide.

Hyperparameters for video generation models

These hyperparameters apply only to video generation models (Wan series). If model performance is poor or training fails to converge, consider adjusting n_epochs or learning_rate. A minimum of 800 total training steps is recommended.

Parameter	Type	Required	Description	Recommended value
batch_size	int	Yes	Batch size. The number of data samples processed in a single training iteration. wan2.5-i2v-preview: Recommended `2`. wan2.2-i2v-flash: Recommended `4`. wan2.2-kf2v-flash: Recommended `4`.	Varies by model
n_epochs	int	Yes	Number of training epochs. The total number of steps is calculated as: steps = n_epochs × ⌈dataset size / batch_size⌉. A minimum of 800 total steps is recommended. Example: If the dataset has 5 samples and `batch_size` = `2`, the steps per epoch = ⌈5/2⌉ = 3. The minimum `n_epochs` would be 800/3 ≈ 267.	400
learning_rate	float	Yes	Learning rate. Controls the magnitude of model weight updates during training. A value that is too high can degrade model performance, while a value that is too low may result in insignificant changes.	2e-5
eval_epochs	int	Yes	Validation interval. The interval, in epochs, at which to perform validation and save a checkpoint. The value must be ≥ `n_epochs/10`.	50
max_pixels	int	Yes	Maximum resolution for training videos (total pixels = width × height). The system only resizes videos that exceed this value. wan2.5-i2v-preview: Recommended `36864`. Range: `16384`–`36864`. wan2.2-i2v-flash: Recommended `262144`. Range: `65536`–`262144`. wan2.2-kf2v-flash: Recommended `262144`. Range: `65536`–`262144`.	Varies by model
split	float	No	Training set split ratio. The proportion of the dataset used for training, with a valid range of (0, 1). This parameter is ignored if `validation_file_ids` is specified.	0.9
max_split_val_dataset_sample	int	No	Maximum samples for auto-split validation set. The size of the validation set is the smaller of two values: the result of total_samples × (1 − split) or the value of this parameter.	5
save_total_limit	int	No	Checkpoint save limit. The maximum number of recent checkpoints to keep. The system deletes older checkpoints once this limit is exceeded.	10
lora_rank	int	No	LoRA rank. The rank (dimension) of the LoRA low-rank matrices. Must be a power of 2 (2ⁿ), such as 16, 32, or 64.	32
lora_alpha	int	No	LoRA alpha. The scaling factor for the LoRA weights. Must be a power of 2 (2ⁿ), such as 16, 32, or 64.	32

Hyperparameters for image generation models

Image generation models use max_steps and eval_steps to control the total training steps and the validation interval, unlike video models which use n_epochs and eval_epochs. If the model performs poorly or fails to converge, consider adjusting max_steps or learning_rate.

Parameter	Type	Required	Description	Recommended value
max_steps	int	Yes	Total training steps. A core parameter that determines the total number of training iterations. We recommend at least 500 steps to ensure model convergence, and a higher value for larger datasets.	800
eval_steps	int	Yes	Validation interval. The value must be ≥ 0. Specifies the frequency (in steps) at which to evaluate the model during training. A checkpoint is also saved at each interval.	200
learning_rate	float	Yes	learning rate. Controls the magnitude of model weight updates. A value that is too high can degrade model performance, while a value that is too low may result in insignificant changes. We recommend using the default value.	3e-5
generation_type	string	Yes	generation mode. Use `"t2i"` for text-to-image or `"i2i"` for image-to-image. This setting determines the training data format and inference method.	t2i
max_pixels	string	Yes	Maximum resolution for training images. For example, "1k" or "2k" (1K = 1024×1024, 2K = 2048×2048). Sets an upper limit on the total number of pixels (width × height) for images in the training set. The system only scales down images that exceed this value; images below the limit remain unchanged. We recommend keeping the three resolution-related parameters (`max_pixels`, `max_token_length`, and `val_img_size`) consistent.	text-to-image: "2k" image-to-image: "1k"
val_img_size	string	Yes	Validation image generation resolution. For example, "1k" or "2k" (1K = 1024×1024, 2K = 2048×2048). The target resolution for images generated during validation evaluation.	text-to-image: "2k" image-to-image: "1k"
max_token_length	string	Yes	Maximum token length per step. For example, "1k" or "2k". This parameter, along with `max_steps`, controls the training process: `max_steps` determines the number of iterations, while `max_token_length` determines the amount of data processed in each step.	text-to-image: "2k" image-to-image: "1k"
gradient_clip	float	Yes	gradient clipping. The threshold for global gradient norm clipping across all trainable parameters, used to prevent exploding gradients. Set to -1 to disable clipping.	0.5
weight_decay	float	Yes	weight decay. The decoupled weight decay coefficient for the AdamW optimizer. It applies to all trainable parameters and is used for regularization to prevent overfitting.	0.02
lora_rank	int	Yes	LoRA rank. The rank (dimension) of the LoRA low-rank matrices. This value determines the number of trainable parameters for fine-tuning. A larger value increases the model's fitting capability but slows down training. The value must be a power of 2 (e.g., 16, 32, 64).	32
save_total_limit	int	No	Checkpoint save limit. The maximum number of model checkpoints to save. The system keeps only the N most recent checkpoints, where N is this value.	10
split	float	No	Training set split ratio. The value range is (0, 1). This parameter takes effect only when `validation_file_ids` is not specified. This parameter is used to automatically split a portion of the training set to be used as a validation set. For example, a value of 0.9 means that 90% of the data is used as the training set and 10% is used as the validation set.	0.9

Example response

Text generation model

{
          "request_id": "9654e55a-d74b-4113-aee1-fa19c9384fcc",
          "output": {
              "job_id": "ft-202410291653-1c7f",
              "job_name": "ft-202410291653-1c7f",
              "status": "PENDING",
              "model": "qwen3-14b",
              "base_model": "qwen3-14b",
              "training_file_ids": [
                  "976bd01a-f30b-4414-86fd-50c54486e3ef"
              ],
              "validation_file_ids": [

              ],
              "hyper_parameters": {
                  "n_epochs": 3,
                  "batch_size": 32,
                  "max_length": 8192,
                  "learning_rate": "1.6e-5",
                  "lr_scheduler_type": "linear",
                  "split": 0.9
              },
              "training_type": "sft",
              "create_time": "2024-10-29 16:53:53",
              "workspace_id":"llm-v71tlv***",
              "user_identity": "1396993924585947",
              "modifier": "1396993924585947",
"creator": "1396993924585947",
              "group": "llm"
          }
      }

Video generation model

Focus on output.job_id (job ID) and output.finetuned_output (the name of the fine-tuned model, used for deployment).

{
    "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": [
            "xxxxxxxxxxxx"
        ],
        "validation_file_ids": [],
        "hyper_parameters": {
            "n_epochs": 400,
            "batch_size": 2,
            "learning_rate": 2.0E-5,
            "split": 0.9,
            "eval_epochs": 50
        },
        "training_type": "efficient_sft",
        "create_time": "2025-11-11 11:22:22"
    }
}

Image generation model

Focus on output.job_id (job ID) and output.finetuned_output (the name of the fine-tuned model, used for deployment).

{
    "request_id": "0eb05b0c-02ba-414a-9d0c-xxxxxxxxx",
    "output": {
        "job_id": "ft-202606030110-xxxx",
        "job_name": "ft-202606030110-xxxx",
        "status": "PENDING",
        "finetuned_output": "wan2.7-image-pro-ft-202606030110-xxxx",
        "model": "wan2.7-image-pro",
        "base_model": "wan2.7-image-pro",
        "training_file_ids": [
            "xxxxxxxxxxxx"
        ],
        "validation_file_ids": [],
        "hyper_parameters": {
            "max_steps": 800,
            "learning_rate": 3.0E-5,
            "eval_steps": 200,
            "max_token_length": "1k",
            "max_pixels": "1k",
            "val_img_size": "1k",
            "generation_type": "t2i",
            "lora_rank": 32
        },
        "training_type": "efficient_sft",
        "create_time": "2026-06-03 01:10:47"
    }
}

Response parameters

Parameter	Type	Description
request_id	String	The ID of the request.
output	Object	Details of the fine-tuning job.
output.job_id	String	The ID of the fine-tuning job. You can use this ID with other APIs, such as querying fine-tuning job details, querying fine-tuning job logs, canceling a fine-tuning job, and deleting a fine-tuning job. Format: `ft-{yyyyMMddHHmm}-{4-character ID}`.
output.job_name	String	Same as `output.job_id`.
output.status	String	The job status.
output.model	String	The ID of the model that was fine-tuned.
output.base_model	String	The ID of the base model used for fine-tuning. Example: For the fine-tuning job `ft-202410291653-1c7f`, the base model is `qwen3-14b`.
output.training_file_ids	Array	An array of fine-tuning file IDs.
output.validation_file_ids	Array	An array of validation file IDs.
output.hyper_parameters	Object	The hyperparameters explicitly set for the job.
output.training_type	String	The fine-tuning method.
output.create_time	String	The time the fine-tuning job was created.
output.workspace_id	String	The ID of the workspace that contains the fine-tuning job.
output.user_identity	String	The UID of the owning main account.
output.modifier	String	The UID of the account that last modified the job. For example, if a sub-account cancels the job, this field returns the UID of that sub-account.
output.creator	String	The UID of the user who created the job.
output.group	String	The fine-tuning job category.

Job status	Description
PENDING	The fine-tuning job is waiting to start.
QUEUING	The fine-tuning job is in the queue. (Only one fine-tuning job can run at a time.)
RUNNING	The fine-tuning job is running.
CANCELING	The fine-tuning job is being canceled.
SUCCEEDED	The fine-tuning job has succeeded.
FAILED	The fine-tuning job has failed.
CANCELED	The fine-tuning job has been canceled.

Request error codes

Returned when a request fails.

Parameter	Type	Description	Example
code	String	The error code.	NotFound
request_id	String	The system-generated unique ID for this request.	6332fb02-3111-43f0-bf79-f9e8c5ffa7f9
message	String	The error message.	Not Found!

Example response

{
        "code": "NotFound",
        "request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
        "message": "Not Found!"
      }

Error codes

HTTP status code	Error code	Example	Description	Solution
400	InvalidParameter	Missing training files	A parameter is invalid, either because a required parameter is missing or a value has an incorrect format.	Check the error message and correct the parameters in your request.
400	UnsupportedOperation	The fine-tune job cannot be deleted because it has already succeeded, failed, or been canceled.	The resource is in a state that prevents this operation.	Retry the operation after the resource enters an operational state.
404	NotFound	Not found!	The requested resource does not exist.	Verify that the resource ID is correct.
409	Conflict	Model instance xxxxx already exists, please specify a suffix	A deployment instance with the specified name already exists.	Specify a unique suffix for the deployment.
429	Throttling	Too many fine-tune jobs are running. Please retry later. Each user is allowed a maximum of 20 fine-tune jobs that are running or have succeeded.	The request was rejected because a platform limit was reached.	Delete unused models. If you need to increase the concurrency for fine-tune jobs or retain more successful models, contact your business manager.
500	InternalError	Internal server error!	An internal error occurred.	Record the request_id and submit a ticket to Alibaba Cloud support for troubleshooting.

Create a fine-tuning job

Text generation

Video generation

Image generation

Input parameters

Text generation model

hyper_parameters: Supported settings

CosyVoice

Hyperparameters for video generation models

Hyperparameters for image generation models

Example response

Text generation model

Video generation model

Image generation model

Response parameters

Request error codes

`hyper_parameters`: Supported settings