動画モデル上級者向け更新日
POST/v1/videos/generations
Kling V3 Motion Control
リクエスト ID kling-v3-motion-control
プロトコル
POST /v1/videos/generations· 動画を生成の例GET /v1/videos/tasks/{id}· 動画タスクを照会の例GET /v1/videos/tasks/{id}/content· 動画をダウンロードの例DELETE /v1/videos/tasks/{id}· 終了済みの動画タスクを削除の例
認証
リクエストには API キー管理 の API キーが必要です。JSON リクエストには Content-Type: application/json を設定します。
Authorization: Bearer YOUR_API_KEY
リクエストパラメータ
POST /v1/videos/generations
| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
model | string | 必須 | kling-v3-motion-control. このページに記載のモデル ID を指定します。 |
prompt | string | 任意 | キャラクターや動きの指示を補足できます。 |
content | array<object> | 必須 | 参照画像 1 枚と参照動画 1 本を指定します。 |
content[].type | string | 必須 | 指定できる値は text, image_url, input_image, video_url, input_video です。 |
content[].text | string | 条件付き | type: "text" の項目にプロンプトを指定します。 |
content[].role | string | 必須 | 画像には reference_image、動画には reference_video を使用します。 |
content[].asset_id | string | 条件付き | POST /v1/videos/assets に素材をアップロードし、返された id を指定します。multipart では kind（image, video）を file より先に指定します。 素材は自分のアカウントに属している必要があります。素材 ID か公開 HTTPS URL のいずれかを指定します。 |
content[].image_url | string | 条件付き | 公開 HTTPS の画像 URL を文字列で指定します。 |
content[].video_url | string | 条件付き | 公開 HTTPS の動画 URL を文字列で指定します。 |
motion_mode | string | 任意 | モーション制御モードです。 指定できる値は std, pro です。 既定値は std です。 |
character_orientation | string | 任意 | 参照動画は image で 3～10 秒、video で 3～30 秒です。 指定できる値は image, video です。 既定値は image です。 |
keep_original_sound | boolean | 任意 | 参照動画の元の音声を残すかを指定します。 既定値は true です。 |
リクエスト例
API Key をローカルの環境変数 ICODEEASY_API_KEY に設定し、直接 HTTP 呼び出しに対応するエンドポイントを選択します。指定クライアントが必要な場合は設定ガイドに従ってください。
例のメディア URL とアセット ID は、有効な素材に置き換えてください。
Video Generations
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/generations' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "kling-v3-motion-control",
"prompt": "Preserve the character identity and follow the reference motion.",
"content": [
{
"type": "image_url",
"image_url": "https://example.com/reference.png",
"role": "reference_image"
},
{
"type": "video_url",
"video_url": "https://example.com/motion.mp4",
"role": "reference_video"
}
],
"motion_mode": "std",
"character_orientation": "image",
"keep_original_sound": true
}'
動画タスクを照会
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY"
動画をダウンロード
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID/content' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-L \
-o result.mp4
終了済みの動画タスクを削除
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
レスポンスとタスク
HTTP 202 · タスクの受付
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "kling-v3-motion-control",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "queued",
"updated_at": "2026-07-30T08:00:00Z",
"task_id": "vid_1785398400000000000"
}
HTTP 200 · 完了したタスクの取得
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "kling-v3-motion-control",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "succeeded",
"updated_at": "2026-07-30T08:01:00Z",
"url": "/v1/videos/tasks/vid_1785398400000000000/content"
}
id を保存します。同じ API キーで status_url に GET リクエストを送り、status が succeeded または failed になるまで確認します。成功後は content_url からダウンロードし、HTTP リダイレクトに従います。どちらのパスも API ベース URL からの相対パスです。
| フィールド | 型 | 説明 |
|---|---|---|
id / task_id | string | タスク ID。作成レスポンスの task_id は id と同じです。 |
status | string | 状態は queued、running、succeeded、failed のいずれかです。 |
progress | integer | 生成の進捗。進捗値が得られない場合は省略されます。 |
error.code | string | タスクが失敗した場合のエラー分類。 |
主なエラー
| HTTP | エラータイプ | 説明 |
|---|---|---|
| 400 | invalid_request | モデル、パラメーターの組み合わせ、参照メディアを確認します。 |
| 401 | unauthorized | API キーが未指定、無効、または停止済みかどうかを確認します。 |
| 402 | insufficient_balance | タスクの送信に必要な残高が不足しています。 |
| 404 | not_found | 照会が 404 の場合はタスク ID を保存し、照会 URL と作成元アカウントの API キーを確認します。既に完了している可能性があるため、この応答だけで再送信しないでください。 |
| 409 | video_not_ready | 動画は生成中です。引き続き状態を確認してください。 |
| 503 | submission_unknown | 送信結果を確認できません。再送信する前にサポートへタスク作成の有無を確認してください。 |
接続ガイド · リクエスト項目、タスクの状態、レスポンス形式は API ガイドを参照してください。
機能と制限
text_to_video· 非対応reference_images· 対応video_input· 対応- 制限 参照画像：最大 1 枚 · 入力：One image and one video. Modes: std or pro. Reference video: 3–10 seconds for image orientation, 3–30 seconds for video orientation.