チュートリアル
HiAPI API で kling-3.0-omni/transformation を呼び出す方法:curl と Python ガイド
HiAPI での動画スタイル変換のための実行可能なリクエストの完全実践
このページの内容
transformation エンドポイントの機能と適用シーン
kling-3.0-omni/transformation は HiAPI 上の動画スタイル変換エンドポイントです。2 つのものを提供します:ソース動画と自然言語のスタイル指示です。ソース動画の内容を保持しつつ、要求された視覚スタイルで表現された新しい動画を返します。
HTTP 呼び出しの背後に隠れたポストプロダクション工程と考えることができます。モデルのトレーニング、GPU クラスタの維持、チェックポイントファイルの管理は不要です。望む視覚効果を記述し、動画を指定すれば、エンドポイントがレンダリング結果を生成します。
このエンドポイントが適するシーン
- 既存素材へのスタイル付与。 すでに撮影済みの映像があり、それをアニメーション、水彩、フィルムグレイン、クレイアニメ、その他の効果で表現したい場合。内容と動きは動画から得られ、エンドポイントは表面の質感を変えます。
- バッチで一貫したスタイルを維持。 スタイルは指示として表現されるため、同じプロンプトを多くのソース動画で再利用し、スタイルの一貫した成果物セットを得られます。
- スタイル開発のプロトタイピング。 クリエイティブチームは、より重い制作パイプラインに投資する前に、低コストでスタイルの方向性を反復できます。
適さないシーン
- ゼロから動画を生成する必要がある場合(テキストから動画への生成は別のタスクです)。
- フレーム単位で正確な編集、カット、合成が必要な場合。変換はスタイルを再形成するだけで、編集は行いません。
- ソース素材が音声のみ、または静止画像のみの場合。
このガイドの残りの部分では、リクエスト構造、すぐに実行できる curl 呼び出し、対応する Python バージョン、そして 4K 出力と長時間タスクを巡る運用上の詳細を順を追って説明します。
リクエストの解析:ソース動画、スタイル指示、出力オプション
変換リクエストは複雑ではありません。コードを書く前に、3 つのフィールドグループに分解します:ソース動画、指示、出力設定です。
ソース動画
エンドポイントは入力にアクセスできる必要があります。実際には、プラットフォームが取得できる URL、または HiAPI のファイルアップロード手順が返す識別子を渡します。実用的なルールは、ソースファイルがノート PC からではなく、サーバー側からアクセス可能でなければならないということです。localhost パスや VPN の背後にあるファイルは機能しません。
ソース形式は保守的に保つべきです——広くサポートされているコンテナとコーデックを使用してください。動画が特殊なプロセスで生成され、検証に通らない場合は、まず標準の H.264 MP4 に再エンコードしてください。この一手間で入力エラーの大部分が解決します。
スタイル指示
これは目標の視覚効果に対する自然言語の記述です。リクエストの中で最も影響力のあるフィールドであり、最も練る価値のあるフィールドです。
- 視覚処理を記述し、内容は記述しないでください。内容は動画から来るので、すでに画面にあるものをモデルに伝えるのはプロンプトの予算の無駄です。
- 媒体と質感について具体的に:「指紋の跡が visible なストップモーション・クレイアニメーション」は「アニメーション」よりも多くの情報を伝えます。
- 重要な場合は保持すべきものを明示する:「顔を識別可能に保ち、カメラの動きを変えない」。
- 焦点を絞った 1 段落に収める。長く矛盾したプロンプトは、平凡な結果に平均化されがちです。
出力オプション
出力設定は解像度とその他の配信詳細を制御します。主な決定は 4K を要求するか標準解像度にするかです。高解像度はより多くの計算資源を消費し、時間がかかるため、デフォルトではなく意識的な決定として扱うべきです。エンドポイントは一般に非同期タスクとして実行されるため、リクエストは通常、完成ファイルを直接返すのではなく、ポーリングまたは待機が必要なタスク参照を返します。
入力をこれら 3 つのフィールドグループにマッピングすれば、実際の JSON リクエストボディは明確になります。
ゼロから始める実行可能な curl リクエスト
理解を確認する最速の方法は、最小限の呼び出しです。以下の形式は、ソース動画 URL とスタイル指示を送信し、標準解像度の結果を要求します。プレースホルダーの値は自分の値に置き換えてください。
curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": "手描きの水彩アニメーションに変換。柔らかく滲む輪郭、紙の質感が見え、温かみのある限定されたパレットを使用。顔とカメラの動きを保持。",
"resolution": "1080p"
}'
各部分の役割
- URL パスはエンドポイントを指定します。完全に正確でなければなりません。ここのスペルミスは検証エラーではなく、ルーティングエラーを返します。
Authorizationヘッダーは HiAPI キーを運びます。シェル履歴に貼り付けるのではなく、環境変数としてエクスポートしてください。video_urlはソース動画です。サーバー側から取得可能でなければなりません。promptはスタイル指示です。最も頻繁に変更するフィールドです。resolutionは出力設定です。反復時は低解像度から始め、効果が確定してから上げてください。
レスポンスの解釈
成功したレスポンスはタスクオブジェクトを返します。タスク識別子と任意のステータスフィールドを記録します:
{
"id": "job_abc123",
"status": "queued"
}
正確なフィールド名は仮定せず、実際のレスポンスから読み取るべきです。重要な習慣はどの言語でも同じです:JSON を解析し、タスク ID を抽出し、完成した動画は後で到着するものとして扱います。最初のレスポンスに再生可能なファイルが含まれると仮定したコードを書かないでください。
同じリクエストを Python で
Python バージョンは、JSON リクエストボディを辞書として表現した curl 呼び出しです。requests を使用すると可読性が保たれ、依存関係も軽量です。
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": (
"手描きの水彩アニメーションに変換。柔らかく滲む輪郭、紙の質感が見え、"
"温かみのある限定されたパレットを使用。顔とカメラの動きを保持。"
),
"resolution": "1080p",
}
resp = requests.post(
f"{BASE}/kling-3.0-omni/transformation",
headers=HEADERS,
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))
タスク完了までポーリング
レンダリングは非同期であるため、待機をループでラップし、試行回数の上限とチェック間のスリープ時間を設定します。スリープ時間は API を頻繁に叩かないよう十分に余裕を持たせ、総待機時間に上限を設けてスタックしたタスクがワーカープロセスを停止させないようにします。
def wait_for_job(job_id, max_attempts=60, interval=10):
for _ in range(max_attempts):
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status == "failed":
raise RuntimeError(data.get("error") or "job failed")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish in time")
result = wait_for_job(job_id)
print(result.get("output") or result)
本番環境で安全にする
- エンドポイントパスとポーリングルートは API レスポンスのドキュメントから読み取り、ドリフトする可能性のある仮定をハードコードしないでください。
- 送信時にタスク ID を記録します。下流で問題が発生した場合、これが唯一の手がかりです。
failedとタイムアウトを異なる結果として扱います。失敗したタスクは通常パラメータの問題、タイムアウトは通常容量または長さの問題です。
4K 出力と長時間実行タスクの処理
2 つの変数がこのエンドポイントの運用動作を支配します:出力解像度と入力の長さです。両方について明確に計画してください。
4K 出力
4K は配信上の決定であり、デフォルト値ではありません。各出力ピクセルは計算資源を消費し、標準解像度から 4K への相対的な跳ね上がりは大きいです。合理的なワークフロー:
- 低解像度でスタイル指示を反復します。プロンプトの品質は解像度に依存しないため、まず低コストで効果を正しく調整します。
- プロンプトとソース動画を固定します。
- 配信用に 4K で一度再実行します。
文言を調整しながらタイトなループで 4K バリアントを生成することは避けてください——最終的に破棄されるレンダリングに予算を無駄にする最も一般的な方法です。
長時間実行タスク
より長いソース動画は変換に時間がかかり、エンドポイントは完成ファイルではなくタスク参照を返します。この現実に合わせてクライアントを構築してください:
- Web リクエストをレンダリングでブロックさせないでください。 送信し、タスク ID を保存し、すぐに呼び出し元に返します。
- 送信と取得を分離します。 キューとポーリングワーカーはインライン待機よりも堅牢で、プロセスの再起動に耐えます。
- タスク状態を永続化します。 ワーカーがポーリング中に死んでもタスクは消えません。保存された ID から復元できます。
- アカウントが webhook をサポートしている場合は使用し、フォールバックパスとしてポーリングを維持します。
- 総待機予算を設定します。任意の数値ではなく、予想される最長動画を反映させてください。
実用的なパターン
典型的な長さを超えるソース動画をクリップに分割し、1 つずつ変換してから結果を結合します。これにより単一の待機時間が短縮され、レンダリング全体ではなく特定のクリップのみを再試行でき、失敗が安価になります。クリップ境界が速い動きを横切らないように注意してください。そうしないと継ぎ目が目立ちます。
一般的な障害のトラブルシューティング
ほとんどの障害は 3 つのカテゴリに分類されます:ソース動画が読み取れない、パラメータが拒否される、タスクが完了しない。何かを変更する前に問題のカテゴリを特定してください。
アップロードとソースアクセスのエラー
症状:送信が失敗する、またはタスクが入力エラーでほぼ即座に失敗する。
- URL が公開アクセスできない。 自分のネットワーク外のマシンからテストしてください。署名付き URL が送信と取得の間に期限切れになるのが典型的な原因です。
- 形式がサポートされていない。 標準の H.264 MP4 に再エンコードして再試行してください。
- ファイルが切り詰められているか破損している。 自分でダウンロードして最初から最後まで再生してください。
- リクエストが大きすぎる。 ファイルバイトを URL ではなくインラインで送信している場合は、アップロードフローを使用して返された識別子を渡してください。
パラメータエラー
症状:送信時に 4xx レスポンスが返る。
- JSON の形式が不正。 lint ツールでリクエストボディをチェックしてください。末尾のカンマとエスケープされていない引用符は、手書きの curl 呼び出しでよくある間違いです。
- フィールド名または型が間違っている。 現在のリクエストスキーマと照合してください。解像度を文字列が期待されるのに数値として渡すと失敗します。
- プロンプトが空または矛盾している。 指示が何も記述していない場合、または相互に排他的なスタイルを要求する場合、出力は弱いか拒否されることが予想されます。明確な視覚的方向性を中心に書き直してください。
- API キーが欠落または無効。 ヘッダーの値、およびキーがそのエンドポイントに対して有効かどうかを確認してください。
タイムアウトとスタックしたタスク
症状:待機予算を過ぎてもタスクがキューまたは実行状態のまま、またはクライアントが諦める。
- クライアントタイムアウトとタスク失敗を区別してください。送信時の短い HTTP タイムアウトはタスクが開始されなかったことを意味しません。再送信する前にタスク ID があるか確認してください。そうしないと重複レンダリングになる可能性があります。
- 長い入力と 4K 出力は実行時間を延長します。タイムアウトが続く場合は、解像度を下げるか動画を短縮してフローが機能することを確認してから、徐々に元に戻してください。
- タスクが
failedを報告した場合、再試行する前にエラーメッセージを読んでください。決定論的なパラメータエラーに対して盲目的に再試行するとコストが倍増するだけです。
効果的なデバッグ順序
可能な限り最小のリクエストから始めます:短い標準解像度の動画と 1 つのプロンプト。成功したら、実際のプロンプト、実際の長さ、最後に 4K を 1 つずつ再導入し、毎回 1 つの変数だけを変更します。失敗したステップがどの変数が原因かを教えてくれます。
計画すべきコストとレイテンシのトレードオフ
リクエストが利用可能になった後、残る決定は運用上のものです。3 つのレバーが同時にコストとレイテンシに影響し、相互作用します。
解像度
出力解像度は最大の単一レバーです。課金はレンダリング実行の作業量に連動し、高解像度の出力はより多くの作業を意味します。経験則:低解像度で反復、高解像度で配信。スタイル実験を 4K で実行しないでください。
入力の長さ
より長いソース動画は変換するフレームが多いことを意味し、より多くの計算資源とより多くの実時間を意味します。ユースケースが許せば、フルレングスの編集ではなく短いハイライト動画を変換するか、長い素材を分割して処理が必要な部分だけを変換してください。
再試行
失敗がタスク開始前でない限り、各再試行は完全なレンダリングです。だからこそデバッグ順序が重要です:レンダリングにお金をかける前にパラメータを低コストで検証してください。タスク ID を記録し、クライアントタイムアウト後に再送信する前に確認することで重複送信を防ぎます。
バッチ処理と並列処理
並列タスクは実時間を短縮しますが総コストは削減しません——また並行性制限に達する可能性があります。バッチ処理では、制御された並列度の適度なキューが通常ファンアウトよりも優れています。レート制限以下に保ち、失敗を個別に再試行しやすくし、予測可能な支出曲線を与えます。
予算チェックリスト
- 配信レンダリングの前に、低解像度でプロンプトを確定する。
- 完成した出力をキャッシュする。同じ入力を再レンダリングしない。
- タスクごとおよびバッチごとの支出見込みを設定し、バッチが超過したらアラートを出す。
- タスク時間と解像度および入力長の関係を追跡し、過去の実行から新しい作業を予測できるようにする。
- 4K をプロセス内の最終ステップとして扱い、インタラクティブモードとはしない。
このエンドポイントの価格は HiAPI のウェブサイトに掲載されているため、バッチサイズを計画する前に最新の料金を確認してください。まず最小リクエストを実行し、その後意識的に解像度と長さを拡張してください——この順序がレイテンシと請求の両方を予測可能に保ちます。