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

Create a model fine-tuning task.

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 and 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.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
    }
}'

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`
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 actual default values, select the corresponding 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

Settings for `hyper_parameters`

Supported parameters and their default values vary by model. For specific default values, refer to the console, as they differ based on the selected model and training method.

Parameter

Recommended settings

Type

Description

n_epochs

(Epochs) [Required]

Dataset size < 10,000: 3 to 5

Dataset size > 10,000: 1 to 2

Integer

An epoch represents one full iteration over the training set. Adjust this value based on your fine-tuning experience.

A higher number of epochs increases training time and cost.

learning_rate

(Learning rate)

Use the default value recommended by Model Studio.

Float

Controls the magnitude of weight updates during training.

A high learning rate can cause drastic parameter changes and degrade performance.
A low learning rate may result in minimal performance changes after fine-tuning.

freeze_vit

(Freeze visual backbone network)

Adjust as needed.

Boolean

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

Note

Billing based on token usage is available only when freeze_vit is set to true.

batch_size

(Batch size) [Required]

Use the default value recommended by Model Studio.

Integer

The number of training samples processed in a single iteration. A small batch size can significantly increase training time. Default values vary by model. Check the console for details.

eval_steps

(Evaluation steps)

Adjust as needed.

Integer

The step interval for evaluating the model on the validation set.

This parameter determines how frequently the Validation Loss and Validation Token Accuracy metrics are updated.

logging_steps

(Logging steps)

Adjust as needed.

Integer

The number of steps between log outputs during fine-tuning.

lr_scheduler_type

(Learning rate schedule)

Recommended: linear or inverse_sqrt

String

The strategy used to dynamically adjust the learning rate during training.

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

max_length

(Sequence length) [Required]

8192

Integer

The maximum sequence length, in tokens, for a single training sample. Samples that exceed this length are discarded and not used for training.

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

max_split_val_dataset_sample

(Maximum validation set samples)

Use the default value recommended by Model Studio.

Integer

If "validation_file_ids" is not set, Alibaba Cloud Model Studio automatically creates a validation set with a maximum of 1,000 samples.

This parameter has no effect if "validation_file_ids" is set.

split

(Training set ratio)

Use the default value recommended by Model Studio.

Float

If "validation_file_ids" is not set, Alibaba Cloud Model Studio automatically splits the training file, using 80% of the data for the training set and 20% for the validation set.

This parameter has no effect if "validation_file_ids" is set.

warmup_ratio

(Warmup ratio)

Use the default value recommended by Model Studio.

Float

The proportion of the total training process used for learning rate warmup. During warmup, the learning rate increases linearly from a small initial value to its configured value.

This helps limit parameter updates early in training and improves training stability.

A high ratio acts like a low learning rate and may result in minimal performance changes.

A low ratio acts like a high learning rate and can cause training instability or degrade performance.

This parameter does not apply to the "Constant" learning rate schedule.

weight_decay

(Weight decay)

Use the default value recommended by Model Studio.

Float

The strength of L2 regularization. L2 regularization helps maintain the model's generalization capabilities. A high value can reduce the effectiveness of model fine-tuning.

Efficient fine-tuning parameters (supports efficient_sft and dpo_lora)

Note

When re-applying efficient fine-tuning to a previously fine-tuned model, the lora_rank, lora_alpha, and lora_dropout parameters must remain the same.

lora_rank

(LoRA rank)

Integer

The rank of the low-rank matrices in LoRA training. A higher rank can improve fine-tuning performance but may slightly slow down training.

lora_alpha

(LoRA alpha)

Use the default value recommended by Model Studio.

Integer

A scaling factor that controls the combination of the base model weights and the LoRA low-rank update.

A larger value gives more weight to the LoRA update, making the model rely more on the information from the fine-tuning task.

A smaller value causes the model to retain more knowledge from the original pre-trained model.

lora_dropout

(LoRA dropout)

Use the default value recommended by Model Studio.

Float

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

The recommended value can enhance the model's generalization capabilities.

A high value can reduce the effectiveness of model fine-tuning.

Mixed training parameters (supports efficient_sft and sft)

data_augmentation

(Enable mixed training)

Mix based on the model's use case.

Boolean

When enabled, your training data is mixed with a general-purpose dataset provided by Model Studio, which covers multiple domains, industries, and scenarios.

- Effect: Improves training performance and prevents catastrophic forgetting.

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

augmentation_types

(Types of pre-built datasets)

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

(Augmentation ratio)

Mix based on the model's use case.

String

Required format: Must correspond one-to-one with augmentation_types.
Example: "0.1,0.05,0.15" (These values correspond to the three datasets listed in augmentation_types, respectively.)
Description: Randomly samples and mixes 10%/5%/15% of the training data.
Range: 0.0 ~ 2.0

Checkpoint publishing parameters (supports efficient_sft and sft)

save_strategy

(Checkpoint saving strategy)

It can be set to epoch or steps.

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

String

Sets the saving interval and the maximum number of checkpoints to save during the fine-tuning process.

save_steps

(Save steps)

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

Integer

The number of training steps between saving a checkpoint.

save_total_limit

(Checkpoint save limit)

Integer

The maximum number of checkpoints to save 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

Image generation model hyperparameters

Applies only to the wan2.7-image-pro model. The image generation model uses max_steps and eval_steps to control training steps and the evaluation interval, unlike video models, which use n_epochs/eval_epochs.

Parameter	Type	Required	Description	Recommended value
max_steps	int	Yes	Total training steps. A minimum of 500 steps is recommended for proper model convergence.	800
eval_steps	int	Yes	Evaluation interval. The number of steps between evaluations. A checkpoint is saved after each evaluation.	200
learning_rate	float	Yes	Learning rate. Controls the magnitude of model weight updates.	3e-5
generation_type	string	Yes	Generation mode. `"t2i"`: text-to-image; `"i2i"`: image-to-image.	t2i
max_pixels	string	Yes	Maximum training image resolution. For example, "1k" (1024×1024) or "2k" (2048×2048). This value should be consistent with `max_token_length` and `val_img_size`.	text-to-image: "2k" image-to-image: "1k"
val_img_size	string	Yes	Evaluation image resolution. The target resolution for images generated during evaluation.	text-to-image: "2k" image-to-image: "1k"
max_token_length	string	Yes	Maximum token length per training step. Works with `max_steps` to control the training process.	text-to-image: "2k" image-to-image: "1k"
gradient_clip	float	Yes	Gradient clipping. The threshold for global gradient norm clipping to prevent gradient explosion. A value of -1 disables clipping.	0.5
weight_decay	float	Yes	Weight decay. The decoupled weight decay coefficient for the AdamW optimizer, used for regularization.	0.02
lora_rank	int	Yes	LoRA low-rank matrix dimension. The value must be a power of 2 (e.g., 16, 32, or 64).	32
lora_alpha	int	Yes	LoRA weight scaling factor. The value must be a power of 2 (e.g., 16, 32, or 64).	32
save_total_limit	int	No	Checkpoint retention limit. The maximum number of recent checkpoints to keep. When this limit is exceeded, the oldest checkpoint is removed.	10
split	float	No	Training set split ratio. The value must be in the range (0, 1). This parameter applies only when `validation_file_ids` is not specified.	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 and image generation model

Focus on output.job_id (job ID) and output.finetuned_output (the name of the new model generated after fine-tuning, which is used for deployment).

Video generation model

{
    "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

{
    "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": "2k",
            "max_pixels": "2k",
            "val_img_size": "2k",
            "generation_type": "t2i",
            "lora_rank": 32,
            "lora_alpha": 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.jobs_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 job type for model fine-tuning.

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 and image generation

Input parameters

Text generation model

Settings for hyper_parameters

CosyVoice

Hyperparameters for video generation models

Image generation model hyperparameters

Example response

Text generation model

Video and image generation model

Video generation model

Image generation model

Response parameters

Request error codes

Settings for `hyper_parameters`