Create a fine-tuning job for image generation models. Datasets can be uploaded via the API or mounted from OSS.
Prerequisites
Supported regions: The features described in this document are only available in the China (Beijing) region. You must use an API Key from this region.
Account permissions: If you use an Alibaba Cloud sub-account (RAM user), you need to grant the sub-account model invocation, training, and deployment permissions.
Configure environment variables: You have successfully obtained an API Key and configured it as an environment variable.
Preparation: You have read Fine-tune image generation models to understand the models that support fine-tuning, fine-tuning steps, data formats, and billing instructions.
Create a Fine-tuning Job
China (Beijing)
POST https://dashscope.aliyuncs.com/api/v1/fine-tunes
For Windows CMD, replace $DASHSCOPE_API_KEY with %DASHSCOPE_API_KEY%. For PowerShell, replace it with $env:DASHSCOPE_API_KEY
Request parameters
Headers
Content-Typestring(Required)
Fixed value: application/json
Authorizationstring(Required)
API Key authentication. Format: Bearer sk-xxxx.
Request Body
modelstring(Required)
Specifies the base model for fine-tuning.
wan2.7-image-pro: Recommended for text-to-image/image-to-image fine-tuning.
wan2.7-image
qwen-image-2.0: A Qwen image generation model. It supports a different set of hyperparameters from Wan. See Hyperparameter properties (qwen-image-2.0, qwen-image-2.0-pro) below.
qwen-image-2.0-pro: A Qwen image generation model. Its hyperparameters are identical to qwen-image-2.0. See Hyperparameter properties (qwen-image-2.0, qwen-image-2.0-pro) below.
Array of training dataset file IDs. Multiple IDs can be passed. Mutually exclusive with training_datasets . If training_datasets is used, this parameter is not required. File IDs are obtained through the Upload File API.
validation_file_idsarray[string] (Optional)
Array of validation dataset file IDs. Multiple IDs can be passed. Mutually exclusive with validation_datasets . If validation_datasets is used, this parameter is not required. If neither is provided, the system will automatically split from the training set. File IDs are obtained through the Upload File API.
training_typestring(Required)
Fine-tuning type. Currently only supports efficient_sft (LoRA efficient fine-tuning).
hyper_parametersobject (Optional)
Hyperparameter configuration. For initial training, it is recommended to use the default hyperparameters. If the model performance is poor or training does not converge, try adjusting the training volume (max_steps for Wan, n_epochs for qwen-image-2.0 and qwen-image-2.0-pro) or learning_rate. Supported hyperparameters vary by base model. See the corresponding hyperparameter properties below.
Total training steps. The core parameter that controls training duration. Recommended value: 800.
max_steps determines the number of training iterations, while max_token_length determines the data volume processed per step.
It is recommended to use at least 500 steps to ensure the model converges sufficiently. You can increase the steps for larger datasets.
ImportantThis parameter affects training billing. Please set it appropriately.
eval_stepsint(Required)
Validation interval. Recommended value: 200. The value must be >= 0. Specifies how many steps between each validation evaluation during training, used for periodic assessment of model training progress. The model file at the current step is also saved.
learning_ratefloat(Required)
Learning rate. Recommended value: 3e-5. Controls the magnitude of model weight updates. Too high may degrade the model, while too low may result in insignificant changes.
generation_typestring(Required)
Generation mode. Determines the training data format and inference method. Valid values:
t2i: Text-to-image mode.
i2i: Image-to-image mode.
max_pixelsstring(Required)
Maximum resolution of training images. Sets the upper limit for the total pixel count (width x height) of images in the training set. The system only scales images that exceed this value; images within the limit remain unchanged. It is recommended to keep the three resolution parameters (max_pixels, max_token_length, val_img_size) consistent.
1k: i.e., 1024x1024.
2k: i.e., 2048x2048.
Recommended value: 2k for text-to-image, 1k for image-to-image.
val_img_sizestring(Required)
Validation image generation resolution. The target resolution for images generated during validation evaluation in the training process. Valid values are the same as max_pixels. Recommended value: 2k for text-to-image, 1k for image-to-image.
max_token_lengthstring(Required)
Maximum token length per training step, affecting per-step computation and billing. Together with max_steps, it controls the training process: max_steps determines the number of iterations, while max_token_length determines the data volume per step. Valid values:
1k: Recommended for image-to-image scenarios.
2k: Recommended for text-to-image scenarios.
The mapping between max_token_length and billing Lmax :
generation_type
max_token_length
Lmax
t2i (text-to-image)
1k
12,800
2k
23,220
i2i (image-to-image)
1k
23,220
2k
32,000
gradient_clipfloat(Required)
Gradient clipping. Recommended value: 0.5. The threshold for global gradient norm clipping on all trainable parameters to prevent gradient explosion. Set to -1 to disable clipping.
weight_decayfloat(Required)
Weight decay. Recommended value: 0.02. The AdamW decoupled weight decay coefficient, applied to all trainable parameters for regularization to prevent overfitting.
lora_rankint(Required)
The rank of LoRA low-rank matrices. Recommended value: 32. This value determines the number of fine-tuning parameters. A larger value provides stronger model fitting capability but slower training speed. The value must be a power of 2n (e.g., 16, 32, 64).
save_total_limitint (Optional)
Maximum number of checkpoints to save. Recommended value: 10. Limits the maximum number of saved models. The system will always keep only the last N checkpoints generated during training.
splitfloat (Optional)
Training set split ratio. Recommended value: 0.9. Value range: (0, 1). Only takes effect when neither validation_file_ids nor validation_datasets is specified. This parameter is used to automatically split a portion from the training set as the validation set. For example, 0.9 means 90% training set and 10% validation set.
qwen-image-2.0 and qwen-image-2.0-pro control the training process by the number of epochs (n_epochs). They do not support max_steps, eval_steps, or max_token_length. The two models share the same hyperparameters, except for the recommended learning rate: 5e-5 for qwen-image-2.0 and 1e-4 for qwen-image-2.0-pro.
n_epochsint(Required)
Number of training epochs. The number of complete passes over the training set. Recommended value: 10. Valid range: [1, 10000]. More epochs improve fitting, but too many can cause overfitting.
ImportantThis parameter affects training billing. Please set it appropriately.
eval_epochsint(Required)
Validation interval in epochs. Recommended value: 10. Valid range: [1, 1000]. Specifies how many epochs between each validation evaluation during training, used for periodic assessment of model training progress. The model file at the current epoch is also saved.
batch_sizeint (Optional)
Batch size. The number of samples used for each parameter update. Recommended value: 8. Valid range: [1, 2048]. This parameter does not affect billing or the total training tokens.
learning_ratefloat(Required)
Learning rate. Recommended value: 5e-5 for qwen-image-2.0, 1e-4 for qwen-image-2.0-pro. Controls the magnitude of model weight updates. Too high may degrade the model, while too low may result in insignificant changes.
generation_typestring(Required)
Generation mode. Determines the training data format and inference method. Valid values:
t2i: Text-to-image mode.
i2i: Image-to-image mode.
Recommended value: i2i.
max_pixelsstring(Required)
Maximum resolution of training images. A string tier that sets the upper limit for the total pixel count (width x height) of images in the training set. The system only scales images that exceed this value; images within the limit remain unchanged. Valid values:
1k: i.e., 1024x1024.
2k: i.e., 2048x2048.
Recommended value: 2k. Keep it consistent with val_img_size.
ImportantThis parameter affects training billing. Please set it appropriately.
val_img_sizestring(Required)
Validation image generation resolution. The target resolution for images generated during validation evaluation in the training process. Valid values are the same as max_pixels. Recommended value: 2k.
gradient_clipfloat(Required)
Gradient clipping. Recommended value: 0.5. Valid range: [0, 10.0]. The threshold for global gradient norm clipping across all trainable parameters, used to prevent exploding gradients.
weight_decayfloat(Required)
Weight decay. Recommended value: 0.02. Valid range: [0, 1.0]. The decoupled weight decay coefficient for AdamW. It applies to all trainable parameters and is used for regularization to prevent overfitting.
lora_rankint(Required)
The rank (dimension) of the LoRA low-rank matrices. Recommended value: 32. Valid range: [8, 128]. This value determines the number of trainable parameters. A larger value increases fitting capability but slows down training.
save_total_limitint (Optional)
Checkpoint save limit. Recommended value: 20. Valid range: [1, 40]. The maximum number of model checkpoints to save. The system keeps only the N most recent checkpoints.
splitfloat (Optional)
Training set split ratio. Recommended value: 0.9. Valid range: [0, 1]. Takes effect only when validation_file_ids or validation_datasets is not specified. Automatically splits a portion of the training set as the validation set. For example, 0.9 means 90% training set and 10% validation set.
training_datasetsArray of Dataset(Conditionally required)
Training dataset file list. Mutually exclusive with training_file_ids . If training_file_ids is used, this parameter is not required.
Dataset structure
data_source_typestring(Required)
Data source type. Valid values:
oss_mount (Mount OSS files)
file_id (Files uploaded via the File Management API)
mount_storageobject (Conditionally required)
Required when data_source_type is oss_mount . OSS mount information.
Properties
regionstring(Required)
The region of the OSS Bucket to mount. Supports Beijing (cn-beijing) and Singapore (ap-southeast-1).
bucketstring(Required)
The name of the OSS Bucket to mount.
file_pathstring(Required)
The OSS file path (object key) to mount. For datasets containing multiple files, use the file path of data.jsonl. Unlike the file_id approach, you need to upload the entire uncompressed dataset folder to OSS. Zip files are not supported.
file_idstring (Conditionally required)
Required when data_source_type is file_id . File ID, generated by the Upload File API.
validation_datasetsArray of Dataset (Optional)
Validation dataset file list. Structure is the same as training_datasets.
Mutually exclusive with validation_file_ids. If neither is provided, the system will automatically split from the training set.
The unique identifier of the fine-tuning job, used to query job details, logs, cancel, or delete the job. Generation rule: ft-{yyyyMMddHHmm}-{4-digit uuid}.
job_namestring
The name of the fine-tuning job.
statusstring
The status of the fine-tuning job:
PENDING: Training is pending.
QUEUING: Training is queuing (only one fine-tuning job can run at a time).
RUNNING: Training is in progress.
SUCCEEDED: Training succeeded.
FAILED: Training failed.
CANCELED: Training has been canceled.
CANCELING: Training is being canceled.
finetuned_outputstring
The ID of the new model produced after fine-tuning, used for deployment and invocation. Returned when the job status is SUCCEEDED.
modelstring
The base model used.
base_modelstring
The base model used.
training_file_idsarray
A legacy field for backward compatibility. New jobs always return an empty array. Please use training_datasets.
training_datasetsArray of Dataset
The list of training datasets.
validation_file_idsarray
A legacy field for backward compatibility. New jobs always return an empty array. Please use validation_datasets.
validation_datasetsArray of Dataset
The list of validation datasets. Returns an empty array if no validation set is specified.
hyper_parametersobject
The hyperparameters actually used.
training_typestring
The training method for model fine-tuning.
create_timestring
The job creation time.
end_timestring
The job end time. Returned when the job status is SUCCEEDED, FAILED, or CANCELED.
usageinteger
The number of tokens consumed by the fine-tuning job. Returned when the job status is SUCCEEDED or CANCELED.
workspace_idstring
The workspace ID associated with the Alibaba Cloud Model Studio API Key. See Get the Workspace ID.
user_identitystring
User identity, Alibaba Cloud account ID.
creatorstring
The Alibaba Cloud account ID of the creator.
modifierstring
The Alibaba Cloud account ID of the modifier.
groupstring
The fine-tuning job group.
max_output_cntinteger
The maximum number of checkpoints saved during training. Equals the value of the save_total_limit hyperparameter.
codestring
Error code. Returned when the call fails. See the error code table below.
messagestring
Detailed error description. Returned when the call fails.
Success response example
Key fields: output.job_id (Job ID), output.finetuned_output (The name of the new model produced after fine-tuning).
{
"code": "InvalidParameter",
"request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
"message": "The model wan2.7-image-pro does not support training_type: full_sft"
}
Error codes
If the call fails and returns an error message, refer to the following table for troubleshooting.
HTTP status code
Error code
Solution
400
InvalidParameter
Parameter error, missing parameter or parameter format issue. Correct your parameters based on the error message.
400
UnsupportedOperation
The resource cannot be operated on when it is in a specific state. Wait until the resource reaches an operable state before performing the operation.
404
NotFound
The resource to query/operate does not exist. Check if the resource ID is incorrect.
409
Conflict
A deployment instance with the same name already exists. Specify a suffix to differentiate.
429
Throttling
Resource creation has triggered a platform limit. Delete models that are no longer in use.If you need to increase the concurrency of tuning jobs or retain more successfully tuned models, please contact your business manager.
500
InternalError
Internal error. Record the request_id and contact Alibaba Cloud engineers via a ticket for troubleshooting.
Next step
Tuning is an asynchronous operation. After calling this API, you can use the Query and Manage Tuning Jobs API to check the job status.