> ## 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.

# Integração e Uso da API Fish Tasks

> Fish music generation 集成指南 - XHuoAPI

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](https://api.xhuoapi.ai/documents/e681b715-54fd-4464-a59a-d7f14500e095) para solicitar o serviço correspondente, e então copiar o ID da tarefa da API Fish Audios Generation, como mostrado na imagem:

<p>
  <img src="https://cdn.xhuoapi.ai/jxvue8.png" width="500" className="m-auto" />
</p>

Por fim, acesse a página da API Tasks [API Fish Tasks](https://api.xhuoapi.ai/documents/44c93949-1419-4a45-8db5-8a8335de7151) 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](https://cdn.xhuoapi.ai/rci31i.png)

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a [página de login](https://api.xhuoapi.ai) 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](https://api.xhuoapi.ai/documents/fish-audios-integration).

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

<p>
  <img src="https://cdn.xhuoapi.ai/jxvue8.png" width="500" className="m-auto" />
</p>

### 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:

<p>
  <img src="https://cdn.xhuoapi.ai/xc5ejq.png" width="500" className="m-auto" />
</p>

### 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:

<p>
  <img src="https://cdn.xhuoapi.ai/851zv2.png" width="500" className="m-auto" />
</p>

Alguns exemplos de código são os seguintes:

#### CURL

```bash theme={null}
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:

```json theme={null}
{
  "_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:

<p>
  <img src="https://cdn.xhuoapi.ai/64lid9.png" width="500" className="m-auto" />
</p>

### 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:

<p>
  <img src="https://cdn.xhuoapi.ai/ezkzmw.png" width="500" className="m-auto" />
</p>

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:

```json theme={null}
{
  "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

```bash theme={null}
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.

### 错误响应示例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha na busca"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 结论

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