Alibaba Cloud Model Studio:Referensi API pembuatan audio

Kirim prompt teks dan audio referensi melalui HTTPS untuk menerima file audio yang dihasilkan. Halaman ini menjelaskan permintaan, respons, dan penanganan error.

Prasyarat

Dapatkan kunci API dan ID workspace dari region yang dipilih. Tetapkan keduanya sebagai variabel lingkungan DASHSCOPE_API_KEY dan SFM_WORKSPACE_ID. Contoh di bawah menggunakan Beijing.

Kirim permintaan POST HTTPS ke endpoint berikut. Ganti {WorkspaceId} dengan ID workspace Anda.

Singapura

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

Tiongkok (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

Header

Header	Wajib	Deskripsi
Authorization	Ya	Bearer <API Key>
Content-Type	Ya	application/json

Contoh permintaan

curl --request POST \
  "https://$SFM_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  --max-time 300 \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-audio-3.1-tts-next",
    "input": {
      "text_prompt": "A woman clearly says: Hello, welcome.",
      "format": "wav",
      "sample_rate": 48000,
      "channels": 2
    }
  }'

Contoh respons, dengan ID ilustratif dan URL unduhan placeholder:

{
  "request_id": "example-request-id",
  "output": {
    "finish_reason": "stop",
    "audio": {
      "data": "",
      "url": "https://example.com/generated.wav",
      "id": "audio_example-request-id",
      "expires_at": 1789616932,
      "duration": 1.12
    }
  },
  "usage": {
    "duration": 1
  }
}

Unduh file menggunakan output.audio.url dari respons aktual. URL berlaku selama 24 jam. Jangan gunakan URL placeholder di atas untuk mengunduh audio.

Parameter permintaan

model adalah field tingkat atas. Semua parameter generasi berada dalam objek input.

Field	Tipe	Wajib	Default	Deskripsi
model	string	Ya	—	ID Model. Lihat Model yang didukung.
input	object	Ya	—	Input pembuatan audio.
input.text_prompt	string	Ya	—	Deskripsi audio atau teks untuk disintesis. Gunakan @voice1, @voice2, dan @voice3 untuk mereferensikan klip audio secara berurutan. Batas panjang tercantum dalam tabel model.
input.references	array	Tidak	—	Klip audio referensi. Abaikan untuk generasi teks saja. Model saat ini menerima hingga 3 klip, masing-masing tidak lebih dari 30 detik dan tidak lebih besar dari 10 MB.
input.references[].audio_url	string	Kondisional	—	URL audio publik yang dapat diakses oleh layanan. Berikan field ini atau audio_data, jangan keduanya.
input.references[].audio_data	string	Kondisional	—	URI data audio: data:{mime_type};base64,{base64_encoded_data}. Saling eksklusif dengan audio_url.
input.format	string	Tidak	wav	Format output: wav, mp3, atau pcm. Output Opus tidak didukung.
input.sample_rate	integer	Tidak	48000	Laju sampel output dalam Hz: 8000, 16000, 24000, 44100, atau 48000.
input.channels	integer	Tidak	2	Jumlah saluran: 1 (mono) atau 2 (stereo).
input.volume	integer	Tidak	50	Volume. Rentang: [0, 100].
input.enable_cbr	boolean	Tidak	false	Hanya MP3. true mengaktifkan bitrate konstan (CBR); false menggunakan bitrate variabel (VBR).
input.bit_rate	integer	Tidak	128	Hanya CBR MP3, dalam kbps. Output aktual bergantung pada laju sampel dan level bitrate MP3 yang didukung. Lihat di bawah.
input.quality	integer	Tidak	5	Hanya VBR MP3. Rentang: [0, 9], di mana 0 adalah kualitas tertinggi.
input.rate	float	Tidak	1.0	Kecepatan bicara. Rentang: [0.5, 2.0].
input.seed	integer	Tidak	42	Seed acak tingkat permintaan.
input.enable_aigc_tag	boolean	Tidak	false	Apakah akan menambahkan watermark identifikasi AIGC ke audio yang dihasilkan.

Audio referensi mendukung WAV, MP3, dan OGG Opus, tetapi bukan PCM mentah. Format referensi dan output memiliki batasan yang berbeda: OGG Opus dapat digunakan sebagai input, tetapi Opus tidak dapat digunakan sebagai output.

Kirim audio referensi melalui URL atau data Base64, bukan melalui ID suara sistem atau kloning.

Bitrate CBR MP3

Laju sampel (Hz)	Bitrate output minimum (kbps)	Bitrate output maksimum (kbps)
8000	8	64
16000, 24000	8	160
44100, 48000	32	320

Laju sampel dan level bitrate MP3 menentukan bitrate output. Tabel mencantumkan batas output, bukan dukungan untuk setiap bilangan bulat dalam setiap rentang. Nilai di luar rentang dibatasi ke batas yang sesuai.

Kirim audio referensi

Contoh Python ini menggunakan dua klip audio referensi untuk menghasilkan percakapan dua pembicara. Instal requests, siapkan reference1.wav dan reference2.wav, masing-masing berisi pembicara yang berbeda dan memenuhi batas model, serta tetapkan variabel lingkungan yang dijelaskan di atas.

Slot mengikuti urutan daftar references: item pertama, reference1.wav, sesuai dengan @voice1; item kedua, reference2.wav, sesuai dengan @voice2. Contoh ini melakukan encoding Base64 pada setiap klip dan mereferensikan kedua pembicara dalam prompt.

import base64
import os
from pathlib import Path

import requests

reference1 = base64.b64encode(Path("reference1.wav").read_bytes()).decode("ascii")
reference2 = base64.b64encode(Path("reference2.wav").read_bytes()).decode("ascii")
workspace_id = os.environ["SFM_WORKSPACE_ID"]
endpoint = (
    f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com"
    "/api/v1/services/audio/tts/SpeechSynthesizer"
)
response = requests.post(
    endpoint,
    headers={
        "Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-audio-3.1-tts-next",
        "input": {
            "text_prompt": "@voice1 says: It is sunny today. Shall we take a walk? @voice2 replies: Sure, let us go to the park.",
            "references": [
                {"audio_data": f"data:audio/wav;base64,{reference1}"},
                {"audio_data": f"data:audio/wav;base64,{reference2}"}
            ],
            "format": "wav",
        },
    },
    timeout=300,
)
response.raise_for_status()
result = response.json()
audio_response = requests.get(result["output"]["audio"]["url"], timeout=60)
audio_response.raise_for_status()
Path("output.wav").write_bytes(audio_response.content)

Untuk menggunakan URL, ganti item daftar dengan {"audio_url": "publicly accessible audio URL"} dan abaikan audio_data. Nomor referensi mengikuti urutan daftar dan harus merujuk ke item yang ada.

Parameter respons

Field	Tipe	Deskripsi
request_id	string	ID Permintaan untuk pemecahan masalah.
output.finish_reason	string	"stop" saat penyelesaian normal.
output.audio.data	string	String kosong untuk mode permintaan ini. Unduh audio lengkap dari output.audio.url.
output.audio.url	string	URL unduhan audio lengkap, berlaku selama 24 jam.
output.audio.id	string	ID audio yang dihasilkan.
output.audio.expires_at	integer	Stempel waktu kedaluwarsa URL unduhan.
output.audio.duration	float	Durasi audio yang dihasilkan dalam detik.
usage.duration	integer	Durasi audio yang dihasilkan dibulatkan ke detik terdekat. Field ini tidak digunakan untuk menghitung biaya token.

Permintaan podcast dapat menghasilkan audio hingga 240 detik (4 menit); skenario lain dibatasi hingga 120 detik per permintaan. Untuk harga, lihat Harga model.

Model yang didukung

ID Model	Batas prompt	Durasi hasil generasi maksimum per permintaan
qwen-audio-3.1-tts-next	3,000 karakter	Podcast: 240 detik (4 menit); skenario lain: 120 detik

Untuk kasus penggunaan, contoh audio, dan panduan prompt, lihat Pembuatan audio. Contoh dalam dokumen ini menggunakan model ini.

Penanganan error

Contoh respons error:

{
  "request_id": "example-request-id",
  "code": "CLIENT_ERROR",
  "message": "text_prompt exceeds the maximum length of 3000 characters."
}

Status HTTP	kode	Tindakan
400	CLIENT_ERROR	Periksa panjang prompt, jumlah dan durasi referensi, eksklusivitas URL/Base64, indeks referensi, dan penggunaan field voice yang tidak didukung.
404	InvalidParameter	Untuk "Model tidak ada.", periksa ID model, wilayah, dan ketersediaan model untuk akun Anda.
401	InvalidApiKey	Periksa validitas kunci API.
403	AccessDenied	Periksa izin akses model.
429	Throttling.RateQuota	Kurangi laju permintaan.
400	DataInspectionFailed	Periksa apakah prompt atau audio referensi memenuhi persyaratan keamanan konten.
500	InternalError	Simpan request_id dan coba lagi nanti atau hubungi dukungan teknis.