機能別
動画
動画は常にタスクとして実行されます:送信して、後で確認するかコールバックを受け取ります。長く高精細なクリップほど料金が高くなります。
#1. モデルを選ぶ
kling-v3-motion-control$0.10288 / リクエスト制限とステータス
この用途で稼働中のモデルは 13 個です。切り替えると下のコードが変わります。
#2. リクエストをコピー
YOUR_API_KEY を自分のキーに置き換えて実行します。表示されているオプションは、このモデルが受け付けるものです。
https://www.aisplice.store/v1/videosBearer API key非同期タスクオプションこのモデルで公開されているオプションのみ表示しています。
# Requires curl and jq
API_KEY="${API_KEY:-YOUR_API_KEY}"
# 1. Submit once
SUBMITTED=$(curl --fail-with-body -sS https://www.aisplice.store/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: model-docs-$(date +%s)-$$" \\
-d '{
"model": "Kling 3.0 Motion Control",
"prompt": "A cinematic scene with careful composition",
"images": [
"https://example.com/reference.png"
],
"videos": [
"example"
],
"mode": "std",
"metadata": {
"character_orientation": "video",
"keep_original_sound": "yes",
"video_urls": [
"https://example.com/source.mp4"
]
},
"nsfw_check": false
}')
TASK_ID=$(printf '%s' "$SUBMITTED" | jq -r '.task_id // .id // empty')
if [ -z "$TASK_ID" ]; then
printf '%s\n' "$SUBMITTED" >&2
exit 1
fi
echo "task_id=$TASK_ID"
# 2. Poll until terminal
while true; do
STATUS_JSON=$(curl --fail-with-body -sS \
"https://www.aisplice.store/v1/videos/$TASK_ID" \
-H "Authorization: Bearer $API_KEY")
STATUS=$(printf '%s' "$STATUS_JSON" | jq -r '.status // empty' | tr '[:upper:]' '[:lower:]')
echo "status=$STATUS"
case "$STATUS" in
completed|succeeded|success) break ;;
failed|failure|cancelled|canceled)
printf '%s\n' "$STATUS_JSON" | jq .
exit 1
;;
esac
sleep 5
done
# 3. Fetch the final result
curl --fail-with-body -sS \
"https://www.aisplice.store/v1/videos/$TASK_ID/content" \
-H "Authorization: Bearer $API_KEY" | jq .このモデルには公開メディア URL が必要です。 ローカルファイルは先にアップロードし、public_url をモデルのリクエストに指定してください。大きな Base64 のボディは避けてください。
アップロードガイドを読むすべてのパラメーター
このモデルが受け付けるすべてのフィールドと、指定できる値。
すべてのパラメーター
このモデルが受け付けるすべてのフィールドと、指定できる値。
modelこのリクエストで使う正確なモデル識別子。
kling-v3-motion-controlpromptOptional. Motion, camera and style notes; the reference video drives the movement.
imagesExactly one public picture of the person who performs the motion (a clear full or half body works best).
videosExactly one public mp4/mov reference video, at least 3 s and up to 100 MB, whose motion is copied. The output is as long as this clip.
metadata.video_urls公開された HTTP(S) のソース動画 URL。 最大 1 個。
レスポンスの流れ
タスクのステータス、終了状態、結果レスポンスの例。
レスポンスの流れ
タスクのステータス、終了状態、結果レスポンスの例。
{
"id": "task_xxx",
"task_id": "task_xxx",
"object": "video",
"model": "Kling 3.0 Motion Control",
"status": "queued"
}待機中
queued · submitted · in_progress · processing
成功
completed · succeeded · success
失敗
failed · failure · cancelled · canceled
#3. 結果を取得
送信するとすぐに task_id が返ります。status が completed になるまで数秒ごとにタスクを確認するか、webhook_url を渡せば完了時にこちらから呼び出します。
GET https://www.aisplice.store/v1/videos/{task_id}
GET https://www.aisplice.store/v1/videos/{task_id}/content
長さと解像度で料金ティアが決まります。実行中のタスクはキャンセルできます。API リファレンスを参照してください。
成功した場合のみ課金
#うまくいかないとき
- フィールド名付きの 400:そのオプションはこのモデルでは受け付けられません。手順 2 に表示される値を使ってください。
- 参照画像や参照動画が拒否された場合:モデルがダウンロードできる公開 URL である必要があります。
- モデルがコンテンツを拒否した場合:プロンプトを言い換えてください。拒否されたリクエストは課金されません。
- 402:残高がこのリクエストに足りません。ウォレットでチャージしてから再試行してください。
- 429:ペースを落とし、Retry-After の秒数が経ってから再試行してください。
- 503 model_not_found:モデル名が間違っているか、モデルがオフラインです。手順 1 から選び直してください。
#開始・終了フレーム、参照画像と参照動画
対応するモデルでは、手順 2 に開始フレーム、終了フレーム、参照画像、参照動画のフィールドが表示されます。公開 URL を指定し、ローカルファイルは先にアップロードしてください。
プロダクトに組み込む最初にユーザーに見せるオプションと、後回しにするオプション。
最初にユーザーに見せるべき選択肢まずはプロンプトと料金に影響する設定を 1 つだけ用意し、基本フローが動いてから残りを追加します。+
創作の意図
prompt のようなフィールドは、変更による結果をユーザーが直接理解できるため、UI に置くべきです。
コストの倍率要因
duration、resolution、size、count のようなフィールドは、料金をすでに説明できる状態になってから導入してください。
モード切り替え
image、mask、継続用の ID のようなフィールドはワークフロー自体を変えるため、専用のモードでのみ表示してください。
システム内部の設定
webhook_secret のようなフィールドは日常的なクリエイターではなく統合する開発者向けなので、デフォルトの UI には含めないでください。
prompt- 表示するタイミング
- 常に。シーンや動きの方向を定義します。
- 推奨デフォルト
- UI で必須にします。
- 重要な理由
- これがないと、ユーザーはクリップの意図をコントロールできません。
image / images- 表示するタイミング
- 参照素材ベースまたは画像から動画のプロダクトでのみ表示します。
- 推奨デフォルト
- プロンプトのみのフローでは非表示にします。
- 重要な理由
- 作成モードを変えるため、意図的なプロダクト判断として扱うべきです。
duration- 表示するタイミング
- 基本の非同期フローが安定し、料金が表示されるようになってから表示します。
- 推奨デフォルト
- 対応する最短の長さから始めます。
- 重要な理由
- 動画生成において、コストとレイテンシーを最も大きく左右する要因の 1 つです。
resolution- 表示するタイミング
- 顧客が 720p、1080p、4K の出力を明確に比較する場合に表示します。
- 推奨デフォルト
- サーバー側で推奨解像度を 1 つ選びます。
- 重要な理由
- 解像度が高いほど、コスト、待ち時間、失敗しやすさが増します。
webhook_url / webhook_secret- 表示するタイミング
- バックエンドの統合担当者向けにのみ表示し、一般のエンドユーザーには表示しません。
- 推奨デフォルト
- UI のプロダクトではポーリングを優先します。
- 重要な理由
- これらはエンドユーザーの創作ではなくシステム統合のための設定なので、利用者向けのコントロールには含めないでください。
Phase 1
- prompt
- one size or one duration default
- submit -> poll -> content
Phase 2
- one quality or resolution selector
- clear pricing hint
Phase 3
- advanced controls such as reference media, continuation, webhook, or vendor-specific tuning結果の信頼できる情報源は 1 つに
まだ解決しませんか?
リクエスト ID かエラーメッセージを送っていただければ、こちらで調査します。