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":[
              "<Replace with the file ID of your training dataset>",
              "<Replace with the file ID of your validation dataset>"
          ],
          "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.7-i2v",
    "training_file_ids": [
        "<Replace with the file ID of your training dataset>"
    ],
    "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
    }
}'

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>"],
    "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.7-i2v` (recommended), `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. To view specific default values, go to the console and select the model and training method.

Parameter

Recommended setting

Type

Description

n_epochs

(Number of epochs) [Required]

Data size < 10,000: 3–5

Data size > 10,000: 1–2

Integer

How many times the model iterates over the full training set.

More epochs increase training time and cost.

learning_rate

(Learning rate)

Use the recommended default value provided by Model Studio.

Float

Controls the step-size for weight updates during training.

Too high: training may diverge.
Too low: slow convergence with minimal improvement.

freeze_vit

(Freeze visual backbone)

Adjust as needed

Boolean

Freezes the visual backbone so its weights are not updated during training. Applies only to Qwen-VL models.

Warning

Token-based billing is available only when freeze_vit is set to “true”.

batch_size

(Batch size) [Required]

Use the recommended default value provided by Model Studio.

Integer

Number of training examples per iteration. Small values significantly increase training time. Defaults vary by model.

eval_steps

(Evaluation steps)

Adjust as needed

Integer

Step interval for evaluating training accuracy and loss.

Controls how often Validation Loss and Validation Token Accuracy are reported.

logging_steps

(Logging steps)

Adjust as needed

Integer

Step interval for logging training progress.

lr_scheduler_type

(Learning rate scheduler)

Recommended linear/Inverse_sqrt

String

Strategy for adjusting the learning rate during training.

Each strategy is described in Fine-tune a model in the console.

max_length

(Sequence length) [Required]

8192

Integer

Maximum sequence length (in tokens) per training example. Longer examples are discarded.

How to convert between tokens and characters.

max_split_val_dataset_sample

(Max validation set samples)

Use the recommended default value provided by Model Studio.

Integer

When "validation_file_ids" is not set, the validation set that is automatically split by Model Studio contains a maximum of 1,000 entries.

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

split

(Training set ratio)

Use the recommended default value provided by Model Studio.

Float

If "validation_file_ids" is not set, Model Studio splits the training file: 80% for training, 20% for validation.

When "validation_file_ids" is set, this parameter has no effect.

warmup_ratio

(Warm-up ratio)

Use the recommended default value provided by Model Studio.

Float

Fraction of training steps used for learning rate warm-up (linear ramp from near-zero to the target rate).

Stabilizes early training by limiting large weight updates.

Too high: resembles a low learning rate with minimal performance change.

Too low: resembles a high learning rate and may degrade performance.

This parameter has no effect if the learning rate scheduler is set to constant.

weight_decay

(Weight decay)

Use the recommended default value provided by Model Studio.

Float

L2 regularization strength. Helps preserve generalization, but excessively high values reduce fine-tuning effectiveness.

Parameters for efficient fine-tuning (supports efficient_sft and dpo_lora)

Note

When you perform a second round of efficient fine-tuning on a model that has already been efficiently fine-tuned, the lora_rank, lora_alpha, and lora_dropout parameters must remain consistent.

lora_rank

(LoRA rank)

Integer

Rank of the LoRA low-rank matrices. Higher ranks can improve results but slightly increase training time.

lora_alpha

(LoRA alpha)

Use the recommended default value provided by Model Studio.

Integer

Scaling factor for combining base model weights with the LoRA correction.

Larger alpha: more weight to task-specific LoRA updates.

Smaller alpha: more retention of base model knowledge.

lora_dropout

(LoRA dropout)

Use the recommended default value provided by Model Studio.

Float

Dropout rate for LoRA low-rank matrices. The default balances generalization; overly large values diminish fine-tuning effectiveness.

Parameters for mixed training (supports efficient_sft and sft)

data_augmentation

(Enable mixed training)

Mix based on the model's use case.

Boolean

Mixes your training data with general-purpose datasets to improve performance and prevent catastrophic forgetting. Mixed-in data counts toward total training tokens and is 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 in conjunction 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	Qwen 3 series
`vl_mix`	General	Qwen 3 VL series

augmentation_ratio

(Mixing ratio)

Mix based on the model's use case.

String

The format must be a one-to-one match with augmentation_types.
Example: "0.1,0.05,0.15" (The 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

Parameters for publishing model parameter snapshots (for efficient_sft and sft only)

save_strategy

(Snapshot save 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

Strategy for saving model parameter snapshots (checkpoints): epoch (after each epoch) or steps (at a specified step interval).

save_steps

(Save steps)

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

Integer

Interval, in training steps, between snapshot saves.

save_total_limit

(Snapshot save limit)

Integer

Maximum snapshots to retain. Older snapshots are auto-deleted when the limit is reached.

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.7-i2v: Recommended `1`. wan2.5-i2v-preview: Recommended `4`. 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. The recommended number of epochs adjusts automatically based on dataset size. Fewer samples require more epochs for sufficient learning, while larger datasets contain more samples per epoch and thus need fewer epochs. The default of 50 epochs is primarily suited for very small datasets (around 2 samples). For datasets of 50-60 videos, training for approximately 3,000-5,000 steps is generally recommended.	50
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`.	20
max_pixels	int	Yes	Maximum resolution for training videos (total pixels = width × height). The system only resizes videos that exceed this value. wan2.7-i2v: Recommended `102400`. Range: `36864`–`123904`. 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": 50,
            "batch_size": 4,
            "learning_rate": 2.0E-5,
            "split": 0.9,
            "eval_epochs": 20
        },
        "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