Create a tuning job - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

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-intl.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-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 the file ID of your training dataset>"
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "n_epochs": 400,
        "batch_size": 1,
        "learning_rate": 2e-5,
        "split": 0.9,
        "max_split_val_dataset_sample": 5,
        "eval_epochs": 50,
        "max_pixels": 102400,
        "save_total_limit": 10,
        "lora_rank": 32,
        "lora_alpha": 32
    }
}'

Image generation

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-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 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.6-i2v`, `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 `sft` or `efficient_sft`. 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

Parameter	Default	Recommended settings	Type	Description
`n_epochs`	1	Adjust based on fine-tuning results.	Integer	Number of times the model iterates through the training data. Higher values increase training duration and cost.
`learning_rate`	`sft`: 1e-5 level `efficient_sft`: 1e-4 level The specific value varies depending on the selected model.	Use the default value.	Float	Controls the intensity of model weight updates. Too high: parameters change drastically, degrading performance. Too low: performance may not change significantly.
`freeze_vit`	true	Adjust as needed.	Boolean	Freezes the visual backbone parameters so that its weights remain unchanged during training. Applies only to Qwen-VL models.
`batch_size`	The specific value varies depending on the selected model. The larger the model, the smaller the default batch size.	Use the default value.	Integer	Number of data entries per training iteration. Smaller values prolong training time.
`eval_steps`	50	Adjust as needed.	Integer	Interval (in steps) for evaluating training accuracy and loss during training. Controls display frequency of Validation Loss and Token Accuracy.
`logging_steps`	5	Adjust as needed.	Integer	Interval (in steps) for printing fine-tuning logs.
`lr_scheduler_type`	`cosine`	Recommended: `linear` or `Inverse_sqrt`	String	Strategy for dynamically adjusting the learning rate during training. Valid values:
`max_length`	2048	8192	Integer	Maximum token length per training entry. Entries exceeding this limit are discarded.
`max_split_val_dataset_sample`	1000	Use the default value.	Integer	If `"validation_file_ids"` is not set, Alibaba Cloud Model Studio automatically splits a validation set of up to 1,000 entries. If you set `"validation_file_ids"`, this parameter is ignored.
`split`	0.8	Use the default value.	Float	If you do not set `"validation_file_ids"`, Model Studio automatically uses 80% of the training file as the training set and 20% as the validation set. If you set `"validation_file_ids"`, this parameter has no effect.
`warmup_ratio`	0.05	Use the default value.	Float	Proportion of total training steps dedicated to learning rate warmup. During warmup, the learning rate linearly increases from a small initial value to the configured rate. Limits the extent of parameter changes during early training, improving stability. Too high: equivalent to a low learning rate; performance may not change. Too low: equivalent to a high learning rate; may degrade performance. Does not apply to the "Constant" learning rate scheduler type.
`weight_decay`	0.1	Use the default value.	Float	L2 regularization strength. Helps maintain model generalization. If too high, fine-tuning effects are insignificant.
Parameters for efficient SFT (supports `efficient_sft`) 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 be consistent.
`lora_rank`	8	64	Integer	Rank of the low-rank matrix in LoRA. Higher ranks improve fine-tuning results but slightly slow down training.
`lora_alpha`	32	Use the default value.	Integer	Scaling factor that controls the balance between original model weights and LoRA corrections. Larger values give more weight to LoRA corrections, making the model more task-specific. Smaller values preserve more pre-trained model knowledge.
`lora_dropout`	0.1	Use the default value.	Float	Dropout rate for LoRA low-rank matrix values. The recommended value enhances generalization. If too high, fine-tuning effects are insignificant.
Parameters for publishing checkpoints
`save_strategy`	`epoch`	Can be set to `epoch` or `steps`. When set to `steps`, set the `save_steps` parameter to adjust the saving interval.	String	Controls the interval and maximum number of checkpoints saved during fine-tuning.
`save_steps`	50	To modify it, set it to an integer multiple of the `eval_steps` parameter.	Integer	Number of training steps after which a checkpoint is saved.
`save_total_limit`	1	10	Integer	Maximum number of checkpoints to save for export.

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.6-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.	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.7-i2v: Recommended `102400`. Range: `36864`–`102400`. wan2.6-i2v: Recommended `36864`. Range: `16384`–`36864`. 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": 4,
            "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.
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

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