> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish Tasks API の連携と使用

> Fish voice generation API guide - Ace Data Cloud

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

本ドキュメントでは、Fish Tasks API の連携に関する説明を詳しく紹介し、この API の強力な機能を簡単に統合して最大限に活用できるよう支援します。Fish Tasks API を通じて、Fish Audios Generation API のタスク実行状況を簡単に照会できます。

## 申請プロセス

Fish Audios Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを促されます。完了後、自動的に現在のページへ戻ります。

**1つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、サービスごとに個別に申請する必要はありません。** 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。

> 📘 完全なドキュメント：[Fish Audios Generation API →](https://platform.acedata.cloud/documents/fish-tts)

## リクエスト例

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

Fish Audios Generation API サービスが返す1つのタスクIDを例として、この API の使用方法を説明します。タスクID：2725a2d3-f87e-4905-9c53-9988d5a7b2f5 があると仮定し、次に1つのタスクIDを渡す方法を説明します。

### タスク例の図

<p>
  <img src="https://cdn.acedata.cloud/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.acedata.cloud/xc5ejq.png" width="500" className="m-auto" />
</p>

### コード例

ページ右側には、すでに各種言語のコードが自動生成されていることが確認できます。図のとおりです：

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

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

#### CURL

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

### レスポンス例

リクエストが成功すると、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,
  "started_at": 1758440856.4,
  "finished_at": 1758440869.2,
  "elapsed": 12.8,
  "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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
      }
    ]
  }
}
```

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

* `id`、このタスクを生成した ID。この生成タスクを一意に識別するために使用されます。
* `request`、タスク照会におけるリクエスト情報。
* `response`、タスク照会における返却情報。最終的に成功した際、その中の `cost.amount` は今回の合成で実際に差し引かれた Credits です。
* `created_at`、タスク作成時刻。Unix タイムスタンプ（秒、浮動小数点）。
* `started_at`、タスク実行開始時刻。Unix タイムスタンプ（秒、浮動小数点）。
* `finished_at`、タスク完了時刻。Unix タイムスタンプ（秒、浮動小数点）。タスクが未完了の場合、このフィールドは返されません。
* `elapsed`、タスク実行時間。単位は秒（浮動小数点、小数点以下 3 桁を保持）。タスクが未完了の場合、このフィールドは返されません。

## 一括照会操作

これは複数のタスクIDを対象にタスク詳細を照会するものです。上記と異なる点は、action で retrieve\_batch を選択する必要があることです。

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

* `ids`：アップロードしたタスクIDの配列。
* `action`：タスクに対する操作方法。

設定は以下の図のとおりです：

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

### コード例

ページ右側には、すでに各種言語のコードが自動生成されていることが確認できます。図のとおりです：

<p>
  <img src="https://cdn.acedata.cloud/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,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.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,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
          }
        ]
      }
    }
  ],
  "count": 2
}
```

返却結果には複数のフィールドがあり、そのうちitemsにはバッチタスクの具体的な詳細情報が含まれています。各タスクの具体的な情報は上記のフィールドと同じであり、フィールド情報は以下のとおりです。

* `items`、バッチタスクのすべての具体的な詳細情報です。これは配列であり、各配列要素の形式は上記の単一タスク照会の返却結果と同じです。
* `count`、ここでバッチ照会するタスクの件数です。

#### CURL

```bash theme={null}
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`：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。
* `400 api_not_implemented`：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。
* `401 invalid_token`：未認証。認証トークンが無効または不足しています。
* `429 too_many_requests`：リクエストが多すぎます。レート制限を超過しています。
* `500 api_error`：内部サーバーエラー。サーバーで問題が発生しました。

### エラー応答の例

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

## 結論

本ドキュメントを通じて、Fish Tasks API を使用して単一またはバッチタスクのすべての具体的な詳細情報を照会する方法をご理解いただけました。本ドキュメントが、この API をより適切に連携・使用するためのお役に立てば幸いです。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.