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.
A principal função da API Fish Tasks é consultar o status de execução de tarefas através do ID da tarefa gerado pela API Fish Audios Generation.
Este documento irá detalhar as instruções de integração da API Fish Tasks, ajudando você a integrar facilmente e aproveitar ao máximo as poderosas funcionalidades dessa API. Com a API Fish Tasks, você pode consultar facilmente o status de execução das tarefas da API Fish Audios Generation.
Processo de Solicitação
Para usar a API Fish Tasks, você precisa primeiro ir à página de solicitação API Fish Audios Generation para solicitar o serviço correspondente, e então copiar o ID da tarefa da API Fish Audios Generation, como mostrado na imagem:
Por fim, acesse a página da API Tasks API Fish Tasks 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 que o convida a se registrar e fazer login. Após o registro e login, você será redirecionado automaticamente de volta para a página atual.
Na primeira solicitação, haverá um crédito gratuito disponível, permitindo que você use essa API gratuitamente.
Exemplo de Solicitação
A API Fish Tasks pode ser usada para consultar os resultados da API Fish Audios Generation. Para saber como usar a API Fish Audios Generation, consulte o documento API Fish Videos Generation.
Usaremos um exemplo de ID de tarefa retornado pelo serviço da API Fish Audios Generation. Suponha que temos um ID de tarefa: 2725a2d3-f87e-4905-9c53-9988d5a7b2f5, a seguir, demonstraremos como passar um ID de tarefa.
Exemplo de Tarefa
Configurando Cabeçalhos e Corpo da Solicitação
Cabeçalhos da Solicitação incluem:
accept: especifica que a resposta deve estar no formato JSON, preenchido como application/json.authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Corpo da Solicitação inclui:
id: o ID da tarefa enviada.action: a forma de operação sobre a tarefa.
Configuração conforme mostrado na imagem abaixo:
Exemplo de Código
Pode-se notar que, no lado direito da página, já foram gerados automaticamente códigos em várias linguagens, como mostrado na imagem:
Alguns exemplos de código são os seguintes:
CURL
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"action": "retrieve"
}'
Exemplo de Resposta
Após uma solicitação bem-sucedida, a API retornará as informações detalhadas da tarefa aqui. Por exemplo:
{
"_id": "68cfad98550a4144a5476a92",
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
"application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
"created_at": 1758440856.34,
"credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
"request": {
"action": "speech",
"prompt": "a white siamese cat",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036",
"callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
},
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"type": "audios",
"user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
"response": {
"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"
}
]
}
}
id, o ID que gerou esta tarefa, usado para identificar exclusivamente esta tarefa gerada.request, informações da solicitação na consulta da tarefa.response, informações da resposta na consulta da tarefa.
Operação de Consulta em Lote
Esta operação é para consultar detalhes de várias IDs de tarefa, diferindo do acima, onde a ação deve ser selecionada como retrieve_batch.
Corpo da Solicitação inclui:
ids: um array de IDs de tarefa enviados.action: a forma de operação sobre a tarefa.
Configuração conforme mostrado na imagem abaixo:
Exemplo de Código
Pode-se notar que, no lado direito da página, já foram gerados automaticamente códigos em várias linguagens, como mostrado na imagem:
Alguns exemplos de código são os seguintes:
Exemplo de Resposta
Após uma solicitação bem-sucedida, a API retornará as informações detalhadas de todas as tarefas em lote. Por exemplo:
{
"items": [
{
"_id": "68cfad98550a4144a5476a92",
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
"application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
"created_at": 1758440856.34,
"credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
"request": {
"action": "fala",
"prompt": "um gato siames branco",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036",
"callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
},
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"type": "audios",
"user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
"response": {
"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"
}
]
}
},
{
"_id": "68cfad98550a4144a5476a92",
"id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
"application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
"created_at": 1758440856.34,
"credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
"request": {
"action": "fala",
"prompt": "um gato siames branco",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036",
"callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
},
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"type": "audios",
"user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
"response": {
"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"
}
]
}
}
],
"count": 2
}
items，批量任务的所有具体详情信息。Ele é um array, cada elemento do array tem o mesmo formato do resultado de consulta de uma única tarefa acima.count，此处批量查询任务的个数。
CURL
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"ids": ["2725a2d3-f87e-4905-9c53-9988d5a7b2f5","2725a2d3-f87e-4905-9c53-9988d5a7b2f5"],
"action": "retrieve_batch"
}'
错误处理
在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
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.
错误响应示例
{
"success": false,
"error": {
"code": "api_error",
"message": "falha na busca"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
