Pré-requisitos
- Obtenha e configure uma chave de API. Não insira chaves de API de longa duração diretamente no código do aplicativo móvel. Recomendamos gerar uma chave de API temporária no servidor do aplicativo e enviá-la ao cliente.
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote mais recente do SDK.
- Extraia o pacote
.tar.gzdo SDK e adicioneRelease/nuisdk.xcframeworkao projeto Xcode. - Em Build Phases > Link Binary With Libraries, adicione
nuisdk.xcframework. - Em General > Frameworks, Libraries, and Embedded Content, defina
nuisdk.xcframeworkcomo Embed & Sign.
Início rápido
Qwen-Audio-TTS
Abra o projeto de exemplo no Xcode. O código de exemplo está em DashQwen-Audio-TTSStreamInputTTSViewController.m. Substitua a chave de API de espaço reservado pela sua própria e execute o aplicativo para testá-lo.
CosyVoice
Abra o projeto de exemplo no Xcode. O código de exemplo está em DashCosyVoiceStreamInputTTSViewController.m. Substitua a chave de API de espaço reservado pela sua própria e execute o aplicativo para testá-lo.
Parâmetros da solicitação
Qwen-Audio-TTS
Exemplo de JSON de parâmetros: O exemplo a seguir não lista todos os campos. Adicione os outros conforme seu código exigir:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | string | Sim | O nome do modelo. |
voice | string | Sim | A voz usada para a síntese de fala.
|
format | string | Não | O formato de codificação de áudio.Valores válidos:
|
enable_audio_decoder | BOOL | Não | Se deve ativar o decodificador interno do SDK. Padrão: NO.Este parâmetro entra em vigor apenas quando o formato de codificação de áudio é opus ou mp3. Quando habilitado, o SDK decodifica dados de áudio opus ou mp3 em dados PCM antes de retorná-los. |
volume | int | Não | O nível de volume.Valor padrão: 50.Valores válidos: [0, 100]. |
sample_rate | int | Não | A taxa de amostragem de áudio em Hz.Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100, 48000. |
rate | float | Não | A velocidade da fala.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
pitch | float | Não | O tom.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
bit_rate | int | Não | A taxa de bits de áudio em kbps. Quando o formato de áudio for mp3 ou opus, use bit_rate para ajustar a taxa de bits.Valor padrão: 32.Valores válidos: [6, 510]. |
enable_ssml | boolean | Não | Se deve ativar o SSML.Padrão: false.
|
word_timestamp_enabled | boolean | Não | Especifica se deve ativar os timestamps no nível da palavra.Valor padrão: false.Disponível apenas no modo de saída em streaming. Vozes clonadas são suportadas. Para as vozes do sistema compatíveis, consulte lista de vozes do Qwen-Audio-TTS.Os carimbos de data/hora são retornados em |
seed | int | Não | Uma semente aleatória para controlar a variação na saída da síntese. Quando a versão do modelo, texto, voz e outros parâmetros permanecem inalterados, usar a mesma semente produz resultados idênticos.Valor padrão: 0.Valores válidos: [0, 65535]. |
language_hints | array[string] | Não | Para as vozes multilíngues e dialetais do qwen-audio-3.1-tts-flash, este parâmetro define o idioma ou dialeto. Para mais detalhes, consulte a seção de configuração de vozes multilíngues e dialetais.
Valores válidos
|
instruction | string | Não | Controla as características da síntese, como dialeto, emoção ou estilo de fala.Para detalhes de uso, consulte Controle de instrução. |
enable_aigc_tag | boolean | Não | Especifica se deve incorporar uma marca d'água AIGC no áudio gerado. Quando definido como true, a marca d'água é incorporada em arquivos de áudio de formatos suportados (wav/mp3/opus).Valor padrão: false. |
aigc_propagator | string | Não | Define o campo ContentPropagator na marca d'água AIGC, identificando o propagador de conteúdo. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: UID da Alibaba Cloud. |
aigc_propagate_id | string | Não | Define o campo PropagateID na marca d'água AIGC, identificando exclusivamente uma ação de propagação específica. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: O ID da solicitação de síntese de fala atual. |
hot_fix | object | Não | Configuração de correção rápida de texto para personalizar a pronúncia de palavras especificadas ou substituir texto antes da síntese.Campos:
|
CosyVoice
Exemplo de JSON de parâmetros: O exemplo a seguir não lista todos os campos. Adicione os outros conforme seu código exigir:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | string | Sim | O nome do modelo. |
voice | string | Sim | A voz usada para a síntese de fala.
|
format | string | Não | O formato de codificação de áudio.Valores válidos:
|
enable_audio_decoder | BOOL | Não | Se deve ativar o decodificador interno do SDK. Padrão: NO.Este parâmetro entra em vigor apenas quando o formato de codificação de áudio é opus ou mp3. Quando habilitado, o SDK decodifica dados de áudio opus ou mp3 em dados PCM antes de retorná-los. |
volume | int | Não | O nível de volume.Valor padrão: 50.Valores válidos: [0, 100]. |
sample_rate | int | Não | A taxa de amostragem de áudio em Hz.Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100, 48000. |
rate | float | Não | A velocidade da fala.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
pitch | float | Não | O tom.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
bit_rate | int | Não | A taxa de bits de áudio em kbps. Quando o formato de áudio for mp3 ou opus, use bit_rate para ajustar a taxa de bits.Valor padrão: 32.Valores válidos: [6, 510]. |
enable_ssml | boolean | Não | Se deve ativar o SSML.Padrão: false.
|
word_timestamp_enabled | boolean | Não | Especifica se deve ativar os timestamps no nível da palavra.Valor padrão: false.Disponível apenas no modo de saída em streaming. Vozes suportadas: vozes clonadas de cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, e vozes do sistema marcadas como suportadas na Lista de vozes do CosyVoice. Vozes clonadas de outros modelos não suportam este recurso.Os carimbos de data/hora são retornados em |
seed | int | Não | Uma semente aleatória para controlar a variação na saída da síntese. Quando a versão do modelo, texto, voz e outros parâmetros permanecem inalterados, usar a mesma semente produz resultados idênticos.Valor padrão: 0.Valores válidos: [0, 65535]. |
language_hints | array[string] | Não | Especifica o idioma de destino para a síntese de fala para melhorar a qualidade da saída.Quando a pronúncia de dígitos, expansão de abreviações, leitura de símbolos ou síntese em idiomas minoritários não atender às expectativas, use este parâmetro. Por exemplo:
Valores válidos
|
instruction | string | Não | Controla as características da síntese, como dialeto, emoção ou estilo de fala.Para detalhes de uso, consulte Controle de instrução. |
enable_aigc_tag | boolean | Não | Especifica se deve incorporar uma marca d'água AIGC no áudio gerado. Quando definido como true, a marca d'água é incorporada em arquivos de áudio de formatos suportados (wav/mp3/opus).Valor padrão: false. Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. |
aigc_propagator | string | Não | Define o campo ContentPropagator na marca d'água AIGC, identificando o propagador de conteúdo. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: UID da Alibaba Cloud.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. |
aigc_propagate_id | string | Não | Define o campo PropagateID na marca d'água AIGC, identificando exclusivamente uma ação de propagação específica. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: O ID da solicitação de síntese de fala atual.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. |
hot_fix | object | Não | Configuração de correção rápida de texto para personalizar a pronúncia de palavras especificadas ou substituir texto antes da síntese. cosyvoice-v2 não suporta este recurso.
|
enable_markdown_filter | BOOL | Não | Apenas as vozes clonadas do cosyvoice-v3-flash suportam este recurso. NO.Valores válidos:
|
Referência da API
NeoNui
Destaques da arquitetura:
- Padrão Singleton: obtenha a instância global através de
[StreamInputTts get_instance]. - Orientado a callbacks: receba eventos e dados de áudio através do protocolo
StreamInputTtsDelegate. - Configuração JSON: passe os parâmetros como strings JSON.
sendStreamInputTts
Envia texto para ser sintetizado. Use este método junto com startStreamInputTts.
Depois de chamar startStreamInputTts, use este método para enviar texto continuamente.
Depois que todo o texto for enviado, chame stopStreamInputTts ou asyncStopStreamInputTts para sinalizar o fim da entrada.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | char* | Texto a ser sintetizado. SSML não é suportado. As tags SSML na entrada são lidas como texto simples em vez de serem analisadas. |
stopStreamInputTts
Método síncrono. Notifica o servidor de que todo o texto foi enviado e, em seguida, bloqueia até que cada bloco de áudio seja sintetizado e TTS_EVENT_SYNTHESIS_COMPLETE seja recebido.
O tempo limite de bloqueio é controlado por complete_waiting_ms.
Assinatura do método
asyncStopStreamInputTts
Método assíncrono. Notifica o servidor de que todo o texto foi enviado e retorna imediatamente. A síntese continua em segundo plano.
Use TTS_EVENT_SYNTHESIS_COMPLETE para detectar quando a síntese termina.
Assinatura do método
cancelStreamInputTts
Encerra imediatamente a conexão com o servidor e finaliza a tarefa de síntese atual. Após a chamada deste método, nenhum outro callback de dados de áudio é acionado.
Assinatura do método
playStreamInputTts
Método de síntese síncrona de uma única vez. Envia o texto e bloqueia enquanto todos os dados de áudio são recebidos, e então retorna após a conclusão da síntese. Você não precisa chamar stopStreamInputTts depois.
Este método habilita SSML por padrão. Para desabilitar o SSML, defina o campo enable_ssml em parameters como false.
Assinatura do método
ticket, parameters e outros parâmetros compartilhados usam as mesmas definições de startStreamInputTts.
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | char* | Texto a ser sintetizado. Suporta SSML. |
asyncPlayStreamInputTts
Este método envia todo o texto para síntese de forma assíncrona. Ele retorna imediatamente sem esperar pelos dados de áudio. Você não precisa chamar stopStreamInputTts depois.
Este método habilita SSML por padrão. Para desabilitar o SSML, defina o campo enable_ssml em parameters como false.
Assinatura do método
ticket, parameters e outros parâmetros compartilhados usam as mesmas definições de startStreamInputTts.
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | char* | Texto a ser sintetizado. Suporta SSML. |
onStreamInputTtsEventCallback: ouvir eventos
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
event | StreamInputTtsCallbackEvent | Evento de callback. |
taskid | char* | ID da tarefa de síntese de fala. |
sessionId | char* | ID da sessão. O valor fornecido pelo cliente é retornado como está. Se none for fornecido, o servidor gera um. |
ret_code | int | Código de erro. Válido apenas para o evento TTS_EVENT_TASK_FAILED. Consulte os códigos de erro. |
error_msg | char* | Mensagem de erro. Válida apenas para o evento TTS_EVENT_TASK_FAILED. |
timestamp | char* | Informações de timestamp para o resultado da síntese. |
all_response | char* | Resposta JSON completa. Analise esta string para extrair os campos necessários. |
onStreamInputTtsDataCallback: ouvir dados de áudio
O SDK aciona este callback repetidamente durante a síntese. Leia os dados de áudio do callback.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
buffer | char* | Dados de áudio para o segmento atual. Use estes dados para:
|
len | int | Comprimento dos dados de áudio, em bytes. |
onStreamInputTtsLogTrackCallback: ouvir logs de rastreamento
Este callback entrega logs internos detalhados do SDK para ajudar na solução de problemas e depuração.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
level | NuiSdkLogLevel | Nível de log. |
log | char* | Conteúdo do log. |
NuiSdkLogLevel
Enumeração de nível de log do SDK que controla a saída de log.
| Nível | Descrição |
|---|---|
| 0: LOG_LEVEL_VERBOSE | Nível de log mais detalhado. Inclui todas as informações de depuração. |
| 1: LOG_LEVEL_DEBUG | Logs de nível de depuração. |
| 2: LOG_LEVEL_INFO | Logs informativos gerais (padrão). |
| 3: LOG_LEVEL_WARNING | Logs de nível de aviso. |
| 4: LOG_LEVEL_ERROR | Logs de nível de erro. |
| 5: LOG_LEVEL_NONE | Desativa a saída de log. |
Modos de chamada
| Modo de chamada | Descrição |
|---|---|
| Entrada única | Etapas:
|
Entrada em streaming | Etapas:
|
Marcação SSML
Objetivo: Incorporar tags XML no texto de entrada para controlar com precisão a pronúncia, a taxa de fala, as pausas e outros detalhes de prosódia.
Limitações: O SSML é suportado apenas com Entrada única (os métodos playStreamInputTts e asyncPlayStreamInputTts). Não é suportado com Entrada em streaming (o método sendStreamInputTts).
Como usar: Ao chamar playStreamInputTts ou asyncPlayStreamInputTts, o SDK habilita o SSML automaticamente. Passe o texto que contém tags SSML diretamente no parâmetro text.
Para mais detalhes, consulte SSML.
Expressões matemáticas
Objetivo: Fazer com que o modelo leia fórmulas e expressões matemáticas comuns corretamente.
Como usar: Passe o texto que contém expressões matemáticas no formato LaTeX diretamente no parâmetro text. Para mais detalhes, consulte Converter fórmulas LaTeX em fala (apenas idioma chinês).
Qwen-Audio-TTS
Fluxos de chamada
Qwen-Audio-TTS suporta dois modos de invocação: entrada única e entrada em streaming.
Entrada única: ideal para síntese de texto curto ou quando você precisa de marcação SSML.
playStreamInputTts()ouasyncPlayStreamInputTts()— Envia um texto completo e inicia a síntese. O primeiro é síncrono e retorna após a conclusão da síntese; o último é assíncrono e retorna imediatamente após o início da síntese.onStreamInputTtsDataCallback()— Receber dados de áudio.TTS_EVENT_SYNTHESIS_COMPLETE— Síntese concluída.
startStreamInputTts()— Inicializa o SDK e define o delegate de callback e os parâmetros de conexão.sendStreamInputTts()— Envia continuamente fragmentos de texto a serem sintetizados.onStreamInputTtsDataCallback()— Receber dados de áudio.stopStreamInputTts()ouasyncStopStreamInputTts()— Envia a solicitação de fim de síntese. O primeiro é síncrono e retorna após a conclusão da síntese; o último é assíncrono e retorna imediatamente após o envio da solicitação.TTS_EVENT_SYNTHESIS_COMPLETE— Síntese concluída.
startStreamInputTts
Inicia uma tarefa de síntese de fala em streaming e abre uma conexão com o servidor.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
ticket | char* | String JSON que contém configurações de autenticação, conexão e depuração. |
parameters | char* | String JSON que contém as configurações de efeito de síntese de fala. |
sessionId | char* | ID de sessão especificado pelo cliente. Se omitido, o servidor gera um. |
logLevel | NuiSdkLogLevel | Nível de impressão para os logs internos do SDK. |
saveLog | BOOL | Se deve salvar logs localmente. Quando definido como YES, você deve especificar um caminho com debug_path e pode limitar o tamanho do arquivo com max_log_file_size. |
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | Endereço do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
apikey | string | Sim | Chave de API. Para limitar a exposição caso uma chave de longa duração vaze, use uma chave de API de curta duração. |
device_id | string | Sim | Identificador exclusivo para o usuário final. Defina isso como o ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. O ID é usado para rastreamento de logs e solução de problemas. |
complete_waiting_ms | int | Não | Tempo limite, em milissegundos, para aguardar o evento de conclusão da síntese (TTS_EVENT_SYNTHESIS_COMPLETE) após chamar stopStreamInputTts.Padrão: 10000. |
debug_path | string | Não | Caminho local onde os arquivos de log são armazenados.Este campo só entra em vigor quando saveLog é definido como YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts. Nesse caso, você deve definir este caminho; caso contrário, um erro é retornado.No máximo dois arquivos de log são mantidos localmente. |
max_log_file_size | int | Não | Tamanho máximo de um arquivo de log, em bytes.Este campo só entra em vigor quando saveLog é definido como YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts.Padrão: 104857600 (100 × 1024 × 1024 bytes, ou seja, 100 MiB). |
log_track_level | int | Não | Nível de filtro para logs entregues através do callback de log (onStreamInputTtsLogTrackCallback).Padrão: 2.Valores válidos:
log_track_level e logLevel (definidos por meio de startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts) juntos determinam quais logs chegam ao callback. Um log aciona o callback apenas quando seu nível está igual ou acima de ambos os limites. Por exemplo, se log_track_level for 2 (INFO) e logLevel for 3 (WARNING), apenas logs no nível WARNING ou superior (nível >= 3) são entregues. |
StreamInputTtsDelegate
Protocolo de callback para síntese de fala em streaming do Qwen-Audio-TTS. Implemente este protocolo para receber eventos de síntese, dados de áudio e logs.
StreamInputTtsCallbackEvent
Enumeração de tipo de evento para síntese de fala em streaming do Qwen-Audio-TTS.
| Evento | Descrição |
|---|---|
TTS_EVENT_SYNTHESIS_STARTED | O servidor aceitou a solicitação e iniciou o processamento. onStreamInputTtsDataCallback normalmente entrega o primeiro segmento de áudio logo após este evento. |
TTS_EVENT_SENTENCE_SYNTHESIS | Informações de progresso emitidas durante a síntese, incluindo dados de faturamento. |
TTS_EVENT_SYNTHESIS_COMPLETE | O servidor terminou de enviar todos os dados de áudio. onStreamInputTtsDataCallback não é chamado novamente. Este evento é o sinal definitivo de fim de stream. |
TTS_EVENT_TASK_FAILED | A tarefa falhou. Leia task_id, error_code e error_message de all_response em onStreamInputTtsEventCallback para diagnosticar a falha. |
Recursos avançados
CosyVoice
Fluxos de chamada
CosyVoice suporta dois modos de invocação: entrada única e entrada em streaming.
Entrada única: ideal para síntese de texto curto ou quando você precisa de marcação SSML.
playStreamInputTts()ouasyncPlayStreamInputTts()— Envia um texto completo e inicia a síntese. O primeiro é síncrono e retorna após a conclusão da síntese; o último é assíncrono e retorna imediatamente após o início da síntese.onStreamInputTtsDataCallback()— Receber dados de áudio.TTS_EVENT_SYNTHESIS_COMPLETE— Síntese concluída.
startStreamInputTts()— Inicializa o SDK e define o delegate de callback e os parâmetros de conexão.sendStreamInputTts()— Envia continuamente fragmentos de texto a serem sintetizados.onStreamInputTtsDataCallback()— Receber dados de áudio.stopStreamInputTts()ouasyncStopStreamInputTts()— Envia a solicitação de fim de síntese. O primeiro é síncrono e retorna após a conclusão da síntese; o último é assíncrono e retorna imediatamente após o envio da solicitação.TTS_EVENT_SYNTHESIS_COMPLETE— Síntese concluída.
startStreamInputTts
Inicia uma tarefa de síntese de fala em streaming e abre uma conexão com o servidor.
Assinatura do método
| Parâmetro | Tipo | Descrição |
|---|---|---|
ticket | char* | String JSON que contém configurações de autenticação, conexão e depuração. |
parameters | char* | String JSON que contém as configurações de efeito de síntese de fala. |
sessionId | char* | ID de sessão especificado pelo cliente. Se omitido, o servidor gera um. |
logLevel | NuiSdkLogLevel | Nível de impressão para os logs internos do SDK. |
saveLog | BOOL | Se deve salvar logs localmente. Quando definido como YES, você deve especificar um caminho com debug_path e pode limitar o tamanho do arquivo com max_log_file_size. |
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | Endereço do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
apikey | string | Sim | Chave de API. Para limitar a exposição caso uma chave de longa duração vaze, use uma chave de API de curta duração. |
device_id | string | Sim | Identificador exclusivo para o usuário final. Defina isso como o ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. O ID é usado para rastreamento de logs e solução de problemas. |
complete_waiting_ms | int | Não | Tempo limite, em milissegundos, para aguardar o evento de conclusão da síntese (TTS_EVENT_SYNTHESIS_COMPLETE) após chamar stopStreamInputTts.Padrão: 10000. |
debug_path | string | Não | Caminho local onde os arquivos de log são armazenados.Este campo só entra em vigor quando saveLog é definido como YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts. Nesse caso, você deve definir este caminho; caso contrário, um erro é retornado.No máximo dois arquivos de log são mantidos localmente. |
max_log_file_size | int | Não | Tamanho máximo de um arquivo de log, em bytes.Este campo só entra em vigor quando saveLog é definido como YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts.Padrão: 104857600 (100 × 1024 × 1024 bytes, ou seja, 100 MiB). |
log_track_level | int | Não | Nível de filtro para logs entregues através do callback de log (onStreamInputTtsLogTrackCallback).Padrão: 2.Valores válidos:
log_track_level e logLevel (definidos por meio de startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts) juntos determinam quais logs chegam ao callback. Um log aciona o callback apenas quando seu nível está igual ou acima de ambos os limites. Por exemplo, se log_track_level for 2 (INFO) e logLevel for 3 (WARNING), apenas logs no nível WARNING ou superior (nível >= 3) são entregues. |
StreamInputTtsDelegate
Protocolo de callback para síntese de fala em streaming do CosyVoice. Implemente este protocolo para receber eventos de síntese, dados de áudio e logs.
StreamInputTtsCallbackEvent
Enumeração de tipo de evento para síntese de fala em streaming do CosyVoice.
| Evento | Descrição |
|---|---|
TTS_EVENT_SYNTHESIS_STARTED | O servidor aceitou a solicitação e iniciou o processamento. onStreamInputTtsDataCallback normalmente entrega o primeiro segmento de áudio logo após este evento. |
TTS_EVENT_SENTENCE_SYNTHESIS | Informações de progresso emitidas durante a síntese, incluindo dados de faturamento. |
TTS_EVENT_SYNTHESIS_COMPLETE | O servidor terminou de enviar todos os dados de áudio. onStreamInputTtsDataCallback não é chamado novamente. Este evento é o sinal definitivo de fim de stream. |
TTS_EVENT_TASK_FAILED | A tarefa falhou. Leia task_id, error_code e error_message de all_response em onStreamInputTtsEventCallback para diagnosticar a falha. |