Image Generation - Create a Tuning Job - Alibaba Cloud Model Studio

Prerequisites

Supported regions: The features described in this document are only available in the Singapore 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

Singapore

POST https://dashscope-intl.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-Type string (Required)Fixed value: application/jsonAuthorization string (Required)API Key authentication. Format: Bearer sk-xxxx.

Request Body

model string (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

training_file_ids array[string] (Conditionally required)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_ids array[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_type string (Required)Fine-tuning type. Currently only supports efficient_sft (LoRA efficient fine-tuning).hyper_parameters object (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 parameters such as max_steps or learning_rate.

Hyperparameter properties

max_steps int (Required)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.

This parameter affects training billing. Please set it appropriately.

eval_steps int (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_rate float (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_type string (Required)Generation mode. Determines the training data format and inference method. Valid values:

t2i: Text-to-image mode.
i2i: Image-to-image mode.

max_pixels string (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_size string (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_length string (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 L_max :

generation_type	max_token_length	L_max
t2i (text-to-image)	1k	12,800
t2i (text-to-image)	2k	23,220
i2i (image-to-image)	1k	23,220
i2i (image-to-image)	2k	32,000

gradient_clip float (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_decay float (Required)Weight decay. Recommended value: 0.02. The AdamW decoupled weight decay coefficient, applied to all trainable parameters for regularization to prevent overfitting.lora_rank int (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 2ⁿ (e.g., 16, 32, 64).save_total_limit int (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.split float (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.

training_datasets Array 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_type string (Required)Data source type. Valid values:

oss_mount (Mount OSS files)
file_id (Files uploaded via the File Management API)

mount_storage object (Conditionally required)Required when data_source_type is oss_mount . OSS mount information.

Properties

region string (Required)The region of the OSS Bucket to mount. Supports Beijing (cn-beijing) and Singapore (ap-southeast-1).bucket string (Required)The name of the OSS Bucket to mount.file_path string (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_id string (Conditionally required)Required when data_source_type is file_id . File ID, generated by the Upload File API.

validation_datasets Array 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.job_name string (Optional)The name of the tuning job.model_name string (Optional)The name of the model after tuning is complete.

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": [
        "<Replace with the training dataset file ID>"
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "learning_rate": 3e-5,
        "max_steps": 800,
        "eval_steps": 200,
        "max_token_length": "2k",
        "gradient_clip": 0.5,
        "weight_decay": 0.02,
        "max_pixels": "2k",
        "val_img_size": "2k",
        "generation_type": "t2i",
        "lora_rank": 32,
        "save_total_limit": 10
    }
}'

Response parameters

request_id stringThe unique identifier of the request.output objectJob details.

Properties

job_id stringThe 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_name stringThe name of the fine-tuning job.status stringThe 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_output stringThe ID of the new model produced after fine-tuning, used for deployment and invocation. Returned when the job status is SUCCEEDED.model stringThe base model used.base_model stringThe base model used.training_file_ids arrayA legacy field for backward compatibility. New jobs always return an empty array. Please use training_datasets.training_datasets Array of DatasetThe list of training datasets.validation_file_ids arrayA legacy field for backward compatibility. New jobs always return an empty array. Please use validation_datasets.validation_datasets Array of DatasetThe list of validation datasets. Returns an empty array if no validation set is specified.hyper_parameters objectThe hyperparameters actually used.training_type stringThe training method for model fine-tuning.create_time stringThe job creation time.end_time stringThe job end time. Returned when the job status is SUCCEEDED, FAILED, or CANCELED.usage integerThe number of tokens consumed by the fine-tuning job. Returned when the job status is SUCCEEDED or CANCELED.workspace_id stringThe workspace ID associated with the Alibaba Cloud Model Studio API Key. See Get the Workspace ID.user_identity stringUser identity, Alibaba Cloud account ID.creator stringThe Alibaba Cloud account ID of the creator.modifier stringThe Alibaba Cloud account ID of the modifier.group stringThe fine-tuning job group.max_output_cnt integerThe maximum number of checkpoints saved during training. Equals the value of the save_total_limit hyperparameter.

code stringError code. Returned when the call fails. See the error code table below.message stringDetailed error description. Returned when the call fails.

Success response example
Error response example

Key fields: output.job_id (Job ID), output.finetuned_output (The name of the new model produced after fine-tuning).

{
    "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": [],
        "training_datasets": [
            {
                "data_source_type": "file_id",
                "file_id": "xxxxxxxxxxxx"
            }
        ],
        "validation_file_ids": [],
        "validation_datasets": [],
        "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
        },
        "training_type": "efficient_sft",
        "create_time": "2026-06-03 01:10:47"
    }
}

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.
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.

​Prerequisites

​Create a Fine-tuning Job

Request parameters

Headers

Request Body

Response parameters

​Error codes

​Next step

Prerequisites

Create a Fine-tuning Job

Error codes

Next step