DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) Model Production Model tuning Speech Synthesis Create a Fine-Tuning Job

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

Updated at:
Copy as MD
Product
My Favorites

Create a speech synthesis fine-tuning training job. Datasets can be uploaded via API or mounted from OSS.

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/json

Authorization 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"
}'

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": "oss_mount",
            "mount_storage": {
                "region": "cn-beijing",
                "bucket": "example_bucket",
                "file_path": "dataset/data.jsonl"
            }
        }
    ],
    "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 string

Unique identifier for the request.

output object

Job details.

Properties

job_id string

Unique 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 string

Fine-tuning job name.

model_name string

Name of the model after fine-tuning is complete.

status string

Fine-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 string

The new model ID after fine-tuning, used for deployment and invocation. Returned when job status is SUCCEEDED.

model string

The base model used.

base_model string

The base model used.

training_file_ids array

Legacy field. Always returns an empty array for new jobs. Use training_datasets instead.

training_datasets Array of Dataset

Training dataset list.

validation_file_ids array

Legacy field. Always returns an empty array for new jobs. Use validation_datasets instead.

validation_datasets Array of Dataset

Validation dataset list. Returns an empty array if no validation set was specified.

hyper_parameters object

The actual hyperparameters used.

training_type string

The training method for fine-tuning.

output_cnt integer

Number of checkpoints produced by this job. The detailed checkpoint list can be obtained via the Checkpoint management API.

max_output_cnt integer

Maximum number of checkpoints a single job can produce. Checkpoints exceeding this limit are truncated based on fine-tuning thoroughness.

charge_type string

Billing type. For CosyVoice models, this is token.

create_time string

Job creation time.

end_time string

Job end time. Returned when job status is SUCCEEDED, FAILED, or CANCELED.

usage integer

Number of tokens consumed by the fine-tuning job. Returned when job status is SUCCEEDED or CANCELED.

workspace_id string

The workspace ID associated with the Alibaba Cloud Model Studio API Key. See Get the Workspace ID.

user_identity string

User identifier, the Alibaba Cloud account ID.

creator string

Alibaba Cloud account ID of the creator.

modifier string

Alibaba Cloud account ID of the modifier.

group string

Fine-tuning job group.

code string

Error code. Returned on failure. See the error code table below.

message string

Detailed error description. Returned on failure.

Success 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 response example

{
    "code": "InvalidParameter",
    "request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
    "message": "The model cosyvoice-v3-flash does not support training_type: full_sft"
}

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.

Previous：Speech SynthesisNext：Query fine-tuning task details