> ## 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.
# Kling Motion Generation API 連携ガイド
> Kling video generation API guide - Ace Data Cloud
本文では、カスタムパラメータを入力することでKling公式の動画を生成できる Kling Motion Generation API の連携方法を紹介します。
## 申請手順
Kling Motion Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。
まだログインまたは登録していない場合は、自動的にログインページへ移動し、登録とログインが案内されます。完了後、自動的に現在のページへ戻ります。
**1つの API Token でプラットフォーム上のすべてのサービスを呼び出すことができ、サービスごとに個別で申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。
> 📘 完全なドキュメント：[Kling Motion Generation API →](https://platform.acedata.cloud/documents/kling-motion)
## 基本的な使用方法
まず基本的な使用方法を理解しましょう。プロンプト `prompt`、参照画像 `image_url`、および参照動画リンク `video_url` を入力すると、処理後の結果を取得できます。さらにモデル `mode` を入力する必要があり、現在は主に `std`、`pro` モデルがあります。具体的な内容は以下のとおりです：
ここでは Request Headers を設定しており、以下が含まれます：
* `accept`：受け取りたいレスポンス結果の形式です。ここでは `application/json`、つまり JSON 形式を指定します。
* `authorization`：API を呼び出すためのキーです。申請後、直接プルダウンから選択できます。
さらに Request Body を設定しており、以下が含まれます：
* `image_url`：人物の外観参照画像 URL。JPG/JPEG/PNG に対応し、ファイルは 50MB 以下、幅と高さはいずれも 300px 以上、アスペクト比は 1:2.5～2.5:1。人物は上半身または全身と頭部が明確に表示されている必要があります。
* `video_url`：動作参照動画 URL。MP4/MOV に対応し、ファイルは 100MB 以下、幅と高さは各 340～3850px、少なくとも 3 秒。`character_orientation=image` の場合は最長 10 秒、`character_orientation=video` の場合は最長 30 秒。人物が常に画面内にいる連続したワンショット動画の使用を推奨します。
* `mode`：動画生成のモードで、主に標準モード `std` と高速モード `pro` の2種類があります。
* `keep_original_sound`：動画の元の音声を保持するかどうかを選択できます。列挙値：yes、no。
* `character_orientation`：生成動画内の人物の向きで、画像と一致させるか動画と一致させるかを選択できます。列挙値：image、video。
* `prompt`：プロンプト。
* `callback_url`：結果をコールバックする必要がある URL。
* `async`：任意です。`true` に設定すると、インターフェースはすぐに `task_id` を返し、`callback_url` を指定する必要はありません。その後、対応するタスク照会インターフェースでポーリングして結果を取得します。
選択後、右側にも対応するコードが生成されていることが分かります。図のとおりです：
「Try」ボタンをクリックするとテストできます。上図のように、ここでは以下の結果を取得しました：
```json theme={null}
{
"success": true,
"video_id": "842578800134742051",
"video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
"duration": "5.066",
"state": "succeed",
"task_id": "363c7a84-e880-472e-a4d4-098e50cfc292"
}
```
返却結果には複数のフィールドがあり、以下のとおりです：
* `success`、この時点での動画生成タスクのステータスです。
* `task_id`、この時点での動画生成タスク ID です。
* `video_id`、この時点での動画生成タスクの動画 ID です。
* `video_url`、この時点での動画生成タスクの動画リンクです。
* `duration`、この時点での動画生成タスクの動画リンクの長さです。
* `state`、この時点での動画生成タスクのステータスです。
満足のいく動画情報を取得できたことが分かります。結果中の `data` の動画リンクアドレスから、生成された Kling 動画を取得するだけです。
また、対応する連携コードを生成したい場合は、直接コピーして生成できます。たとえば CURL のコードは以下のとおりです：
```shell theme={null}
curl -X POST 'https://api.acedata.cloud/kling/motion' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
"video_url": "https://cdn.acedata.cloud/odwfm5.mp4",
"prompt": "让画面生动起来",
"mode": "std",
"character_orientation": "image"
}'
```
## 非同期コールバック
Kling Motion 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/624b2c78-6dbd-4618-9d2b-b32eade6d8c3` です。
次に、フィールド `callback_url` を上記の Webhook URL に設定し、対応するパラメータを入力します。具体的な内容は図のとおりです：
実行をクリックすると、以下のようにすぐに結果を取得できます：
```
{
"task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
```
少し待つと、`https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3` で生成動画の結果を確認できます。図のとおりです：
内容は以下のとおりです：
```json theme={null}
{
"success": true,
"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
"video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
"duration": "5.1",
"state": "succeed",
"task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
```
結果には `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"
}
```
## 結論
本ドキュメントを通じて、Kling Motion Generation API を使用してKling公式のモーションコントロール機能を実現する方法を理解しました。本ドキュメントが、この API との連携および使用により役立つことを願っています。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.