> ## 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 Videos Generation API 接続説明
> Hailuo Video Generation 集成指南 - XHuoAPI
本文では、Hailuo Videos Generation API 接続説明を紹介します。これは、カスタムパラメータを入力することで Hailuo の公式動画を生成できるものです。
## 申請プロセス
API を使用するには、まず [Hailuo Videos Generation API](https://api.xhuoapi.ai/documents/ee06377b-9185-438f-ac84-3376bcb1275e) の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。
初回申請時には無料のクレジットが付与され、この API を無料で使用できます。
## 基本使用
まず、基本的な使用方法を理解します。これは、プロンプト `prompt`、生成アクション `action`、初フレーム参照画像 `first_image_url`、およびモデル `model` を入力することで処理された結果を得ることができます。まず、シンプルに `action` フィールドを渡す必要があります。その値は `generate` です。次に、モデルを入力する必要があります。現在、主に画像から動画を生成するモデル `minimax-i2v` とテキストから動画を生成するモデル `minimax-t2v` があります。具体的な内容は以下の通りです：
ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：
* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
また、リクエストボディを設定しています。これには以下が含まれます：
* `model`：動画を生成するモデル。主に画像から動画を生成するモデル `minimax-i2v` とテキストから動画を生成するモデル `minimax-t2v` の2種類があります。
* `action`：今回の動画生成タスクのアクション。
* `first_image_url`：画像から動画モデル `minimax-i2v` を選択した場合に必ずアップロードする必要がある初フレーム参照画像のリンク。Base64 コードはサポートされていません。
* `prompt`：プロンプト。
* `callback_url`：結果をコールバックする URL。
選択後、右側にも対応するコードが生成されていることがわかります。以下の図のように：
「Try」ボタンをクリックするとテストができます。上の図のように、以下の結果を得ました：
```json theme={null}
{
"success": true,
"task_id": "baf1034c-684c-46be-ae6d-89ebb89b690d",
"trace_id": "3221eb74-1a25-447a-ba69-7d9b310e306c",
"data": [
{
"id": "0pv8yhe4fdrge0cmckpv23pd2g",
"model": "minimax-t2v",
"prompt": "Internal heat",
"video_url": "https://file.aigpai.com/czjl/qoueLWBokF3ud6tdVD6VJTZuXTnK5HaMO2qAOS46Ef8VSBFUA/tmp9e3u11c1.output.mp4",
"state": "succeeded"
}
]
}
```
返された結果には複数のフィールドがあり、以下のように説明されます：
* `success`：この時点での動画生成タスクの状態。
* `task_id`：この時点での動画生成タスク ID。
* `trace_id`：この時点での動画生成トレース ID。
* `data`：この時点での動画生成タスクの結果リスト。
* `id`：この時点での動画生成タスクの動画 ID。
* `prompt`：この時点での動画生成タスクのプロンプト。
* `model`：この時点での動画生成タスクのモデルリンク。
* `video_url`：この時点での動画生成タスクの動画リンク。
* `state`：この時点での動画生成タスクの状態。
満足のいく動画情報を得られたことがわかります。結果の `data` の動画リンクアドレスに基づいて生成された Hailuo 動画を取得するだけです。
また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURL のコードは以下の通りです：
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/hailuo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"prompt": "Internal heat"
}'
```
## 非同期コールバック
Hailuo Videos Generation API で生成される時間は比較的長く、約 1-2 分かかります。API が長時間応答しない場合、HTTP リクエストは接続を維持し続け、追加のシステムリソースを消費するため、本 API では非同期コールバックのサポートも提供しています。
全体の流れは次の通りです：クライアントがリクエストを発起する際に、追加で `callback_url` フィールドを指定します。クライアントが API リクエストを発起した後、API はすぐに結果を返し、現在のタスク ID を示す `task_id` フィールド情報を含みます。タスクが完了すると、生成された動画の結果が POST JSON 形式でクライアントが指定した `callback_url` に送信され、その中にも `task_id` フィールドが含まれます。これにより、タスク結果を ID で関連付けることができます。
以下の例を通じて、具体的にどのように操作するかを理解しましょう。
まず、Webhook コールバックは HTTP リクエストを受け取ることができるサービスであり、開発者は自分が構築した HTTP サーバーの URL に置き換える必要があります。ここでは、デモのために公開された Webhook サンプルサイト [https://webhook.site/](https://webhook.site/) を使用します。このサイトを開くと、Webhook URL を得ることができます。以下の図のように：
この URL をコピーすれば、Webhook として使用できます。このサンプルは `https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83` です。
次に、フィールド `callback_url` を上記の Webhook URL に設定し、相応のパラメータを入力します。具体的な内容は以下の図のように：
実行をクリックすると、すぐに結果が得られます。以下のように：
```
{
"task_id": "05aff65c-5e84-442b-8e29-3a5d27130840"
}
```
少し待つと、`https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83` で生成された動画の結果を観察できます。以下の図のように：
内容は以下の通りです：
```json theme={null}
{
"success": true,
"task_id": "05aff65c-5e84-442b-8e29-3a5d27130840",
"trace_id": "b9856b8a-725d-45c9-befe-e789d9fd9ffb",
"data": [
{
"id": "t80jhsf96srg80cmcm6b0rk8gm",
"model": "minimax-t2v",
"prompt": "Internal heat",
"video_url": "https://file.aigpai.com/czjl/YPaUz2DcwpJqItTXAG9XHAoEoj3dbF0XPU69LT5nefCMzBFUA/tmp8s_59jez.output.mp4",
"state": "succeeded"
}
]
}
```
結果には `task_id` フィールドがあり、他のフィールドは上記と似ています。このフィールドを通じてタスクの関連付けが可能です。
## エラーハンドリング
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"
}
```
## 結論
この文書を通じて、Hailuo Videos Generation APIを使用して、入力プロンプトと最初のフレームの参照画像を通じて動画を生成する方法を理解しました。この文書が、APIの接続と使用をより良くする手助けとなることを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。