Saltar para o conteúdo principal
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: Página de Solicitação 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.acedata.cloud/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"
      }
    ]
  }
}
O resultado retornado contém vários campos, o campo request é o corpo da solicitação ao iniciar a tarefa, enquanto o campo response é o corpo da resposta retornada após a conclusão da tarefa. A descrição dos campos é a seguinte.
  • 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是包含了批量任务的具体详情信息，每个任务的具体信息与上文的字段一样，字段信息如下。
  • 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.acedata.cloud/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"
}

​
结论

通过本文档，您已经了解了如何使用 Fish Tasks API 进行查询单个或批量任务的所有具体详情信息。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。