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

# Fish Tasks API の接続と使用

> Fish music generation 集成指南 - XHuoAPI

Fish Tasks API の主な機能は、Fish Audios Generation API によって生成されたタスクIDを入力することで、そのタスクの実行状況を照会することです。

この記事では、Fish Tasks API の接続説明を詳しく紹介し、簡単に統合し、この API の強力な機能を十分に活用できるようにします。Fish Tasks API を使用することで、Fish Audios Generation API のタスク実行状況を簡単に照会できます。

## 申請プロセス

Fish Tasks API を使用するには、まず申請ページ [Fish Audios Generation API](https://api.xhuoapi.ai/documents/e681b715-54fd-4464-a59a-d7f14500e095) にアクセスして、該当するサービスを申請し、その後、Fish Audios Generation API のタスクIDをコピーします。以下の図のように：

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

最後に、Tasks API ページ [Fish Tasks API](https://api.xhuoapi.ai/documents/44c93949-1419-4a45-8db5-8a8335de7151) にアクセスして、該当するサービスを申請します。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

![申請ページ](https://cdn.xhuoapi.ai/rci31i.png)

まだログインまたは登録していない場合は、自動的に[ログインページ](https://api.xhuoapi.ai)にリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。

初回申請時には無料のクレジットが付与され、この API を無料で使用できます。

## リクエスト例

Fish Tasks API は、Fish Audios Generation API の結果を照会するために使用できます。Fish Audios Generation API の使用方法については、ドキュメント [Fish Videos Generation API](https://api.xhuoapi.ai/documents/fish-audios-integration) を参照してください。

Fish Audios Generation API サービスから返されたタスクIDを例に、どのようにこの API を使用するかを示します。仮にタスクIDが：2725a2d3-f87e-4905-9c53-9988d5a7b2f5 だとします。次に、タスクIDを渡す方法を示します。

### タスク例の図

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

### リクエストヘッダーとリクエストボディの設定

**Request Headers** には以下が含まれます：

* `accept`：JSON形式のレスポンス結果を受け取ることを指定します。ここには `application/json` を記入します。
* `authorization`：APIを呼び出すためのキーで、申請後に直接ドロップダウンから選択できます。

**Request Body** には以下が含まれます：

* `id`：アップロードされたタスクID。
* `action`：タスクの操作方法。

設定は以下の図のようになります：

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

### コード例

ページの右側には、さまざまな言語のコードが自動生成されていることがわかります。以下の図のように：

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

一部のコード例は以下の通りです：

#### 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"
}'
```

### レスポンス例

リクエストが成功すると、API はこのタスクの詳細情報を返します。例えば：

```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"
      }
    ]
  }
}
```

返された結果には複数のフィールドがあり、request フィールドはタスクを開始したときの request body です。また、response フィールドはタスク完了後に返される response body です。フィールドの説明は以下の通りです。

* `id`：このタスクを生成するための ID で、今回の生成タスクを一意に識別します。
* `request`：タスク内のリクエスト情報を照会します。
* `response`：タスク内の返却情報を照会します。

## バッチ照会操作

これは複数のタスクIDに対してタスクの詳細を照会するもので、上記とは異なり、action を retrieve\_batch に設定する必要があります。

**Request Body** には以下が含まれます：

* `ids`：アップロードされたタスクIDの配列。
* `action`：タスクの操作方法。

設定は以下の図のようになります：

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

### コード例

ページの右側には、さまざまな言語のコードが自動生成されていることがわかります。以下の図のように：

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

一部のコード例は以下の通りです：

### レスポンス例

リクエストが成功すると、API は今回のすべてのバッチタスクの具体的な詳細情報を返します。例えば：

```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": "スピーチ",
        "prompt": "白いシャム猫",
        "model": "fish-tts",
        "voice_id": "d7900c21663f485ab63ebdb7e5905036",
        "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
      },
      "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
      "type": "オーディオ",
      "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": "スピーチ",
        "prompt": "白いシャム猫",
        "model": "fish-tts",
        "voice_id": "d7900c21663f485ab63ebdb7e5905036",
        "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
      },
      "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
      "type": "オーディオ",
      "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`、バッチタスクのすべての具体的な詳細情報。これは配列であり、各配列の要素は上記の単一タスクの返却結果の形式と同じです。
* `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`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。
* `401 invalid_token`：認証されていない、無効または不足している認証トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "取得に失敗しました"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、Fish Tasks APIを使用して単一またはバッチタスクのすべての具体的な詳細情報を照会する方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。