チュートリアル

kling-3.0-omni/transformation APIの使い方：curlとPythonで動画をリスタイルする

Oct 14, 2026

kling-3.0-omni/transformation は Kling 3.0 Omni の動画から動画へのモデルです。ソース動画とテキストプロンプトを渡すと、元の動きとタイミングを保ったまま、その動画の見た目——シーン、スタイル、被写体——を書き換えます。hiapi では、他のすべての生成モデルと同じ統一非同期エンドポイント POST /v1/tasks で呼び出します。本ガイドでは、実際に検証済みのパラメータ表、そのままコピー＆ペーストできる curl リクエスト、完全な Python クライアント（ポーリングして結果をダウンロード）に加え、実際のアプリに組み込む前に必要な本番運用パターン（コールバック、冪等性、エラーハンドリング）を提供します。

以下の各フィールド名、列挙値、レスポンス構造はすべて実際の API と照合済みです。

構築するもの + 前提条件

小さなプログラムです：リスタイルタスクを送信し、完了を待ち、リスタイルされた .mp4 をダウンロードします。必要なものは 2 つです：

hiapi API キー。 hiapi コンソールで作成します——形式は sk-... のようなものです。各リクエストでは Authorization: Bearer sk-<your-key> を使用します。
公開アクセス可能なソース動画 URL。 モデルはサーバー側で動画をダウンロードするため、公開された http(s) URL（自分の CDN、公開オブジェクトを持つ R2/S3 など）である必要があり、ローカルファイルパスは使えません。URL は 1 つだけです。

モデルとそのパラメータ

リクエストの外側の構造は {"model": ..., "input": {...}} です。input のスキーマは厳格で、以下の 3 つのフィールドのみを受け付け、余分なフィールドは拒否されて 400 が返されます。

フィールド	型	必須	説明
`prompt`	string	はい	目標のスタイル／シーン／被写体を記述します。リスタイルの強度もここで調整します——数値型の `strength`/`fidelity` パラメータはありません。
`video_urls`	array	はい	ちょうど1 つの公開ソース動画 URL（`minItems` は 1、`maxItems` は 1）。
`resolution`	string 列挙	はい	`720p`、`1080p`、`4k` のいずれか。

つまずきやすいポイント：

duration パラメータはありません。 出力の長さとアスペクト比はソース動画に従い（3～15.5 秒）、最終出力の長さで課金されます。
モデル ID 自体に -omni が付きます：kling-3.0-omni/transformation（他の一部の Omni エンドポイントは kling-3.0/... を使用します）。この ID をそのまま model の値として指定します。
リスタイルの強度はプロンプトで決まります。 軽微な変更なら「軽くリスタイルし、顔の特徴と照明を保つ」、大きな変更なら「2D セルルックカートゥーンとして完全に再想像する」と書きます。

最小の動作例（curl）

# 1) リスタイルタスクを作成
curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/transformation",
    "input": {
      "prompt": "このシーンを、柔らかな紙の質感と暖かな夕暮れの光を備えた手描き水彩アニメーション風にリスタイルしてください。元のカメラワークと被写体は保ってください。",
      "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
      "resolution": "720p"
    }
  }'
# -> {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2) タスクが終了状態になるまでポーリング
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01... \
  -H "Authorization: Bearer sk-<your-key>"
# data.status は順に：queued -> handling -> archiving -> success
# 成功後、data.output[0].url がリスタイルされた .mp4

ポーリングに使うタスク ID は作成レスポンスの data.taskId から取得します——トップレベルの id ではありません。ステータス文字列は queued / handling / archiving / success（終了状態）または fail です。succeeded/completed と仮定しないでください。

完全な Python クライアント（作成 → ポーリング → ダウンロード）

import os
import time
import requests

API_KEY = os.environ["HIAPI_KEY"]            # あなたの sk-... キー
BASE = "https://api.hiapi.ai"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_restyle(source_video_url: str, prompt: str, resolution: str = "720p") -> str:
    body = {
        "model": "kling-3.0-omni/transformation",
        "input": {
            "prompt": prompt,
            "video_urls": [source_video_url],   # ちょうど 1 つの公開 URL
            "resolution": resolution,           # "720p" | "1080p" | "4k"
        },
    }
    r = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 200:
        raise RuntimeError(f"送信が拒否されました：{data}")
    return data["data"]["taskId"]


def wait_for_video(task_id: str, poll_s: int = 10, timeout_s: int = 900) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"タスクが失敗しました：{data.get('error')}")
        time.sleep(poll_s)                      # queued / handling / archiving
    raise TimeoutError(f"{task_id} は {timeout_s} 秒以内に完了しませんでした")


if __name__ == "__main__":
    task_id = create_restyle(
        source_video_url="https://your-cdn.example.com/source-clip.mp4",
        prompt=(
            "このシーンを、柔らかな紙の質感と暖かな夕暮れの光を備えた"
            "手描き水彩アニメーション風にリスタイルしてください。元のカメラワークと被写体は保ってください。"
        ),
        resolution="720p",
    )
    print("タスク：", task_id)

    url = wait_for_video(task_id)
    print("動画 URL：", url)

    # 出力ファイルは temp.hiapi.ai にあり、期限切れになります（約 7 日）。今すぐダウンロードしてください。
    clip = requests.get(url, timeout=120).content
    with open("restyled.mp4", "wb") as f:
        f.write(clip)
    print("restyled.mp4 を保存しました", len(clip), "バイト")

キーを環境変数に入れて実行します：

export HIAPI_KEY=sk-<your-key>
python restyle.py

本番運用パターン

頻繁なポーリングの代わりにコールバックを使う

スクリプト以外のあらゆる場面では、ポーリングループを維持しないよう webhook を登録してください。callback はトップレベルのフィールドで、model や input と同じ階層に置きます。input の中に入れてはいけません：

{
  "model": "kling-3.0-omni/transformation",
  "input": {
    "prompt": "このシーンを、太い輪郭線を持つ 2D セルルックカートゥーン風にリスタイルしてください。元の動きは保ってください。",
    "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
    "resolution": "1080p"
  },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

callback.when は final（デフォルト値）のみを受け付けます。タスクが終了状態になると 1 回キューに入り、成功時も失敗時も発火します。配信セマンティクスは少なくとも 1 回であるため、同じコールバックが複数回届く可能性があります（後述）。
配信される POST リクエストボディは、GET /v1/tasks/<id> で得られる data オブジェクトと完全に同じです。そのため、ハンドラは再取得せずに status、output[].url、error を読み取れます。
callback を input の中に入れると、送信時に additional properties 'callback' not allowed というエラーで失敗します（各モデルの input スキーマは厳格です）。

冪等性と配信セマンティクス

コールバックは少なくとも 1 回であり、ちょうど 1 回ではありません——同じ taskId が複数回届く可能性があります。ハンドラのキーを taskId にして、「完了マーク + 動画保存」のステップを冪等にしてください。hiapi は 2xx 以外／タイムアウトのコールバックを即時 → +1 分 → +5 分 → +20 分、最大 4 回の試行のペースでリトライします。リトライを止めるには、エンドポイントが HTTP 2xx を返す必要があります。

出力をすぐにダウンロードする

data.output[0].url は temp.hiapi.ai を指し、expireAt（Unix タイムスタンプ、約 7 日の TTL）が付いています。期限が切れるとオブジェクトは削除され、その URL は 404 を返します——タスクを再ポーリングすると同じ URL が返りますが、ファイルが再生成されることはありません。タスクが成功したらすぐに、バイトを自分のストレージにコピーしてください。

エラーハンドリング

分岐して処理する必要がある 3 つの失敗形態：

リクエストエラー（HTTP 400）——フラット構造で、タスクは作成されません： {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: resolution: value must be one of '720p', '1080p', '4k'"}
認証失敗（HTTP 401）——ネスト構造： {"error":{"code":"permission_denied","type":"hiapi_error", ...}}
タスク失敗——送信は 200 と taskId を返しますが、その後のポーリングで data.status == "fail" となり、data.error が付きます。失敗したタスクは課金されません（タスクが最終的に失敗すると、事前に差し引かれた金額は返金されます）。ソース URL にアクセスできない、またはダウンロードできない場合はここに現れます。

料金

kling-3.0-omni/transformation は出力秒数で課金され、レートはリクエストした解像度によって変わります（720p は毎秒 $0.143、1080p は毎秒 $0.193、4k は毎秒 $0.479、2026 年 10 月 21 日時点で確認）。動画をバッチ処理する前に、最新の毎秒レートについて hiapi 料金ページを確認してください——動画タスクは画像タスクよりはるかに速く費用が積み上がります。

モデルページと仕様：hiapi 上の kling-3.0-omni/transformation
エンドポイントリファレンス：タスクの作成——統一非同期 API
同じエンドポイントの同シリーズチュートリアル：Python での Kling AI 画像から動画への API

よくある質問

リスタイルの強度はどうやって制御しますか？ パラメータではなくプロンプトで制御します。strength、fidelity、creativity といったフィールドはありません。軽微な編集なら「軽くリスタイルし、顔と照明を保つ」、大幅な編集なら「完全に再想像する

重要なポイント

kling-3.0-omni/transformation は動画から動画へのリスタイルモデルです：テキストプロンプトに従って 1 つのソース動画の見た目を書き換え、元の動きとタイミングを保ちます。
hiapi の統一非同期エンドポイント POST /v1/tasks で、ベアモデル ID と Authorization: Bearer sk-<key> を使って呼び出します。送信すると data.taskId が返るので、その後 GET /v1/tasks/<id> をポーリングします。
input にはちょうど 3 つのフィールドがあります——prompt（必須）、video_urls（1 つの公開 URL）、resolution（720p|1080p|4k）。duration/strength/fidelity パラメータはなく、余分なフィールドは拒否され 400 が返ります。
出力は temp.hiapi.ai 上の data.output[0].url にあり、期限切れになります（約 7 日）。そのためタスクが success 状態になったらすぐに .mp4 をダウンロードしてください。
本番環境では、トップレベルの callback {url, when:'final'} を登録します。これは成功時または失敗時に 1 回発火し、配信セマンティクスは少なくとも 1 回であるため、taskId で重複排除してください。