Trabalhos assíncronos

Use trabalhos assíncronos TTS para texto longo, geração de lotes, fluxos de trabalho no estilo webhook e fluxos de UI onde os usuários podem sair da página enquanto o áudio ainda está sendo processado.

Criar trabalho

POST /api/open/v1/speech/tts/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json

Solicitar

{
  "text": "Hello from Fish Audio.",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s2pro",
  "format": "mp3"
}

Persista o hash de texto, a voz solicitada e o ID da tarefa retornado em seu banco de dados. Se o seu trabalhador travar após a criação, a pesquisa por ID de tarefa é mais segura do que criar um segundo trabalho.

O exemplo usa a voz de teste do sistema público 00a1b221-6137-4b73-ad62-b0cbce134167. Substitua-o pelo seu Voice ID preferido após verificar a conexão.

curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
  -H "Authorization: Bearer FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Fish Audio.","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s2pro","format":"mp3"}'

Resposta

O endpoint create retorna 202 Accepted com um objeto de tarefa. Os campos exatos da tarefa podem evoluir, mas os clientes devem pelo menos armazenar o ID e o status.

{
  "id": "task_123",
  "status": "queued"
}

Conseguir emprego

GET /api/open/v1/speech/tts/jobs/{taskId}
Authorization: Bearer FISHAUDIO_API_KEY

As tarefas bem-sucedidas incluem audioUrl quando um URL de áudio de curta duração pode ser gerado. As tarefas com falha incluem um código ou mensagem de erro. Trate queued e processing como estados não terminais e pesquise com espera.

Faturamento e créditos

Os trabalhos assíncronos podem reservar ou consumir créditos durante a criação ou conclusão da tarefa, dependendo do modelo habilitado. Não crie trabalhos duplicados como estratégia de nova tentativa, a menos que o usuário solicite explicitamente uma segunda saída. Armazene o ID da tarefa e recupere-o.

Para um lote, limite a simultaneidade do seu lado e verifique Perfil antes de adicionar um grande número de tarefas. Se uma tarefa falhar por créditos insuficientes, pause o rest do lote até que o proprietário da conta resolva o saldo.

Erros