> ## 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.
# Hailuo Videos Generation API 接続説明
> Hailuo Video Generation API guide - Ace Data Cloud
本文では、Hailuo Videos Generation API の接続説明を紹介します。これは、カスタムパラメータを入力することで Hailuo の公式動画を生成できるものです。
## 申請プロセス
Hailuo Videos Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして API トークンを取得し、保管してください。
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。
**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。
> 📘 完全なドキュメント：[Hailuo Videos Generation API →](https://platform.acedata.cloud/documents/hailuo-videos-integration)
## 基本使用
まず、基本的な使用方法を理解します。これは、プロンプト `prompt`、生成アクション `action`、初フレーム参照画像 `first_image_url`、およびモデル `model` を入力することで処理された結果を得ることができます。最初に、`action` フィールドを単純に渡す必要があり、その値は `generate` です。次に、モデルを入力する必要があります。現在、主に画像から動画を生成するモデル `minimax-i2v` とテキストから動画を生成するモデル `minimax-t2v` の2つがあります。具体的な内容は以下の通りです：
ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：
* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
また、リクエストボディを設定しています。これには以下が含まれます：
* `model`：動画を生成するモデル。主に画像から動画を生成するモデル `minimax-i2v` とテキストから動画を生成するモデル `minimax-t2v` の2種類があります。
* `action`：今回の動画生成タスクのアクション。
* `first_image_url`：画像から動画を生成するモデル `minimax-i2v` を選択した場合に必ずアップロードする必要がある初フレーム参照画像のリンク。Base64 コードはサポートされていません。
* `prompt`：プロンプト。
* `callback_url`：結果をコールバックするための URL。
* `async`：オプション。`true` に設定すると、インターフェースはすぐに `task_id` を返し、`callback_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://platform.cdn.acedata.cloud/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.acedata.cloud/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": "内部熱",
"video_url": "https://platform.cdn.acedata.cloud/czjl/YPaUz2DcwpJqItTXAG9XHAoEoj3dbF0XPU69LT5nefCMzBFUA/tmp8s_59jez.output.mp4",
"state": "成功"
}
]
}
```
結果には `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": "取得に失敗しました"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 結論
この文書を通じて、Hailuo Videos Generation APIを使用して、入力プロンプトと最初のフレームの参照画像を通じて動画を生成する方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.