音声クローニング Java SDK リファレンス - DashScope - Alibaba Cloud Model Studio

DashScope Java SDK を使用して、Qwen-Audio-TTS / Qwen-Audio-Realtime / CosyVoice の音声をクローンし、管理します。

サービスエンドポイント

SDK は、デフォルトで China (Beijing) エンドポイントを使用します。別のリージョンに切り替えるには、初期化の前に Constants.baseHttpApiUrl を変更します。

注記

API キーはリージョンごとに異なります。対象リージョンに対応する API キーを使用してください。
リージョン設定はグローバルに適用され、すべての DashScope SDK API コールに影響します。

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

{WorkspaceId} は、実際のワークスペース ID に置き換えてください。

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

{WorkspaceId} は、実際のワークスペース ID に置き換えてください。

重要Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールの各リージョン向けにワークスペース固有ドメインをリリースしました。これらの新しい専用ドメインにより、推論リクエストのパフォーマンスと安定性が向上します。以下の新しいドメインへの移行を推奨します：

中国 (北京)：dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com へ
シンガポール：dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com へ

VoiceEnrollmentService クラス

パッケージ： com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService

目的：Qwen-Audio-TTS、Qwen-Audio-Realtime、CosyVoice のクローン音色のライフサイクル (作成、照会、更新、削除) を管理します。

コンストラクター

public VoiceEnrollmentService(String apiKey)

パラメーター：

パラメーター	タイプ	説明
apiKey	String	API キー

createVoice() - 音声の作成

メソッドシグネチャ：

public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

パラメーター：

パラメーター	タイプ	必須	説明
targetModel	String	はい	音色を使用する対象モデル。後続のリクエストでその音色を使用するモデルと一致する必要があります。一致しない場合、リクエストは失敗します。
prefix	String	はい	音声名のプレフィックス。英数字のみが許可され、最大長は 10 文字です。結果として得られる音声名は、`{target_model}-{prefix}-{unique_id}` のフォーマットに従います。
url	String	はい	音声クローニングに使用する参照音声。公開アクセス可能な URL または `data:audio/wav;base64,...` 形式の Base64 Data URI を指定できます。
customParam	VoiceEnrollmentParam	いいえ	`languageHints` や `maxPromptAudioLength` などのカスタムパラメーター。

戻り値：Voice オブジェクトを返します。getVoiceId() を呼び出して音声 ID を取得します。

listVoice() - 音声の一覧取得

メソッドシグネチャ：

public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

パラメーター：

パラメーター	タイプ	必須	説明
prefix	String	いいえ	音声名のプレフィックスで音声をフィルタリングします。
pageIndex	int	いいえ	ページインデックス。0 から始まります。
pageSize	int	いいえ	1 ページあたりのレコード数。

戻り値：Voice[] 配列を返します。

queryVoice() - 音声詳細の取得

メソッドシグネチャ：

public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

パラメーター：

パラメーター	タイプ	必須	説明
voiceId	String	はい	取得する音声の ID。

戻り値：音声詳細を含む Voice オブジェクトを返します。

updateVoice() - 音声の更新

メソッドシグネチャ一覧：

public void updateVoice(String voiceId, String url) throws NoApiKeyException, InputRequiredException
public void updateVoice(String voiceId, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

パラメーター：

パラメーター	タイプ	必須	説明
voiceId	String	はい	更新する音声 ID。
url	String	はい	新しい参照音声。公開アクセス可能な URL または `data:audio/wav;base64,...` 形式の Base64 Data URI を指定できます。
customParam	VoiceEnrollmentParam	いいえ	カスタムパラメーター。

deleteVoice() - 音声の削除

メソッドシグネチャ：

public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException

パラメーター：

パラメーター	タイプ	必須	説明
voiceId	String	はい	削除する音声 ID。

VoiceEnrollmentParam クラス

パッケージ： com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam

ビルダーパターンを使用してパラメーターオブジェクトを構築します。

メソッド	タイプ	説明
model(String)	String	音声クローニングモデル。値は "voice-enrollment" である必要があります。
`languageHints(List<String>)`	`List<String>`	モデルがサンプル音声の言語を識別し、音声特徴をより正確に抽出し、クローニング品質を向上させるのに役立ちます。指定された言語が実際の音声言語と一致しない場合 (たとえば、音声が中国語なのに `en` を設定した場合)、システムはこの値を無視し、言語を自動的に検出します。このパラメーターは配列で、要素数は 1 である必要があります。注記対象モデル：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-plus、cosyvoice-v3-flash。クリックしてモデル別の対応言語を表示 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash： zh：中国語 en：英語 fr：フランス語 de：ドイツ語 ja：日本語 ko：韓国語 ru：ロシア語 pt：ポルトガル語 th：タイ語 id：インドネシア語 vi：ベトナム語 it：イタリア語 es：スペイン語 ms：マレーシア語 fil：フィリピン語 ar：アラビア語 cosyvoice-v3-plus： zh：中国語 en：英語 fr：フランス語 de：ドイツ語 ja：日本語 ko：韓国語 ru：ロシア語 cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash： zh：中国語 en：英語 fr：フランス語 de：ドイツ語 ja：日本語 ko：韓国語 ru：ロシア語 pt：ポルトガル語 th：タイ語 id：インドネシア語 vi：ベトナム語デフォルト： ["zh"]。
maxPromptAudioLength(Float)	Float	前処理後の参照音声の最大持続時間 (秒)。有効な値： [3.0, 30.0]。デフォルト： 10.0。注記対象モデル：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
parameter(String, Object)	Object	`parameter("language_hints", Arrays.asList("en"))`、`parameter("max_prompt_audio_length", 10.0f)`、`parameter("enable_preprocess", false)`、`parameter("enable_volume_normalization", "false")` などのカスタムパラメーターを設定します。

追加パラメーター

パラメーター タイプ 必須説明

パラメーター	タイプ	必須	説明
enable_preprocess	boolean	いいえ	音声前処理 (ノイズリダクション、音声強調、音量正規化) を有効にするかどうか。バックグラウンドノイズのある録音の場合はこれを有効にします。静かな環境での録音の場合は、元の音声特性を保持するために無効にします。デフォルト： false。注記対象モデル：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
enable_volume_normalization	String	いいえ	音声クローニングに使用されるサンプル音声の音量を正規化するかどうかを指定します。有効な値は `"true"` と `"false"` です。このパラメーターを有効にすると、生成される音声の音量が、無効にした場合と異なることがあります。デフォルト： `"false"`。

enable_preprocess

boolean

いいえ

音声前処理 (ノイズリダクション、音声強調、音量正規化) を有効にするかどうか。バックグラウンドノイズのある録音の場合はこれを有効にします。静かな環境での録音の場合は、元の音声特性を保持するために無効にします。

デフォルト： false。

注記対象モデル：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。

enable_volume_normalization

String

いいえ

音声クローニングに使用されるサンプル音声の音量を正規化するかどうかを指定します。有効な値は "true" と "false" です。このパラメーターを有効にすると、生成される音声の音量が、無効にした場合と異なることがあります。デフォルト： "false"。

サンプルコード

音声の作成

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Arrays;

public class Main {
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args) {
        // 以下ではシンガポールリージョンを使用します。 {WorkspaceId} を実際のワークスペース ID に置き換えてください。他のリージョンについては、それに応じて URL を変更してください。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String targetModel = "qwen-audio-3.0-tts-flash";
        String prefix = "myvoice";
        String fileUrl = "https://your-audio-file-url";
        String cloneModelName = "voice-enrollment";

        try {
            VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
            Voice myVoice = service.createVoice(
                    targetModel,
                    prefix,
                    fileUrl,
                    VoiceEnrollmentParam.builder()
                            .model(cloneModelName)
                            .parameter("language_hints", Arrays.asList("en"))
                            // .parameter("max_prompt_audio_length", 10.0f)
                            // .parameter("enable_preprocess", false)
                            // .parameter("enable_volume_normalization", "false")
                            .build());

            logger.info("音声作成リクエストを送信しました。リクエスト ID：{}", service.getLastRequestId());
            logger.info("生成された音声 ID：{}", myVoice.getVoiceId());
        } catch (Exception e) {
            logger.error("音声の作成に失敗しました", e);
        }
    }
}

ローカルの WAV ファイルを使用する場合は、上記の try ブロック内で createVoice を呼び出す前に、以下の代入を追加します。音声の更新時も、Data URI を updateVoice の url パラメーターに指定します。sample.wav をローカル音声ファイルのパスに置き換えてください。

fileUrl = "data:audio/wav;base64," + java.util.Base64.getEncoder().encodeToString(
        java.nio.file.Files.readAllBytes(java.nio.file.Paths.get("sample.wav")));

音声の一覧表示

この例では、サードパーティライブラリ com.google.gson.Gson が必要です。

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // 環境変数を使用しない場合は、ご自身の API キーに置き換えてください
    private static String prefix = "myvoice"; // 実際の値に置き換えてください
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // 以下ではシンガポールリージョンを使用します。 {WorkspaceId} を実際のワークスペース ID に置き換えてください。他のリージョンについては、それに応じて URL を変更してください。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // 音声の一覧表示
        Voice[] voices = service.listVoice(prefix, 0, 10);
        logger.info("一覧の取得に成功しました。リクエスト ID：{}", service.getLastRequestId());
        logger.info("音声の詳細：{}", new Gson().toJson(voices));
    }
}

特定の音声の取得

この例では、サードパーティライブラリ com.google.gson.Gson が必要です。

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // 環境変数を使用しない場合は、ご自身の API キーに置き換えてください
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // 実際の値に置き換えてください
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // 以下ではシンガポールリージョンを使用します。 {WorkspaceId} を実際のワークスペース ID に置き換えてください。他のリージョンについては、それに応じて URL を変更してください。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        Voice voice = service.queryVoice(voiceId);

        logger.info("クエリに成功しました。リクエスト ID：{}", service.getLastRequestId());
        logger.info("音声の詳細：{}", new Gson().toJson(voice));
    }
}

音声の更新

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // 環境変数を使用しない場合は、ご自身の API キーに置き換えてください
    private static String fileUrl = "https://your-audio-file-url";  // 実際の値に置き換えてください
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // 実際の値に置き換えてください
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // 以下ではシンガポールリージョンを使用します。 {WorkspaceId} を実際のワークスペース ID に置き換えてください。他のリージョンについては、それに応じて URL を変更してください。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // 音声を更新
        service.updateVoice(voiceId, fileUrl);
        logger.info("更新リクエストを送信しました。リクエスト ID：{}", service.getLastRequestId());
    }
}

音声の削除

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // 環境変数を使用しない場合は、ご自身の API キーに置き換えてください
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // 実際の値に置き換えてください
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // 以下ではシンガポールリージョンを使用します。 {WorkspaceId} を実際のワークスペース ID に置き換えてください。他のリージョンについては、それに応じて URL を変更してください。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // 音声を削除
        service.deleteVoice(voiceId);
        logger.info("削除リクエストを送信しました。リクエスト ID：{}", service.getLastRequestId());
    }
}