Alibaba Cloud Model Studio:Referencia de la API de generación de audio

Envíe prompts de texto y audio de referencia mediante HTTPS para recibir archivos de audio generados. Esta página describe las solicitudes, las respuestas y el manejo de errores.

Requisitos previos

Obtenga una clave API y un ID de espacio de trabajo de la región seleccionada. Configúrelos como las variables de entorno DASHSCOPE_API_KEY y SFM_WORKSPACE_ID. Los ejemplos siguientes usan Beijing.

Envíe solicitudes HTTPS POST al siguiente endpoint. Reemplace {WorkspaceId} con su ID de espacio de trabajo.

Singapur

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

China (Beijing)

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

Headers

Header	Obligatorio	Descripción
Authorization	Sí	Bearer <API Key>
Content-Type	Sí	application/json

Ejemplo de solicitud

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

Respuesta de ejemplo, con IDs ilustrativos y una URL de descarga de marcador de posición:

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

Descargue el archivo usando output.audio.url de la respuesta real. La URL es válida por 24 horas. No use la URL de marcador de posición anterior para descargar audio.

Parámetros de solicitud

model es un campo de nivel superior. Todos los parámetros de generación pertenecen al objeto input.

Campo	Tipo	Obligatorio	Valor predeterminado	Descripción
model	string	Sí	—	ID del modelo. Consulte Modelos compatibles.
input	object	Sí	—	Entrada de generación de audio.
input.text_prompt	string	Sí	—	Descripción de audio o texto para sintetizar. Utilice @voice1, @voice2 y @voice3 para hacer referencia a los clips de audio en orden. Los límites de longitud se indican en la tabla de modelos.
input.references	array	No	—	Clips de audio de referencia. Omítalos para generación solo de texto. El modelo actual acepta hasta 3 clips, cada uno de no más de 30 segundos y no mayor de 10 MB.
input.references[].audio_url	string	Condicional	—	URL de audio pública accesible para el servicio. Proporcione este campo o audio_data, pero no ambos.
input.references[].audio_data	string	Condicional	—	URI de datos de audio: data:{mime_type};base64,{base64_encoded_data}. Mutuamente excluyente con audio_url.
input.format	string	No	wav	Formato de salida: wav, mp3 o pcm. No se admite la salida Opus.
input.sample_rate	integer	No	48000	Tasa de muestreo de salida en Hz: 8000, 16000, 24000, 44100 o 48000.
input.channels	integer	No	2	Número de canales: 1 (mono) o 2 (estéreo).
input.volume	integer	No	50	Volumen. Rango: [0, 100].
input.enable_cbr	boolean	No	false	Solo MP3. true habilita la tasa de bits constante (CBR); false usa la tasa de bits variable (VBR).
input.bit_rate	integer	No	128	Solo CBR de MP3, en kbps. La salida real depende de la tasa de muestreo y los niveles de tasa de bits de MP3 admitidos. Véase abajo.
input.quality	integer	No	5	Solo VBR de MP3. Rango: [0, 9], donde 0 es la calidad más alta.
input.rate	float	No	1.0	Velocidad de habla. Rango: [0.5, 2.0].
input.seed	integer	No	42	Semilla aleatoria a nivel de solicitud.
input.enable_aigc_tag	boolean	No	false	Si se debe agregar una marca de agua de identificación AIGC al audio generado.

El audio de referencia admite WAV, MP3 y OGG Opus, pero no PCM sin procesar. Los formatos de referencia y de salida tienen límites diferentes: OGG Opus se puede usar como entrada, pero Opus no se puede usar como salida.

Envíe audio de referencia a través de una URL o datos Base64, no a través de un ID de voz del sistema o clonada.

Tasa de bits CBR de MP3

Frecuencia de muestreo (Hz)	Tasa de bits de salida mínima (kbps)	Tasa de bits de salida máxima (kbps)
8000	8	64
16000, 24000	8	160
44100, 48000	32	320

La frecuencia de muestreo y los niveles de tasa de bits MP3 determinan la tasa de bits de salida. La tabla enumera los límites de salida, no la compatibilidad con cada número entero en cada rango. Los valores fuera del rango se restringen a los límites correspondientes.

Enviar audio de referencia

Este ejemplo de Python utiliza dos clips de audio de referencia para generar una conversación entre dos hablantes. Instale requests, prepare reference1.wav y reference2.wav, cada uno con un hablante diferente y cumpliendo los límites del modelo, y configure las variables de entorno descritas anteriormente.

Las ranuras siguen el orden de la lista references: el primer elemento, reference1.wav, corresponde a @voice1; el segundo elemento, reference2.wav, corresponde a @voice2. El ejemplo codifica en Base64 cada clip y hace referencia a ambos hablantes en el 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)

Para usar una URL, reemplace el elemento de la lista con {"audio_url": "publicly accessible audio URL"} y omita audio_data. Los números de referencia siguen el orden de la lista y deben apuntar a elementos existentes.

Parámetros de respuesta

Campo	Tipo	Descripción
request_id	string	ID de solicitud para solución de problemas.
output.finish_reason	string	"stop" al finalizar normalmente.
output.audio.data	string	Una cadena vacía para este modo de solicitud. Descargue el audio completo desde output.audio.url.
output.audio.url	string	URL completa de descarga de audio, válida por 24 horas.
output.audio.id	string	ID del audio generado.
output.audio.expires_at	integer	Marca de tiempo de caducidad de la URL de descarga.
output.audio.duration	float	Duración del audio generado en segundos.
usage.duration	integer	Duración del audio generado redondeada al segundo entero más cercano. Este campo no se utiliza para calcular cargos por tokens.

Las solicitudes de podcast pueden generar hasta 240 segundos (4 minutos) de audio; otros escenarios están limitados a 120 segundos por solicitud. Para consultar los precios, véase Precios de modelos.

Modelos compatibles

Model ID	Límite de prompt	Duración máxima generada por solicitud
qwen-audio-3.1-tts-next	3,000 caracteres	Podcasts: 240 segundos (4 minutos); otros escenarios: 120 segundos

Para casos de uso, ejemplos de audio y orientación sobre prompts, consulte Generación de audio. Los ejemplos en este documento utilizan este modelo.

Manejo de errores

Ejemplo de respuesta de error:

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

HTTP status	code	Action
400	CLIENT_ERROR	Verifique la longitud del prompt, el recuento y duración de referencias, exclusividad de URL/Base64, índices de referencia y el uso del campo voice no admitido.
404	InvalidParameter	Para "Model not exist.", verifique el ID del modelo, la región y la disponibilidad del modelo para su cuenta.
401	InvalidApiKey	Verifique la validez de la clave API.
403	AccessDenied	Verifique los permisos de acceso al modelo.
429	Throttling.RateQuota	Reduzca la tasa de solicitudes.
400	DataInspectionFailed	Verifique si el prompt o el audio de referencia cumplen con los requisitos de seguridad de contenido.
500	InternalError	Conserve el request_id y reintente más tarde o contacte al soporte técnico.