チュートリアル
HiAPI API で topaz-upscale/video を使用する方法:curl と Python の例
このページの内容
topaz-upscale/video の機能と適用シーン
topaz-upscale/video は HiAPI 上の動画エンハンスメントエンドポイントです。ソース動画と指示を送ると、エンハンス済みの動画を返します:より高い解像度、再構築された精細なディテール、さらに任意でフレーム補間によるより滑らかな動き。素材がすでに存在し、問題がコンテンツ生成ではなく品質にある場合に、このエンドポイントを使うべきです。
適用シーン
このエンドポイントに自然にマッチする典型的なタスク:
- アーカイブと古い素材——古い映像、圧縮された画面録画、継承したメディアなど、現代的な解像度で見栄えよくする必要があるもの。
- レンダリングパイプライン——速度のために低解像度で先にレンダリングした完成済みシーケンスを、納品用に後からエンハンスする。
- モーションのクリーンアップ——低フレームレートのソースに補間フレームを挿入し、再生時のカクつきを防ぐ。
- 納品バリアント——1つのマスターから複数の出力階層を作り、階層ごとにエンハンスを適用する。
代替手段ではなくこれを選ぶべき時
判断は通常3つの問いに集約されます:
- 問題は解像度とディテールにあるのか、それともコンテンツにあるのか?存在しない新しいピクセルを発明する必要がある場合(一度も撮影されなかったシーン)、それは間違ったツールです。エンハンスは土台に本物のソースフレームがあることを前提とします。
- あなたのパイプラインは非同期処理を許容できるか?動画タスクは一瞬では終わりません。ユーザー体験がサブ秒の応答を要求するなら、このエンドポイントはリクエストハンドラ内ではなくバックグラウンドタスクに置くべきです。
- フレーム補間とアップスケールの両方が必要か?動きの滑らかさが重要なら、複数の独立したツールを直列につなぐのではなく、1回の処理で両方の機能を得たいはずです。
topaz-upscale/videoは両方をカバーします。
ソースが1枚の静止画像なら、画像アップスケーラーを使ってください。ソース自体は問題ないがエンコードが悪いなら、まずエンコードを直してください——エンハンスは重度の圧縮がすでに破壊したディテールを復元できず、計算コストを払ったのに品質向上は得られません。
初回呼び出しの前にリクエストを準備する
初回呼び出しの失敗の大半は、プロンプトの不出来ではなく抜け漏れに起因します。コードを書く前に、これらを準備してください。
アカウントと認証情報
topaz-upscale/video にアクセスできる HiAPI API キーが必要です。キーはソースコードではなく環境変数に保存してください——以下のすべての例は HIAPI_API_KEY を環境から読み取ります。
export HIAPI_API_KEY="your-key-here"
アクセス可能なソースメディア
モデルがあなたの入力を取得できる必要があります。信頼できる2つのパターン:
- 公開 URL または署名付き URL——サービスが対話的認証なしでダウンロードできる URL。ストレージが署名付きリンクを要求する場合、十分な有効期限のリンクを生成し、リトライ時に再生成することを忘れないでください。さもないと長時間タスクが途中で失敗します。
- 先にアップロード——プラットフォームのアップロード機構でファイルを送信し、返された識別子を参照する。大きなファイルやプライベートネットワークの内側にあるものには、これがより安全な選択です。
確認しておくべきソースの特徴
1回の呼び出しを消費する前に、以下を確認してください:
- 長さ。長い動画は長いタスクを意味します。テスト中なら、ソースの中間から5〜10秒のクリップを切り出してください——中間は冒頭フレームよりも代表的であることが多いです。
- コーデックとコンテナ。稀なコーデックはデコードできないことがあります。疑わしければ一般的なコンテナに再ラップしてください。
- フレームレート。正確に記録してください。フレーム補間の推論時に使います。
- 解像度。正確なソースサイズを記録してください。そうすればビフォーアフター比較が誠実になります。
出力目標を明確にする
初回呼び出しの前に、出力解像度とフレームレートを決めてください。後ではなく。720p ソースを1080pに上げるのに妥当なエンハンス設定は、480p ソースを4Kに上げる設定とは異なります。目標を書き留めてください。以降のすべてのリクエストで再利用します。
curl で呼び出しを行う
リクエストは topaz-upscale/video エンドポイントへの JSON ボディ付き POST です。以下は完全に実行可能な例です——自分のメディア URL に置き換えてください。
curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "topaz-upscale/video",
"input": {
"video": "https://your-bucket.example.com/clips/source_720p.mp4"
},
"parameters": {
"target_resolution": "1080p",
"target_fps": 60,
"interpolation": "smooth",
"detail": "balanced"
},
"prompt": "生地や肌の細かな質感を復元し、粒子は自然に保ち、ゴーストなしで60fpsに補間する"
}'
レスポンスの読み取り
即時レスポンスはタスクを確認するものです。タスク識別子とステータスフィールドを受け取ります。動画処理は非同期なので、実際のパターンはこうなります:
# 1. 送信してタスク id を取得
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | jq -r '.id')
# 2. 終状態になるまでポーリング
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'
結果を読む際、3つのフィールドが重要です:
status——キュー待ちから実行中、そして終状態へ。認識できないステータスは成功ではなく「引き続き待機」として扱ってください。output——成功時に存在し、エンハンス済み動画の URL または識別子を含みます。error——失敗時に存在します。メッセージを逐語的に読んでください。通常は問題のあるフィールドを指し示します。
プロンプトを反復するなら、リクエストボディをファイル(request.json)に置き、-d @request.json を使ってください。これでシェル履歴がきれいに保たれ、同じリクエストの異なるバージョンを diff できます。
Python から同じエンドポイントを呼び出す
Python 版は同じ HTTP 契約の薄いラッパーです。requests を使い、キーを環境に保存し、送信とポーリングループを関数に包みます。そうすれば呼び出し側は非同期であることを知る必要がありません。
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def enhance_video(
video_url: str,
prompt: str,
target_resolution: str = "1080p",
target_fps: int = 60,
poll_interval: float = 5.0,
timeout: float = 1800.0,
) -> str:
payload = {
"model": "topaz-upscale/video",
"input": {"video": video_url},
"parameters": {
"target_resolution": target_resolution,
"target_fps": target_fps,
"interpolation": "smooth",
"detail": "balanced",
},
"prompt": prompt,
}
resp = requests.post(f"{BASE}/video/enhance",
headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
job_id = resp.json()["id"]
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
if data["status"] == "succeeded":
return data["output"]["video"]
if data["status"] == "failed":
raise RuntimeError(data.get("error", "エンハンスに失敗しました"))
time.sleep(poll_interval)
raise TimeoutError(f"タスク {job_id} が想定時間内に完了しませんでした")
実際のパイプラインで使う際の注意点
- ポーリングには指数バックオフを。5秒固定間隔はシェルスクリプトなら問題ありませんが、本番環境ではバックオフし、間隔に上限を設けるべきです。長い動画には時間がかかることがあり、より頻繁にポーリングしても完了は早まりません。
- 冪等性。送信呼び出しがタイムアウトした場合、タスクが起動したかどうか分からないかもしれません。リクエストボディをタスク id と一緒に記録し、重複を照合できるようにしてください。盲目的に再送信しないこと。
- タスク id を永続化する。受け取ったらすぐにデータベースへ書き込んでください。ポーリング中にプロセスが落ちても、id から復帰でき、2回目のエンハンスに支払う必要がありません。
フレーム補間のプロンプトレシピ
フレーム補間はプロンプトが最も失敗しやすい領域です——曖昧すぎて何も導けないか、規定しすぎてモデルが矛盾した目標を追うことになります。プロンプトは構造化パラメータと併存します。文言は意図と動きの特徴に、数値目標はパラメータに持たせてください。
パターン:数学ではなく動きを描写する
悪い例:
interpolate
良い例:
滑らかな60fpsに補間する。元の動きのリズムを保ち、速度は変えない。パンやカメラの動きは線形で安定しているべきで、フレーム端の歪みは避ける。
目標フレームレートはすでに parameters で API に伝えています。プロンプトはこの素材の滑らかな動きがどのように見えるかを描写すべきです。
パターン:避けたいアーティファクトを名指しする
24p を60fpsに滑らかにする。速く動く手にゴーストを出さず、手すりや髪などの細い物体の周囲の尾引きを避ける。静的な背景は完全に静止したままでなければならない。
具体的な失敗モードを名指しする方が、「高品質」よりもはるかに効果的です。モデルは具体的な指示に対して自分の出力を検査できます。
パターン:動きとテクスチャを分離する
このパスでは動きの滑らかさのみに集中する。既存のディテールと粒子は変更しない——テクスチャ復元は別途処理する。
2つの処理段階を直列につなぐときに便利で、各プロンプトの責務が1つになります。
パターン:混合モーション素材を扱う
固定カメラだが被写体が動くインタビュークリップでは、カメラが静止していることを明示するとうまくいきます:
60fpsに補間する。カメラは固定——背景は完全に動かないか、ちらついてはならない。話し手の頭と手だけが滑らかな動きを示すべき。
長文を書く衝動を抑えてください。目標の動き、避けるべきアーティファクト、静止を保つべき内容の3文で、ほぼすべてのケースをカバーできます。
ディテール再構築のプロンプトレシピ
ディテール再構築はタスクのうち、もっともらしい精細構造を発明する半分です。失敗モードは幻覚テクスチャ:肌がプラスチックのように見え、植生がノイズになり、文字が文字化けします。プロンプトは発明に上限を設けるべきです。
パターン:ソースにアンカーする
ソースフレームと一致するディテールを再構築する。元のピクセルが示唆しないテクスチャを発明しない。ディテールが実際に失われている箇所では、シャープ化されたノイズよりも柔和で信憑性のある結果を優先する。
この1つの指示で、大半の過剰シャープ化の病理を防げます。
パターン:画面内の素材を名指しする
生地の質感、髪の毛、肌の毛穴の細かなディテールを復元する。肌色は自然に、毛穴は不規則に保ち、平滑でエアブラシのような外観は避ける。金属表面は既存のハイライトを保ち、新しいハイライトを生じさせない。
素材に特化した指示は、漠然とした長文なしでモデルに実行可能な制約を与えます。
パターン:文字とグラフィックを保護する
このクリップには画面字幕とロゴが含まれる。文字は鮮明で読みやすく、歪みなく保たれなければならない。いかなるグラフィック要素も描き直したりスタイルを変えたりしない。
文字は最もリスクの高いディテールです——文字化けした字幕は、少しぼやけた字幕より悪いです。可読性が重要なら、プロンプトを信じるのではなく比較段階で検証してください。
パターン:シャープ化を意図的に調整する
控えめなディテール復元量を適用する。目標は1080pで自然に見える素材であり、シャープ化された静止画ではない。軽度の柔らかさは許容できるが、リンギングとハローは許容できない。
両方を組み合わせる
1回の処理で補間と再構築の両方を行う場合は、両方をカバーするプロンプトを書きますが、各節は1つの関心事だけに触れてください:
生地、髪、肌といった細かなテクスチャをソースと一致するように再構築し、プラスチックのような平滑化を避ける。60fpsに補間し、動きは安定、手にゴーストなし、背景は完全に静止。
出力のビフォーアフターを比較する
1フレームでは見事に見えるエンハンス動画が、動きの中で崩壊することがあります。固定の比較フローを構築し、パラメータやプロンプトを変更するたびに実行してください。さもないと当て推量になり、高くつく推量をすることになります。
標準テストクリップセットを構築する
3つの短いクリップ(それぞれ5〜10秒)を選び、決して変更しないでください:
- 簡単——良好な照明、スローモーション、クリーンなソース。ほぼ完璧に見えるはずです。そうでなければどこかの設定が誤っています。
- 困難——速い動き、精細なディテール、または混合した動きの種類。補間のアーティファクトがここで現れます。
- 敵対的——画面文字、細い構造、または重度の事前圧縮。幻覚がここで明らかになります。
プロンプトやパラメータの変更ごとに3つすべてに対して実行してください。簡単なクリップには役立つが敵対的クリップを損なう変更は、改善ではありません。
この順序で比較する
- 100% ズームで並べて比較。ウィンドウに合わせる表示は使わないでください。アーティファクトが隠れます。同じクロップ領域を確認してください:顔、文字領域、高モーション領域。
- フレームごとにスクラブ。速い動きの部分をフレーム単位で進め、ゴースト、歪み、ちらつきを探してください。
- 実時間速度で再生。多くのアーティファクトはフレームスクラブでは消え、動きの中で現れます。逆もまた然り。両方を見てください。
- 文字可読性チェック。エンハンス版の各字幕をソースと照らして読んでください。これが最も速く使える客観的な合否チェックです。
品質とコストを両立させる
課金はエンドポイントが行う作業に従います——出力の長さと解像度が駆動要因です。現在の料金はウェブサイトの価格パネルで確認してください。実際の帰結:長いクリップによるわずかな品質向上は、短いクリップによる明確な向上よりも取引として見合わないことが多いです。候補の設定ごとに、生成した出力の長さと解像度を記録し、目に見える改善がその費用に見合うか問いかけてください。勝者を残し、他は捨て、エンドポイントを自動化パイプラインに接続する前に、1つの設定を凍結して記録してください——プロンプト、パラメータ、テスト結果——そうすれば将来の変更をそれに対して測定できます。
よくあるリクエスト問題のトラブルシューティング
topaz-upscale/video との統合上の摩擦の大半は少数のカテゴリに分類できます。この順序で1つずつ対処してください。
認証とアクセス
401 はキーが欠落、不正な形式、または送信されていないことを意味します——環境変数がエディタ内だけでなく、実際にコマンドを実行するシェルで設定されているか確認してください。403 は通常、キーは有効だがアカウントにこのモデルへのアクセス権がないことを意味します。モデル名が完全に topaz-upscale/video と綴られていることを確認してください。
サービスがあなたの動画を取得できない
これが最もよくある失敗です。症状:タスクが早期にダウンロードまたは入力エラーで失敗する。原因:
- URL がプライベート、または対話的ログインを要求する。
- 署名付き URL がタスクのダウンロード段階に到達する前に期限切れになる——長いキューでは特に起こりやすい。
- ホストが自動リクエストをブロックする、または遅すぎてタイムアウトする。
修正:プラットフォーム経由でファイルをアップロードし、返された識別子を参照するか、送信時に十分な有効期限の署名付き URL を生成してください。
デコード失敗
エラーがリクエストではなくメディアに言及している場合、ソースを一般的なコンテナに再ラップして再試行してください。まずローカルでファイルをテストしてください——自分のプレーヤーでも苦労するなら、サービスも同じです。
タスクが走り続ける、またはタイムアウトする
長いソースは長い時間を要し、一部のリクエストは不相応に長くかかります。再送信する前に、id でタスク状態を確認してください——見ているのは失敗タスクではなくキュー待ちタスクかもしれません。盲目的な再送信はコストを倍にしかねません。スクリプトからポーリングする場合、自分のクライアントのタイムアウトが想定タスク時間より長いことを確認してください。さもないと、まだ正常に実行中のタスクを放棄してしまいます。
出力がソースより悪く見える
リクエストは成功したが結果が過剰シャープ、プラスチック的、またはゴーストだらけ。これは API の問題ではなくプロンプトの問題です:ディテール再構築と補間のレシピに戻り、明確な上限を追加してください——「ソースと一致」「ゴーストなし」「背景は静止を保つ」。その後、標準比較セットを再実行してください。
断続的で再現しない失敗
毎回の呼び出しでリクエストボディ全体とタスク id を一緒に記録してください。両方がなければ、失敗が異なるペイロードから来たのか一時的なサービス問題から来たのか判断できません。十数件の記録された失敗があれば、パターンは通常数分で浮かび上がります。