> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Integração da API de Geração de Áudios do Producer
> Producer Music Generation 集成指南 - XHuoAPI
Este documento apresentará uma descrição da integração da API de Geração de Áudios do Producer, que pode gerar músicas oficiais do Producer através da entrada de parâmetros personalizados.
## Processo de Solicitação
Para usar a API, você precisa primeiro acessar a página correspondente da [API de Geração de Áudios do Producer](https://api.xhuoapi.ai/documents/producer-audios) para solicitar o serviço correspondente. Após entrar na página, clique no botão "Adquirir", conforme mostrado na imagem:
Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual.
Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.
## Uso Básico
Para gerar músicas, você pode inserir qualquer texto, por exemplo, se eu quiser gerar uma música sobre o Natal, posso inserir `a song for Christmas`, conforme mostrado na imagem:
Aqui, podemos ver que configuramos os Cabeçalhos da Solicitação, incluindo:
* `accept`: o formato de resposta desejado, aqui preenchido como `application/json`, ou seja, formato JSON.
* `authorization`: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Além disso, os parâmetros do Corpo da Solicitação incluem:
* `action`: a ação da tarefa de geração de música, que é `generate`.
* `model`: o modelo utilizado para criar a música, atualmente os principais são: **FUZZ-2.0 Pro**, **FUZZ-2.0**, **FUZZ-2.0 Raw**, **FUZZ-1.1 Pro**, **FUZZ-1.0 Pro**, **FUZZ-1.0**, **FUZZ-1.1**, **FUZZ-0.8**.
* `lyric`: o conteúdo da letra da música.
* `custom`: se a música deve ser gerada de forma personalizada.
* `prompt`: a palavra-chave no modo de inspiração.
* `title`: informações sobre o título da música.
* `audio_id`: ID da música de referência, usado para continuar ou replicar.
* `continue_at`: continuar a partir de um número de segundos especificado.
* `replace_section_start`/`replace_section_end`: tempo de início e fim do trecho a ser substituído, em segundos.
* `lyrics_strength`: intensidade da letra, indicando o grau de influência da letra na geração do áudio, podendo ser de 0 a 1, com padrão de 0.7.
* `sound_strength`: intensidade da palavra-chave de áudio, podendo ser de 0.2 a 1, com padrão de 0.7.
* `cover_strength`: intensidade da reinterpretação, de 0.2 a 1, com padrão de 1.
* `weirdness`: grau de peculiaridade do estilo, podendo ser de 0 a 1, com padrão de 0.5.
* `callback_url`: URL para onde os resultados devem ser retornados.
* `instrumental`: se deve ser no modo sem letra.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, conforme mostrado na imagem:
Clique no botão "Tentar" para realizar o teste, como mostrado na imagem acima, e você receberá o seguinte resultado:
```json theme={null}
{
"success": true,
"task_id": "82fd443a-903a-4f18-8028-12d2f8a0a4be",
"trace_id": "d85839fa-0bb1-42da-a9fc-cd582c29027d",
"data": [
{
"id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d",
"title": "Untitled",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/a853673e-615c-42ae-bdff-16b1add94861/image/6c947f13-a3c5-4b9c-8609-5639c37cdc2d.jpg",
"lyric": "[Instrumental]",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/a853673e-615c-42ae-bdff-16b1add94861/audio/6c947f13-a3c5-4b9c-8609-5639c37cdc2d.m4a",
"video_url": null,
"image_id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d",
"topic": null,
"seed": "2450882164",
"sound": "A song for Christmas",
"created_at": "2025-12-30T17:18:23.232911Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "181.3014058956916"
}
]
}
```
O resultado retornado contém vários campos, descritos a seguir:
* `success`, o estado atual da tarefa de geração de música.
* `data`, o resultado da tarefa de música atual
* `id`, o ID da tarefa de geração de música atual.
* `sound`, a palavra-chave da tarefa de geração de música atual.
* `seed`, o valor da semente da tarefa de geração de música atual.
* `audio_url`, o link de áudio da tarefa de geração de música atual.
* `image_url`, o link da capa da tarefa de geração de música atual.
* `image_id`, o ID da capa da tarefa de geração de música atual.
* `state`, o estado da tarefa de geração de música atual.
* `duration`, a duração da música atual.
* `progress`, o valor de progresso da tarefa de música atual.
* `model`, as informações do modelo utilizado na tarefa de geração de música atual.
* `lyric`, as informações da letra da tarefa de geração de música atual.
Podemos ver que recebemos as informações da música que desejamos gerar, e tudo o que precisamos fazer é acessar o link de áudio da música no `data` para obter a música do Producer gerada.
Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"model": "FUZZ-2.0 Pro",
"prompt": "A song for Christmas"
}'
```
## Geração Personalizada
Se você quiser gerar letras personalizadas, pode inserir a letra:
Neste caso, o campo `lyric` pode receber um conteúdo semelhante ao seguinte:
```
[Verse]Woke up with the sun in my eyesNo clouds above just blue in the skiesShoes on my feet I’m ready to runEvery step feels like a loaded gun[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Verse 2]Dancing through the city streetsA rhythm pounding in my heartbeatStrangers smile it’s catching onThis world’s a stage we’re all a song[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Bridge]Throw your worries out the doorLet them sink to the ocean floorWe’re alive and it’s enoughLife is messy but it’s love[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high
```
Em seguida, para personalizar a geração da música com base na letra, título e estilo, você pode especificar o seguinte conteúdo:
* lyric: texto da letra
* custom: preenchido como `true`, representando a geração personalizada, este parâmetro é `false` por padrão, representando a geração usando `prompt`.
* title: o título da música.
填写样例如下：
填写完毕之后自动生成了代码如下：
对应的代码：
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"model": "FUZZ-2.0 Pro",
"instrumental": false,
"lyric": "[Verse]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verse 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Bridge]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é o suficiente\nA vida é bagunçada, mas é amor\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"custom": true
}'
```
Teste permitido, o efeito gerado é semelhante.
```json theme={null}
{
"success": true,
"task_id": "9f58bbd4-855a-4233-ac45-b63bf9168e02",
"trace_id": "145ad117-6ce7-42dd-af12-70751c5284fc",
"data": [
{
"id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
"title": "Acordei com o sol nos meus olhos",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/38d3b9e2-0dfb-4338-b2a7-15e45656ed32.jpg",
"lyric": "[Verse]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verse 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Bridge]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é o suficiente\nA vida é bagunçada, mas é amor\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/38d3b9e2-0dfb-4338-b2a7-15e45656ed32.m4a",
"video_url": null,
"image_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
"topic": null,
"seed": "3789209121",
"sound": "",
"created_at": "2025-12-30T17:26:46.357055Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "153.80897959183673"
}
]
}
```
## Cantar músicas
Se você deseja realizar a operação de cantar uma música já gerada, pode inserir a música gerada acima para cantar, em seguida, precisamos personalizar a geração da música com base na letra e no título.
Se você deseja continuar cantando uma música que você enviou, pode definir o parâmetro `action` como `upload_cover` e inserir o ID da música que precisa continuar cantando. O ID da música pode ser obtido usando a [API de Upload do Produtor](https://api.xhuoapi.ai/documents/7fd2cb52-772e-4cc4-a018-e2626ff6f447), como mostrado na imagem abaixo:
Você pode especificar o seguinte conteúdo:
* action: A ação da tarefa da música, atualmente suportada: generate, cover, extend, upload\_cover, upload\_extend, replace\_section, swap\_vocals, swap\_instrumentals, variation, nesta reinterpretação usamos o parâmetro `cover`.
* lyric: Texto da letra
* title: Título da música.
* custom: Se deve usar o modo personalizado para gerar, o padrão é false.
* audio\_id: ID da música que precisa ser cantada.
Preenchimento de exemplo abaixo:
Preenchido, o código gerado é o seguinte:
Correspondente ao código:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "cover",
"model": "FUZZ-2.0 Pro",
"lyric": "[Verse]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verse 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Bridge]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é o suficiente\nA vida é bagunçada, mas é amor\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
"instrumental": false,
"custom": true,
"title": "Cover"
}'
```
Teste permitido, o efeito gerado é semelhante.
```json theme={null}
{
"success": true,
"task_id": "dbca350e-6fb9-46ca-9c7e-4c1a9080806f",
"trace_id": "a39e0fff-ced8-4b31-ae23-aef3badd90fa",
"data": [
{
"id": "e52dd729-38b4-4c2f-9031-59eb7953c593",
"title": "Capa",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/e52dd729-38b4-4c2f-9031-59eb7953c593.jpg",
"lyric": "[Verso]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nSapatos nos meus pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verso 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Ponte]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é suficiente\nA vida é bagunçada, mas é amor\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/e52dd729-38b4-4c2f-9031-59eb7953c593.m4a",
"video_url": null,
"image_id": "e52dd729-38b4-4c2f-9031-59eb7953c593",
"topic": null,
"seed": "358803418",
"sound": "",
"created_at": "2025-12-30T17:32:32.951948Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "153.0659410430839"
}
]
}
```
## Continuar a música
Se você quiser continuar a música, precisamos passar o valor do parâmetro `action` como: `extend`, em seguida, devemos personalizar a geração da música com base na letra, título e estilo.
Se você quiser continuar a música que enviou, pode definir o parâmetro `action` como `upload_extend` e inserir o ID da música que deseja continuar. O ID da música pode ser obtido usando a [API de Upload do Produtor](https://api.xhuoapi.ai/documents/7fd2cb52-772e-4cc4-a018-e2626ff6f447), conforme mostrado na imagem abaixo:
O exemplo de preenchimento é o seguinte:
Depois de preencher, o código gerado automaticamente é o seguinte:
O código correspondente:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "extend",
"model": "FUZZ-2.0 Pro",
"instrumental": false,
"lyric": "[Verso]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nSapatos nos meus pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verso 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Ponte]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é suficiente\nA vida é bagunçada, mas é amor\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"continue_at": 3,
"audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
"custom": true,
"title": "Estender",
"weirdness": 0.3,
"sound_strength": 0.3,
"lyrics_strength": 0.6
}'
```
Teste permitido, o efeito gerado é semelhante.
```json theme={null}
{
"success": true,
"task_id": "834983cb-d62d-4750-b1aa-461da137e51f",
"trace_id": "6923eee2-7403-432c-8bd1-e471086385b0",
"data": [
{
"id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
"title": "Estender",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/d9ebc609-fb65-4a23-b914-c074747af6a4.jpg",
"lyric": "[Verso]\n[Verso]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nSapatos nos meus pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verso 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Ponte]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é suficiente\nA vida é bagunçada, mas é amor\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/d9ebc609-fb65-4a23-b914-c074747af6a4.m4a",
"video_url": null,
"image_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
"topic": null,
"seed": "4294469624",
"sound": "",
"created_at": "2025-12-30T17:36:14.520928Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "173.87102040816328"
}
]
}
```
## Transformação musical
Se você quiser gerar uma nova música com efeito semelhante com base no valor de seed da música anterior, precisamos passar o valor do parâmetro `action` como: `variation`, em seguida, podemos personalizar a geração de uma nova música com efeito semelhante.
O exemplo de preenchimento é o seguinte:
填写完毕之后自动生成了代码如下：
对应的代码：
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "variation",
"audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
"model": "FUZZ-2.0 Pro",
"instrumental": false,
"lyric": "[Verse]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verse 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Bridge]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é o suficiente\nA vida é bagunçada, mas é amor\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"custom": true
}'
```
测试允许, 生成的效果 é semelhante.
```json theme={null}
{
"success": true,
"task_id": "3a74da6d-a37d-4b5d-b116-821f455bce39",
"trace_id": "8e28cce0-0400-4bfd-83db-6d27f97422c7",
"data": [
{
"id": "c14ca458-cd5a-4700-83d4-5249e15f2707",
"title": "Acordei com o sol nos meus olhos",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/c14ca458-cd5a-4700-83d4-5249e15f2707.jpg",
"lyric": "[Verse]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verse 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Bridge]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é o suficiente\nA vida é bagunçada, mas é amor\n[Chorus]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/c14ca458-cd5a-4700-83d4-5249e15f2707.m4a",
"video_url": null,
"image_id": "c14ca458-cd5a-4700-83d4-5249e15f2707",
"topic": null,
"seed": "2082104582",
"sound": "",
"created_at": "2025-12-30T17:48:40.135187Z",
"model": "FUZZ-2.0",
"progress": "100%",
"state": "succeeded",
"duration": "173.12798185941043"
}
]
}
```
## Substituir Seções
Se você quiser substituir seções da música, precisamos passar o valor do parâmetro `action` como: `replace_section`, em seguida, devemos personalizar a geração da música com base na letra e no título.
Se você quiser continuar substituindo seções de uma música que você enviou, pode definir o parâmetro `action` como `upload_replace_section` e inserir o ID da música que precisa ser continuada. O ID da música pode ser obtido usando a [Producer Upload API](https://api.xhuoapi.ai/documents/7fd2cb52-772e-4cc4-a018-e2626ff6f447), como mostrado na imagem abaixo:
Exemplo de preenchimento:
Preenchido, o código gerado automaticamente é o seguinte:
Correspondente ao código:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "replace_section",
"model": "FUZZ-2.0 Pro",
"instrumental": false,
"lyric": "[Verse]\\nAcordei com o sol nos meus olhos\\nSem nuvens acima, apenas azul no céu\\nCom os sapatos nos pés, estou pronto para correr\\nCada passo parece uma arma carregada\\n[Chorus]\\nDias felizes estão chegando\\nDeixe a alegria debaixo da minha pele\\nSem mais sombras, sem mais mentiras\\nApenas a verdade que me eleva\\n[Verse 2]\\nDançando pelas ruas da cidade\\nUm ritmo pulsando no meu coração\\nEstranhos sorriem, está pegando\\nEste mundo é um palco, todos somos uma canção\\n[Chorus]\\nDias felizes estão chegando\\nDeixe a alegria debaixo da minha pele\\nSem mais sombras, sem mais mentiras\\nApenas a verdade que me eleva\\n[Bridge]\\nJogue suas preocupações pela porta\\nDeixe-as afundar no fundo do oceano\\nEstamos vivos e isso é o suficiente\\nA vida é bagunçada, mas é amor\\n[Chorus]\\nDias felizes estão chegando\\nDeixe a alegria debaixo da minha pele\\nSem mais sombras, sem mais mentiras\\nApenas a verdade que me eleva",
"audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
"replace_section_start": 3,
"replace_section_end": 70,
"custom": true
}'
```
Teste permitido, o efeito gerado é semelhante.
```json theme={null}
{
"success": true,
"task_id": "3cb5ae96-01b0-4a37-afb0-e582608af56f",
"trace_id": "3ebc6f63-5093-4499-bf9b-95c239e0da4f",
"data": [
{
"id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f",
"title": "Acordei com o sol nos meus olhos",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/a54609c6-13e2-4176-be0f-4d7eebc68e1f.jpg",
"lyric": "[Verso]\\nAcordei com o sol nos meus olhos\\nSem nuvens acima, apenas azul no céu\\nSapatos nos meus pés, estou pronto para correr\\nCada passo parece uma arma carregada\\n[Refrão]\\nDias felizes estão chegando\\nDeixe a alegria debaixo da minha pele\\nSem mais sombras, sem mais mentiras\\nApenas a verdade que me eleva\\n[Verso 2]\\nDançando pelas ruas da cidade\\nUm ritmo pulsando no meu coração\\nEstranhos sorriem, está pegando\\nEste mundo é um palco, todos somos uma canção\\n[Refrão]\\nDias felizes estão chegando\\nDeixe a alegria debaixo da minha pele\\nSem mais sombras, sem mais mentiras\\nApenas a verdade que me eleva\\n[Ponte]\\nJogue suas preocupações pela porta\\nDeixe-as afundar no fundo do oceano\\nEstamos vivos e isso é suficiente\\nA vida é bagunçada, mas é amor\\n[Refrão]\\nDias felizes estão chegando\\nDeixe a alegria debaixo da minha pele\\nSem mais sombras, sem mais mentiras\\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/a54609c6-13e2-4176-be0f-4d7eebc68e1f.m4a",
"video_url": null,
"image_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f",
"topic": null,
"seed": "14887454",
"sound": "",
"created_at": "2025-12-30T18:01:19.907443Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "174.6140589569161"
}
]
}
```
## Versão de Acompanhamento
Se você deseja usar a operação de versão de acompanhamento oficial, pode definir o valor do parâmetro `action` como: `swap_instrumentals`, em seguida, precisamos personalizar a geração da música com base na letra e no título.
O exemplo de preenchimento é o seguinte:
Após o preenchimento, o código gerado automaticamente é o seguinte:
O código correspondente:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "swap_instrumentals",
"model": "FUZZ-2.0 Pro",
"weirdness": 0.6,
"prompt": "Feliz",
"audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4"
}'
```
Teste permitido, o efeito gerado é semelhante.
```json theme={null}
{
"success": true,
"task_id": "d17d8376-3a58-451d-a976-404719bac11d",
"trace_id": "ab596807-910a-4e30-bae2-4647895f7d0b",
"data": [
{
"id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b",
"title": "Estender (Troca de som)",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b.jpg",
"lyric": "[Verso]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nSapatos nos meus pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verso 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Ponte]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é suficiente\nA vida é bagunçada, mas é amor\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b.m4a",
"video_url": null,
"image_id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b",
"topic": null,
"seed": "2157878068",
"sound": "Feliz",
"created_at": "2025-12-30T18:09:49.594800Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "172.3849433106576"
}
]
}
```
## Versão de Voz
Se você deseja usar a operação de versão de voz oficial, pode definir o valor do parâmetro `action` como: `swap_vocals`, em seguida, precisamos personalizar a geração da música com base na letra, título e estilo.
O exemplo de preenchimento é o seguinte:
Após o preenchimento, o código gerado automaticamente é o seguinte:
O código correspondente:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "swap_vocals",
"model": "FUZZ-2.0 Pro",
"instrumental": false,
"lyric": "[Verso]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verso 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Ponte]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é o suficiente\nA vida é bagunçada, mas é amor\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"weirdness": 0.6,
"lyrics_strength": 0.8,
"audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
"custom": true
}'
```
测试允许，生成的效果是 semelhante.
```json theme={null}
{
"success": true,
"task_id": "a903ac38-f129-4f85-9181-b1dc5579bd32",
"trace_id": "9953af52-45e0-4808-bf13-88f0b21262c1",
"data": [
{
"id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b",
"title": "Acordei com o sol nos meus olhos",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/7b2d653b-aaaa-41b0-b737-aee4c4c5693b.jpg",
"lyric": "[Verso]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verso 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, está pegando\nEste mundo é um palco, todos somos uma canção\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Ponte]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é o suficiente\nA vida é bagunçada, mas é amor\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/7b2d653b-aaaa-41b0-b737-aee4c4c5693b.m4a",
"video_url": null,
"image_id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b",
"topic": null,
"seed": "2484735707",
"sound": "",
"created_at": "2025-12-30T18:13:01.349875Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "173.12798185941043"
}
]
}
```
## Separação de letras e música
Se você quiser usar a operação oficial de separação de letras e música, pode definir o valor do parâmetro `action` como: `stems`, em seguida, precisamos realizar a separação de letras e música com base no ID da música.
O exemplo de preenchimento é o seguinte:
Após o preenchimento, o código gerado automaticamente é o seguinte:
O código correspondente:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "stems",
"audio_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f"
}'
```
Teste permitido, o efeito gerado é semelhante.
```json theme={null}
{
"success": true,
"task_id": "561ac695-b4aa-47cf-978d-fb7be2b9ebfc",
"trace_id": "66d0d397-2987-4bde-84fb-a60d0023b217",
"data": [
{
"title": "Acordei com o sol nos meus olhos",
"lyric": "",
"stems_url": "https://platform.cdn.xhuoapi.ai/producer/561ac695-b4aa-47cf-978d-fb7be2b9ebfc.zip",
"model": "",
"progress": "100%",
"state": "succeeded"
}
]
}
```
## Callback assíncrono
Como a API de Geração de Áudios do Producer pode levar um tempo relativamente longo para gerar, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos.
O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo `callback_url` adicional. Após o cliente fazer a solicitação à API, a API retornará imediatamente um resultado, contendo um campo de informação `task_id`, representando o ID da tarefa atual. Quando a tarefa for concluída, o resultado da tarefa gerada será enviado para o `callback_url` especificado pelo cliente no formato JSON POST, que também incluirá o campo `task_id`, assim o resultado da tarefa pode ser associado pelo ID.
Vamos entender como operar isso através de um exemplo.
Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, os desenvolvedores devem substituir pela URL do servidor HTTP que construíram. Para facilitar a demonstração, usamos um site de exemplo de Webhook público [https://webhook.site/](https://webhook.site/), ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem:
Copie esta URL e você pode usá-la como Webhook, o exemplo aqui é [https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1](https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1).
Em seguida, podemos definir o campo `callback_url` como a URL do Webhook acima, ao mesmo tempo preenchendo os parâmetros correspondentes, o conteúdo específico é mostrado na imagem:
Clique em executar, e você verá que receberá imediatamente um resultado, como abaixo:
```
{
"task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad"
}
```
稍等片刻，我们可以在 [https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1](https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1) 上观察到生成任务的结果，如图所示：
内容如下：
```json theme={null}
{
"success": true,
"task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
"trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
"data": [
{
"id": "1dd08826-478e-43a6-868f-aff5ababac2c",
"title": "Acordei com o sol nos meus olhos",
"image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/3bff6223-fe13-4bef-973e-2cbaef430d5d/image/1dd08826-478e-43a6-868f-aff5ababac2c.jpg",
"lyric": "[Verso]\nAcordei com o sol nos meus olhos\nSem nuvens acima, apenas azul no céu\nCom os sapatos nos pés, estou pronto para correr\nCada passo parece uma arma carregada\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Verso 2]\nDançando pelas ruas da cidade\nUm ritmo pulsando no meu coração\nEstranhos sorriem, é contagiante\nEste mundo é um palco, todos somos uma canção\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva\n[Ponte]\nJogue suas preocupações pela porta\nDeixe-as afundar no fundo do oceano\nEstamos vivos e isso é suficiente\nA vida é bagunçada, mas é amor\n[Refrão]\nDias felizes estão chegando\nDeixe a alegria debaixo da minha pele\nSem mais sombras, sem mais mentiras\nApenas a verdade que me eleva",
"audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/3bff6223-fe13-4bef-973e-2cbaef430d5d/audio/1dd08826-478e-43a6-868f-aff5ababac2c.m4a",
"video_url": null,
"image_id": "1dd08826-478e-43a6-868f-aff5ababac2c",
"topic": null,
"seed": "1490770667",
"sound": "",
"created_at": "2025-12-30T18:36:00.994141Z",
"model": "FUZZ-2.0 Pro",
"progress": "100%",
"state": "succeeded",
"duration": "135.2330158730159"
}
]
}
```
可以看到结果中有一个 `task_id` 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。
## Erro de tratamento
Na chamada da API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondente. Por exemplo:
* `400 token_mismatched`：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `400 api_not_implemented`：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `401 invalid_token`：Não autorizado, token de autorização inválido ou ausente.
* `429 too_many_requests`：Muitas solicitações, você excedeu o limite de taxa.
* `500 api_error`：Erro interno do servidor, algo deu errado no servidor.
### Exemplo de resposta de erro
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "falha ao buscar"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusão
Através deste documento, você já entendeu como usar a API de Geração de Áudios do Produtor, que pode gerar música através da entrada de palavras-chave. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.