動画からのサムネイル抽出
🤖/video/thumbs は、プレビュー用の画像を動画から任意の枚数抽出します。

smart: true を設定すると、一定間隔でフレームを取り出すだけでなく、AI でプレビューに適した画像を選択できます。この Robot は候補フレームの鮮明さ、明るさ、構図、顔、表情、動き、視覚的な魅力を採点し、評価が最も高い count フレームを時系列順に返します。スマート選択の結果には file.meta.smart_score と file.meta.smart_reasons が含まれます。AI による採点を利用できない場合、Assembly はフォールバック順の候補フレームで処理を続行し、警告を含めます。AI の認証情報は不要です。
HLG および PQ HDR 動画のフレームは、スマートサムネイルの候補も含め、画像エンコード前に SDR sRGB にトーンマッピングされます。これにより、サムネイルを sRGB 画像として表示するブラウザーでも、意図した見た目が保たれます。SDR 入力の処理は従来どおりです。
AI の料金
通常の /video/thumbs の処理料金は引き続き適用されます。AI によるフレーム解析は、利用するプロバイダーの原価に Transloadit の 50% のマークアップを加えた料金で別途請求されます。スマート選択では、/ai/chat のデフォルト設定とは独立して、専用の openai/gpt-5.4-mini ビジョンモデルと low の推論設定を使用します。実際の AI 料金は、候補フレーム数とプロバイダーの料金によって異なります。
AI は、アスペクト比を維持し、長辺を最大 512 ピクセルに制限したプレビュー用コピーを採点します。小さい画像は拡大しません。返されるサムネイルは指定された出力サイズと形式を維持します。出力サイズを大きくしても、採点用プレビューがこの上限を超えることはありません。
smart_max_candidates は、コストとレイテンシーを制御する主な設定です。この Robot は、要求されたサムネイルごとに最大三つの候補を解析します。候補数は smart_max_candidates を上限としますが、count を下回ることはありません。デフォルトの count: 8 と smart_max_candidates: 20 では、20 フレームを解析し、評価が最も高い 8 フレームを返します。AI のコストとレイテンシーを抑えるには、候補数の上限を下げてください。上限を上げると、候補数を count の最大三倍まで増やせます。それ以上に上限を上げても効果はありません。
スマート選択では count を使用してください。offsets で常に正確なタイムスタンプのフレームを抽出するには、smart: false を設定してください。
動画からのサムネイル抽出は並列で行われますが、Assembly の結果に追加する前にサムネイルを並べ替えます。そのため、結果内の表示順は動画内の順序と一致します。thumb_index メタキーでも確認できます。
アップロードからポスター画像を生成する Template、SDK の使用方法、公開時の確認事項については、HTML 動画ワークフローガイド (English)を参照してください。動画と S3 のデモ (English)には、録画済みの入力と抽出されたフレームが含まれています。
使用例
AI を使用して、アップロードされた各動画から視覚的に魅力のあるサムネイルを三つ選択します:
{
"steps": {
"thumbnailed": {
"count": 3,
"ffmpeg_stack": "v7",
"robot": "/video/thumbs",
"smart": true,
"smart_max_candidates": 12,
"use": ":original"
}
}
}パラメーター
interpolateboolean | Record<string, boolean>処理設定の各フィールドで Assembly Variables を展開するかどうかを制御します。
デフォルトでは、Robot の処理設定のほとんどのフィールドで Assembly Variables が展開されます。すべての設定フィールドをリテラルテキストとして扱うには、このパラメーターを
falseに設定してください。特定のフィールドだけをリテラルテキストとして扱うには、そのフィールドのパスをfalseに設定してください。デフォルトでリテラルとして扱われる Robot 固有のフィールドで展開を有効にするには、このパラメーターをtrueに設定するか、そのフィールドのパスをtrueに設定してください。pathのようなフィールド名を使用してください。ネストされたオブジェクトには、ffmpeg.vfのようなドット区切りのパスを使用してください。output_metaRecord<string, boolean> | boolean | Array<string>算出に多くの CPU リソースを要するメタデータを指定できます。Assembly の処理速度を維持するため、これらはデフォルトで無効になっています。
画像の場合、このオブジェクトに
"has_transparency": trueを追加すると、画像に透明な部分が含まれるかどうかを抽出できます。"dominant_colors": trueを追加すると、画像から 16 進数のカラーコードの配列を抽出できます。画像の場合、
"blurhash": trueを追加すると、画像のプレースホルダーをコンパクトに表す BlurHash 文字列も抽出できます。画像全体の読み込み中に、ぼかしたプレビューを表示するのに役立ちます。画像の場合、代わりに
"thumbhash": trueを使用すると、base64 エンコードされた ThumbHash をmeta.thumbhashに抽出し、meta.has_alpha(完全に不透明な場合も含め、アルファチャンネルが存在するかどうか)も抽出します。ThumbHash は EXIF の向きを反映したピクセルを表し、アニメーション画像では最初のフレームを使用します。抽出はベストエフォートです。40 メガピクセルを超える画像、非対応の形式、デコードの失敗やデコード処理の上限への到達があった場合、プレースホルダーは生成されません。抽出に成功すると、そのファイルのバイト数の 20% に相当するメタデータ料金が加算されます。無効な場合やハッシュが生成されない場合、ThumbHash の追加料金は発生しません。このオプションは画像を生成する Step に設定してください。たとえば、アップロードされた元画像では
/upload/handle、処理済みの出力では/image/resizeに設定します。/transloadit/storeにのみ設定しても、抽出は要求されません。ストレージは生成元のメタデータを保持します。Transloadit Storage は生成されたハッシュをその不変のバージョンとともに永続化し、保存済みの結果やネイティブのアセット読み取り時に返します。S3 への直接アップロードではプレースホルダーは生成されません。プレースホルダーには画像情報が含まれるため、画像全体と同じアクセス制御で保護してください。動画の場合、
"colorspace": trueパラメーターを追加すると、出力動画の色空間を抽出できます。動画の場合、
"interlaced": trueを追加すると、インターレース動画かどうかも検出できます。これは、低コストの ffprobe のfield_orderフラグと、ソースの先頭フレームに対する処理範囲を制限したidetサンプリング処理を組み合わせ、file.metaの下にinterlaced、field_order、診断用のinterlace_detectionオブジェクトを出力します。この処理は計算コストが高く、それに応じて課金されます。音声の場合、
"mean_volume": trueを追加すると、音声ファイルの平均音量を表す単一の値を取得できます。また、
falseに設定すると、メタデータの抽出をスキップしてトランスコードを高速化できます。user_metaRecord<string, any>(デフォルト:{})出力される各ファイルに、ファイルの内容を変更せずにカスタム JSON メタデータを追加します。ネストしたオブジェクトと配列に対応しています。
継承の動作は Robot によって異なります。値は出力ファイルの既存の
user_metaとマージされ、一致するトップレベルのキーは現在の Step によって置き換えられます。Robot が新しい出力を作成する場合は、必要なキーを明示的に割り当ててください。処理 Step では、
${file.*}は最初の入力を、${result.*}は出力されるファイルを参照します。値は Robot の実行後、後続のメタデータ抽出と一時保存の前に、出力ごとに評価されます。:originalでは、メタデータ抽出の前にアップロードごとに値が評価されます。後続の Step は
${file.user_meta.key}を読み取ります。完全な例と継承ルールについては、カスタムメタデータ を参照してください。resultboolean(デフォルト:false)この Step の結果を Assembly Status JSON に含めるかどうか
queuebatchqueue を 'batch' に設定すると、このステップのジョブの優先度を手動で下げ、キューの待ち時間がゼロである必要のないジョブが優先ジョブスロットを消費しないようにします。
force_acceptboolean(デフォルト:false)通常は無視するファイルタイプを Robot に強制的に受け入れさせます。
デフォルトでは、Robot は認識できないファイルを無視します。たとえば、🤖/video/encodeは入力画像を無視します。
force_acceptパラメーターをtrueに設定すると、Robot に渡されたすべてのファイルを強制的に受け入れさせることができます。通常、この設定はエラーにつながるため、デバッグやエッジケースへの対処にのみ使用してください。ignore_errorsboolean | Array<meta | execute>(デフォルト:[])処理の特定のフェーズでエラーを無視します。
このパラメーターを
["meta"]に設定すると、Robot はメタデータ抽出中のエラーを無視します。このパラメーターを
["execute"]に設定すると、Robot はメイン実行フェーズ中のエラーを無視します。このパラメーターを
trueに設定すると、["meta", "execute"]と同じ動作になり、両方のフェーズでエラーを無視します。usestring | Array<string> | Array<object> | object入力として使用する Step を指定します。
- Step には任意の名前を付けられます。ただし、
":original"は Transloadit が処理するユーザーアップロード用に予約されています。 - 配列を使用して、複数の Step を入力として指定できます。
{ "use": [ ":original", "encoded", "resized" ] } - 入力 Step に
asでタグを付けて、意味上の用途を Robot に伝えることもできます。{ "use": [ { "name": ":original", "as": "image" }, { "name": ":original", "as": "mask" } ] }
ヒントuseについては、通常ここまでの内容で十分ですが、高度な使用例 も参照できます。- Step には任意の名前を付けられます。ただし、
ffmpegobjectFFmpeg に渡すパラメーターオブジェクトです。プリセットを使用する場合、ここで指定したオプションがプリセットのオプションに上書きマージされます。利用可能なオプションは、FFmpeg ドキュメントを参照してください。ここで指定したオプションは、プリセットのオプションよりも優先されます。
ffmpeg_stackv6 | v7 | v8 | string(デフォルト:"v6.0.0")エンコードに使用する FFmpeg スタックのバージョンを選択します。現在は「v7」の使用を推奨しています。「v6.0.0」、「v7.0.0」、「v8.0.0」という正確なバージョン指定は、後方互換性のために引き続き受け付けられるレガシー値です。非推奨の「v5.x」の値も受け付けられます。
countstring | number(デフォルト:8)抽出するサムネイルの数です。動画の長さが正しくない場合があるため、まれに実際に生成されるサムネイルの数が指定数を下回ることがあります。現在許可されているサムネイル数の上限は 999 です。
smartがfalseの場合、サムネイルは一定間隔で抽出されます。たとえば、数を 3 にすると、動画の 25%、50%、75% の位置でサムネイルが生成されます。smart: trueの場合は、候補群から選択するサムネイルの数になります。特定のタイムスタンプのサムネイルを抽出するには、
offsetsパラメーターを使用してください。offsetsArray<string | number> | Array<string> | nullファイル内の位置を秒単位で表すオフセットの配列です。たとえば
[ 2, 45, 120 ]のように指定します。小数を使うと、ミリ秒単位の位置も指定できます。たとえば 1250 ミリ秒のオフセットは1.25と表します。[ "2%", "50%", "75%" ]のようなパーセント値も指定できます。smartがfalseの場合、offsetsがcountより優先されます。動画の再生時間内のタイムスタンプを指定してください。指定したオフセットで FFmpeg がフレームを生成しない場合、Robot はタイムスタンプによるシークを行わずに再試行し、代わりに冒頭付近のフレームを返すことがあります。単にオフセットを無視するわけではなく、利用できるフレームがなければ抽出が失敗することもあります。smartがtrueの場合、スマート選択ではoffsetsを無視し、countを使って独自の候補タイムスタンプから選択します。スマート選択の候補を抽出できない場合、Robot は通常の抽出にフォールバックし、その際はoffsetsが優先されます。指定したタイムスタンプを常に抽出するには、smart: falseを使ってください。タイムスタンプの選択を
countとsmartに任せるには、nullを使ってください。formatjpeg | jpg | png(デフォルト:"jpeg")抽出するサムネイルの形式です。指定できる値は
"jpg"、"jpeg"、"png"です。形式に"jpeg"を指定しても、生成されるサムネイルのファイル拡張子は"jpg"になります。widthstring | number | nullサムネイルの幅(ピクセル単位)です。動画の元の幅を使う場合は、省略するか
nullを指定します。heightstring | number | nullサムネイルの高さ(ピクセル単位)です。
widthと同様の上限が適用されます。元の高さを使う場合は、省略するかnullを指定します。resize_strategycrop | fit | fillcrop | min_fit | pad | stretch(デフォルト:"pad")利用可能なリサイズ方式のいずれかを指定します。
backgroundstring(デフォルト:"#000000ff")"pad"リサイズ方式を使用する場合の、生成されるサムネイルの背景色です。"rrggbbaa"形式(赤、緑、青、アルファ)で指定します。デフォルトは不透明な黒です。rotate0 | 90 | 180 | 270 | 360(デフォルト:0)指定した整数の角度で動画を強制的に回転させます。現在は 90 の倍数のみ対応しています。カメラが向きの情報を提供する多くの動画では、向きを自動補正します。このオプションは、カメラが向きを検出しなかったために回転が必要な動画でのみ役立ちます。
input_codecstring動画のデコードに使う入力コーデックを指定します。特定のデコーダーを必要とする特殊なコーデックの動画に役立ちます。
smartboolean(デフォルト:false)trueに設定すると、AI によるスマートなサムネイル選択が有効になります。Robot は一定間隔のサムネイルを返す代わりに、候補フレームを分析し、視覚的に最も魅力的なものを選択します。AI は次の基準でフレームを評価します。
- 視覚的な鮮明さ(ぼやけたフレームや暗いフレームを回避)
- 構図の質
- 顔の有無と表情
- アクションと動き(場面切り替え中のフレームを回避)
- 全体的な視覚的魅力
通常の
/video/thumbs処理料金も適用されます。AI によるフレーム分析には、lowの推論設定を使う専用の低コスト画像認識モデルと、長辺を最大 512 ピクセルに制限したプレビュー用コピーを使用します。返されるサムネイルは、指定されたサイズと形式を維持します。分析料金は別途請求され、基盤プロバイダーの原価に Transloadit の 50% のマークアップを加算した金額になります。AI の認証情報を用意する必要はありません。スマートモードは、一定間隔の候補タイムスタンプを独自に生成します。特定のタイムスタンプが必要な場合は、
smart: falseとoffsetsを併用してください。スマート選択されたサムネイルは、スコア順ではなく時系列順で返されます。選択結果を評価する際は、meta.thumb_offset、meta.smart_score、meta.smart_reasonsを確認してください。AI によるスコアリングが失敗した場合、Robot は抽出済みの候補を時系列順に選択し、フォールバックの理由を記録します。候補がない場合は、通常の抽出を試みます。どちらのフォールバックでも Assembly に警告が追加されます。Assembly が完了しても、内容を代表するポスター画像や、安全に公開できるポスター画像が得られるとは限りません。出力が存在することを確認し、アプリケーションのレビューポリシーを適用してください。
smart_max_candidatesstring | number(デフォルト:20)smartがtrueの場合の候補プールの最大サイズです。Robot は、リクエストされたサムネイルごとに最大三つの候補を、この値を上限として分析します。ただし、分析する候補数が、リクエストされたcountを下回ることはありません。値を大きくすると、よりよい結果が得られる可能性がありますが、処理時間と AI のコストが増加します。デフォルトの
count: 8とsmart_max_candidates: 20では、Robot は 20 フレームを分析し、最良の 8 フレームを時系列順で返します。この上限を
countの三倍より大きくしても、候補プールは拡大しません。たとえば、count: 1では最大三つの候補を分析します。このパラメーターは、
smartがtrueの場合にのみ使用されます。