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

# Hailuo Tasks API の接続と使用

> Hailuo Video Generation 集成指南 - XHuoAPI

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

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

## 申請プロセス

Hailuo Tasks API を使用するには、まず申請ページ [Hailuo Videos Generation API](https://api.xhuoapi.ai/documents/ee06377b-9185-438f-ac84-3376bcb1275e) にアクセスして、該当するサービスを申請し、その後、Hailuo Videos Generation API のタスクIDをコピーします。以下の図のように：

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

最後に、Tasks API ページ [Hailuo Tasks API](https://api.xhuoapi.ai/documents/4b1ccdbc-b8ed-4171-9a14-48e10970ba04) にアクセスして、該当するサービスを申請します。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

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

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

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

## リクエスト例

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

Hailuo Videos Generation API サービスから返されたタスクIDを例に、どのようにこの API を使用するかを示します。タスクID：58cc618b-9639-4ee7-add2-d2fcf260d9a3 があると仮定し、次にタスクIDを渡す方法を示します。

### タスク例の図

<p>
  <img src="https://cdn.xhuoapi.ai/4f9d95.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/e9btl5.png" width="500" className="m-auto" />
</p>

### コード例

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

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

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

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/hailuo/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3",
  "action": "retrieve"
}'
```

#### Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/hailuo/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

### レスポンス例

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

```json theme={null}
{
  "_id": "67866dff550a4144a5867aa7",
  "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3",
  "api_id": "d5af91f6-a7ec-4015-b0a5-d25051158470",
  "application_id": "2f9f4d93-9193-4c49-a1a5-eddf0ff38abb",
  "created_at": 1736863231.588,
  "credential_id": "f634e655-012e-432e-92a8-a87e4a80d636",
  "request": {
    "action": "generate",
    "prompt": "Internal heat"
  },
  "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3",
    "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190",
    "data": [
      {
        "id": "2a1tbgnjdxrg80cmcmes19s33r",
        "model": "minimax-t2v",
        "prompt": "Internal heat",
        "first_image_url": null,
        "video_url": "https://file.aigpai.com/czjl/tjU3QYKgU96IJFgpL0eMfBFhmy0qXz9Y05P2IBhShCYaDCFUA/tmp5uligw3a.output.mp4",
        "state": "succeeded"
      }
    ]
  }
}
```

返された結果には複数のフィールドがあり、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/i023y9.png" width="500" className="m-auto" />
</p>

### コード例

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

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

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

### レスポンス例

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

```json theme={null}
{
  "items": [
    {
      "_id": "67866fad550a4144a587053c",
      "id": "09d4a93e-d5c8-4778-bdf2-711773d71c59",
      "api_id": "d5af91f6-a7ec-4015-b0a5-d25051158470",
      "application_id": "2f9f4d93-9193-4c49-a1a5-eddf0ff38abb",
      "created_at": 1736863661.511,
      "credential_id": "f634e655-012e-432e-92a8-a87e4a80d636",
      "request": {
        "action": "generate",
        "prompt": "内部熱"
      },
      "trace_id": "0edc94c6-4938-4bff-bb16-20364c254e40",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "09d4a93e-d5c8-4778-bdf2-711773d71c59",
        "trace_id": "0edc94c6-4938-4bff-bb16-20364c254e40",
        "data": [
          {
            "id": "24zdgea0s1rge0cmcmjbsfj2m8",
            "model": "minimax-t2v",
            "prompt": "内部熱",
            "first_image_url": null,
            "video_url": "https://file.aigpai.com/czjl/6cTYBRBDVJIQANzG7GaPwPblbeIiFe4yUDcVoMkkXttqJCFUA/tmpm4ke45c5.output.mp4",
            "state": "成功"
          }
        ]
      }
    },
    {
      "_id": "67866dff550a4144a5867aa7",
      "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3",
      "api_id": "d5af91f6-a7ec-4015-b0a5-d25051158470",
      "application_id": "2f9f4d93-9193-4c49-a1a5-eddf0ff38abb",
      "created_at": 1736863231.588,
      "credential_id": "f634e655-012e-432e-92a8-a87e4a80d636",
      "request": {
        "action": "generate",
        "prompt": "内部熱"
      },
      "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3",
        "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190",
        "data": [
          {
            "id": "2a1tbgnjdxrg80cmcmes19s33r",
            "model": "minimax-t2v",
            "prompt": "内部熱",
            "first_image_url": null,
            "video_url": "https://file.aigpai.com/czjl/tjU3QYKgU96IJFgpL0eMfBFhmy0qXz9Y05P2IBhShCYaDCFUA/tmp5uligw3a.output.mp4",
            "state": "成功"
          }
        ]
      }
    }
  ],
  "count": 2
}
```

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/hailuo/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["09d4a93e-d5c8-4778-bdf2-711773d71c59","58cc618b-9639-4ee7-add2-d2fcf260d9a3"],
  "action": "retrieve_batch"
}'
```

#### Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/hailuo/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "ids": ["09d4a93e-d5c8-4778-bdf2-711773d71c59","58cc618b-9639-4ee7-add2-d2fcf260d9a3"],
    "action": "retrieve_batch"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## エラーハンドリング

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

## 結論

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