Saltar para o conteúdo principal

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.

Este documento irá apresentar uma descrição da integração da Fish Audios Generation API, que pode clonar sua própria voz através da entrada de palavras-chave.

​
Processo de Solicitação

Para usar a API, você precisa primeiro acessar a página correspondente da Fish Audios Generation API para solicitar o serviço correspondente. Após entrar na página, clique no botão “Acquire”, como 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

Primeiro, entenda a forma básica de uso, que é inserir a palavra-chave prompt, a ação de clonagem action, o ID da voz voice_id e o modelo model, para obter o resultado processado. Primeiro, você precisa passar um campo action, cujo valor é generate, e depois precisamos inserir o modelo model, que atualmente é principalmente o modelo fish-tts, com os detalhes a seguir:

Podemos ver que aqui configuramos os Request Headers, 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, configuramos o Request Body, incluindo:
  • model: o modelo para clonar a voz, principalmente o modelo fish-tts.
  • action: a ação da tarefa de clonagem de voz.
  • prompt: a palavra-chave a ser clonada.
  • voice_id: o ID da voz a ser clonada.
  • callback_url: a URL para onde o resultado deve ser enviado.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e aqui obtivemos o seguinte resultado: 
{
  "success": true,
  "task_id": "5872ab00-3cf4-4040-a798-8510aaa16756",
  "trace_id": "5eda3694-448a-4b72-af33-2acb3851ffe1",
  "data": [
    {
      "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
    }
  ]
}
O resultado retornado contém vários campos, descritos a seguir:
  • success, o estado da tarefa de clonagem de voz.
    • data, o resultado da tarefa de clonagem de voz
      • audio_url, o link do áudio da tarefa de clonagem de voz.
Podemos ver que obtivemos informações de voz satisfatórias, e tudo o que precisamos fazer é acessar o link de áudio no data para obter a voz clonada. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, como o código CURL abaixo: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "speech",
  "prompt": "a white siamese cat",
  "model": "fish-tts",
  "voice_id": "d7900c21663f485ab63ebdb7e5905036"
}'

​
Callback Assíncrono

Como o tempo de geração da Fish Audios Generation API é relativamente longo, cerca de 1-2 minutos, 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 task_id, que representa 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 em formato JSON POST, incluindo também o campo task_id, permitindo que o resultado da tarefa seja 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, e o desenvolvedor deve substituí-lo pela URL do servidor HTTP que ele configurou. Para facilitar a demonstração, usaremos um site de exemplo de Webhook público https://webhook.site/, ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem: Copie esta URL para usá-la como Webhook, o exemplo aqui é https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34. Em seguida, podemos definir o campo callback_url como a URL do Webhook acima, ao mesmo tempo em que inserimos os parâmetros correspondentes, conforme mostrado na imagem:

Clique em executar e você verá que receberá imediatamente um resultado, como abaixo: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5"
}
Após alguns instantes, podemos observar o resultado da tarefa gerada em https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34, como mostrado na imagem: O conteúdo é o seguinte: 
{
    "success": true,
    "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
    "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
    "data": [
        {
            "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
        }
    ]
}
Podemos ver que o resultado contém um campo task_id, e os outros campos são semelhantes aos mencionados anteriormente, permitindo que a tarefa seja associada através desse campo.

​
Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. 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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusão

Através deste documento, você já entendeu como usar a API de Geração de Áudio Fish para clonar vozes 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, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.