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-s21pro-flash",
  "format": "mp3",
  "speed": 1,
  "volume": 0,
  "stability": 1,
  "similarity": 1,
  "pitch": 0,
  "language": "auto",
  "emotion": "neutral",
  "instruction": "Speak naturally",
  "textNormalization": true
}

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-s21pro-flash","format":"mp3"}'

Resposta

O endpoint retorna 202 Accepted. Salve task.id antes de iniciar a consulta.

{
  "task": {
    "id": "task_123",
    "status": "pending",
    "audioUrl": null,
    "delivery": { "downloadUrl": null, "downloadReady": false }
  },
  "record": { "id": "task_123", "status": "pending" },
  "requestId": "req_123",
  "quotaRemaining": 99994,
  "creditsUsed": 6
}

Conseguir emprego

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

Os valores de status são pending, processing, success, partial_fail e fail.

GET /api/open/tts/jobs/{taskId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEY

Os links task.segments[].playbackUrl exigem o mesmo cabeçalho. Não crie outro trabalho para recuperar um download.

Recuperar um ID de tarefa perdido

Se a solicitação de criação chegou ao servidor, mas o cliente não recebeu a resposta 202 Accepted, liste primeiro os trabalhos recentes:

curl "https://fishaudio.org/api/open/v1/speech/tts/jobs?limit=20&createdAfter=2026-07-20T00%3A00%3A00Z" \
  -H "Authorization: Bearer FISHAUDIO_API_KEY"

Os resultados são ordenados do mais recente para o mais antigo. Use createdAt, textFingerprint, voiceId e engineModelId para corresponder à solicitação local. São aceitos page, limit (máximo 100), status e createdAfter no formato ISO 8601. A lista retorna apenas uma prévia do texto, nunca o texto completo. Depois de recuperar taskId, continue consultando o trabalho existente. A listagem não consome quota de API.

Faturamento e créditos

O servidor reserva creditsUsed uma única vez quando aceita o trabalho. Consultar, baixar e baixar novamente o mesmo áudio não causa nova cobrança. Um trabalho pré-pago que falha é reembolsado por um caminho idempotente.

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