Speech Synthesis (CosyVoice) - Create a Fine-Tuning Job

Prerequisites

Supported region: The features described in this document are only available in the China (Beijing) region. You must use an API Key from that region.
Account permissions: If using an Alibaba Cloud sub-account (RAM user), you need to grant model invocation, training, and deployment permissions to the sub-account.
Configure environment variables: You have successfully obtained an API Key and configured it as an environment variable.
Preparation: You have read CosyVoice model tuning to understand supported models, fine-tuning steps, data formats, and billing.

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 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)The base model for fine-tuning. Currently supported:

cosyvoice-v3-flash

training_type string (Required)Fine-tuning type. Currently only efficient_sft (efficient fine-tuning) is supported.hyper_parameters object (Required)Hyperparameter configuration. CosyVoice fine-tuning involves two sub-networks that are decoupled and can be adjusted independently:

LM (Language Model): An autoregressive language model that converts text to discrete speech tokens. Has a significant impact on prosody. Hyperparameters are prefixed with lm_*.
FM (Flow Matching): A flow matching model that converts speech tokens back to Mel spectrograms. Has a significant impact on timbre reproduction. Hyperparameters are prefixed with fm_*.

Hyperparameter properties

lm_max_epoch int (Required)Number of LM training epochs. Recommended: 60. Range: [1, 2147483647].lm_step int (Required)LM checkpoint save interval (save a checkpoint every N epochs). Recommended: 5. Range: [1, 2147483647].lm_num int (Required)Maximum number of LM checkpoints to retain. Recommended: 3. Range: [1, 2147483647].lm_batch_size int (Required)LM batch size. Recommended: 1000. Range: [1, 2147483647].fm_max_epoch int (Required)Number of FM training epochs. Recommended: 100. Range: [1, 2147483647].fm_step int (Required)FM checkpoint save interval (save a checkpoint every N epochs). Recommended: 10. Range: [1, 2147483647].fm_num int (Required)Maximum number of FM checkpoints to retain. Recommended: 3. Range: [1, 2147483647].fm_batch_size int (Required)FM batch size. Recommended: 2000. Range: [1, 2147483647].

training_datasets Array of Dataset (Conditionally required)Training dataset file list. Mutually exclusive with training_file_ids. If using training_file_ids, this parameter is not required. Only one training file is supported.

Dataset structure

data_source_type string (Required)Data source type. Valid values:

oss_mount (mount an OSS file)
file_id (a file 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. Supported regions: 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 path to the data.jsonl file. Unlike the file_id approach, you need to upload the uncompressed dataset folder to OSS; zip files are not supported.

file_id string (Conditionally required)Required when data_source_type is file_id. The file ID generated by the Upload File API.

validation_datasets Array of Dataset (Optional)Validation dataset file list. Same structure as training_datasets.Mutually exclusive with validation_file_ids. If neither is provided, the system automatically splits from the training set.training_file_ids array[string] (Conditionally required)Array of training dataset file IDs. Multiple IDs can be provided. Mutually exclusive with training_datasets. If using training_datasets, this parameter is not required. File IDs are obtained via the Upload File API.validation_file_ids array[string] (Optional)Array of validation dataset file IDs. Multiple IDs can be provided. Mutually exclusive with validation_datasets. If using validation_datasets, this parameter is not required. If neither is provided, the system automatically splits from the training set. File IDs are obtained via the Upload File API.job_name string (Optional)Fine-tuning job name.model_name string (Optional)Name of the model after fine-tuning is complete.

curl --location 'https://dashscope.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "cosyvoice-v3-flash",
    "training_datasets": [
        {
            "data_source_type": "file_id",
            "file_id": "<replace with training dataset file_id>"
        }
    ],
    "hyper_parameters": {
        "lm_max_epoch": 60,
        "lm_step": 5,
        "lm_num": 3,
        "lm_batch_size": 1000,
        "fm_max_epoch": 100,
        "fm_step": 10,
        "fm_num": 3,
        "fm_batch_size": 2000
    },
    "training_type": "efficient_sft"
}'

Response parameters

request_id stringUnique identifier for the request.output objectJob details.

Properties

job_id stringUnique identifier for the fine-tuning job. Used to query job details, logs, cancel, or delete a job. Format: ft-{yyyyMMddHHmm}-{4-char uuid}.job_name stringFine-tuning job name.model_name stringName of the model after fine-tuning is complete.status stringFine-tuning job status:

PENDING: Training is pending.
QUEUING: Training is queued (only one fine-tuning job can run at a time).
RUNNING: Training is in progress.
SUCCEEDED: Training succeeded.
FAILED: Training failed.
CANCELED: Training was canceled.
CANCELING: Training is being canceled.

finetuned_output stringThe new model ID after fine-tuning, used for deployment and invocation. Returned when job status is SUCCEEDED.model stringThe base model used.base_model stringThe base model used.training_file_ids arrayLegacy field. Always returns an empty array for new jobs. Use training_datasets instead.training_datasets Array of DatasetTraining dataset list.validation_file_ids arrayLegacy field. Always returns an empty array for new jobs. Use validation_datasets instead.validation_datasets Array of DatasetValidation dataset list. Returns an empty array if no validation set was specified.hyper_parameters objectThe actual hyperparameters used.training_type stringThe training method for fine-tuning.output_cnt integerNumber of checkpoints produced by this job. The detailed checkpoint list can be obtained via the Checkpoint management API.max_output_cnt integerMaximum number of checkpoints a single job can produce. Checkpoints exceeding this limit are truncated based on fine-tuning thoroughness.charge_type stringBilling type. For CosyVoice models, this is token.create_time stringJob creation time.end_time stringJob end time. Returned when job status is SUCCEEDED, FAILED, or CANCELED.usage integerNumber of tokens consumed by the fine-tuning job. Returned when 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 identifier, the Alibaba Cloud account ID.creator stringAlibaba Cloud account ID of the creator.modifier stringAlibaba Cloud account ID of the modifier.group stringFine-tuning job group.

code stringError code. Returned on failure. See the error code table below.message stringDetailed error description. Returned on failure.

Success response example
Error response example

Key fields: output.job_id (job ID) and output.finetuned_output (the new model name after fine-tuning).

{
    "request_id": "0eb05b0c-02ba-414a-9d0c-xxxxxxxxx",
    "output": {
        "job_id": "ft-202511111122-xxxx",
        "job_name": "ft-202511111122-xxxx",
        "status": "PENDING",
        "finetuned_output": "cosyvoice-v3-flash-ft-202511111122-xxxx",
        "model": "cosyvoice-v3-flash",
        "base_model": "cosyvoice-v3-flash",
        "training_file_ids": [],
        "training_datasets": [
            {
                "data_source_type": "file_id",
                "file_id": "xxxxxxxxxxxx"
            }
        ],
        "validation_file_ids": [],
        "validation_datasets": [],
        "hyper_parameters": {
            "lm_max_epoch": 60,
            "lm_step": 5,
            "lm_num": 3,
            "lm_batch_size": 1000,
            "fm_max_epoch": 100,
            "fm_step": 10,
            "fm_num": 3,
            "fm_batch_size": 2000
        },
        "training_type": "efficient_sft",
        "model_name": "ft-202511111122-xxxx",
        "output_cnt": 0,
        "max_output_cnt": 10,
        "charge_type": "token",
        "create_time": "2025-11-11 11:22:22"
    }
}

Error codes

If the API 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 parameters or incorrect parameter format. Fix the parameters according to the error message.
400	UnsupportedOperation	The resource cannot be operated on while in a specific state. Wait until the resource reaches an operable state before retrying.
404	NotFound	The resource to query or operate on does not exist. Verify the resource ID.
409	Conflict	A deployment instance with the same name already exists. Add a suffix to differentiate.
429	Throttling	Resource creation has triggered platform limits. Delete models that are no longer in use. If you need to increase the concurrent fine-tuning job limit or retain more successfully fine-tuned models, contact your account manager.
500	InternalError	Internal error. Record the request_id and contact Alibaba Cloud engineers via a support ticket.

Next steps

Fine-tuning is an asynchronous operation. After calling this API, you can use the Query and Manage Fine-Tuning Jobs API to check job status.

​Prerequisites

​Create a fine-tuning job