DocsICP FilingConsole
官方文档
首页

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

更新时间：
复制 MD 格式
产品详情
我的收藏

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

Prerequisites

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

Using file_id dataset

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

Using OSS-mounted dataset

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

Response parameters

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

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.

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