ドキュメントの別形式への変換
🤖/document/convert は、ドキュメントを別の形式に変換します。

HTML から PDF への出力では、サンプリング対象の表示中のブラウザーフレームと、それらのドキュメントおよびフォントの準備が整った状態が 500 ms 続くと、印刷が始まります。ページ遷移後、PDF の準備が整うまでの上限は 30 秒です。準備が整わないページは変換に失敗します。非表示のフレームによって、準備完了と判定するまでの継続時間が延びることはありません。最後のサンプリング期間中に初めて表示されるコンテンツは、取り込まれない場合があります。動的コンテンツはキャプチャー前に準備してください。
この Robot は、対応ファイルを PDF に変換しますが、入力された PDF を他の形式には変換しません。PDF のページを画像としてレンダリングするには、🤖/image/resize を使用してください。PDF ドキュメントからのネイティブテキスト抽出や OCR には、🤖/document/extract を使用し、プロバイダーと入力の要件を確認してください。画像の OCR には、🤖/image/ocr を使用してください。これらの抽出用 Robot は認識したテキストを返します。元の PDF に検索可能なテキストレイヤーを追加するものではありません。
ファイル形式によっては、目的の処理に対応していない場合があります。たとえば、社内でドキュメントの書式設定を自動化しようとしても、処理が docx にしか対応していなければ、すべてのドキュメントを変換する必要があります。また、保存している jpg ファイルが容量を使いすぎているため、より軽量な形式にしたい場合もあるでしょう。いずれの場合も対応できます。
この Robot でファイルを最適な形式に変換すれば、特定のファイル形式に起因する問題を回避できます。他の Robot とも連携できるため、サービスをさらに幅広い用途に活用できます。
この Robot では原則として、異なるカテゴリの形式にファイルを変換しようとするとエラーになります。たとえば、SRT ファイルは VTT 形式に変換でき、その逆も可能ですが、画像には変換できません。
LibreOffice が一般的な理由で読み込みを拒否した場合、USER_COMMAND_ERROR と理由 “LibreOffice could not load the document. It may be damaged, password-protected, or in an unsupported format. If it opens elsewhere, please contact support.” を返します。これにより、ドキュメントが破損していると決めつけずに、連携先で使用するユーザーエラーコードを維持します。
診断によって変換サービスの問題が特定された場合、読み込み失敗時には INTERNAL_COMMAND_ERROR と理由 “LibreOffice could not load the document. Please contact support.” を返します。どちらのレスポンスにも非公開の診断情報は含まれません。
/speech/transcribe から "format": "json" を使用して得られるタイムスタンプ付き JSON は、SRT に変換できます。ここで "format": "srt" を設定してください。JSON 内の単語は最大 3語のキューにまとめられ、文末と 0.4 秒を超える間で区切られます。大文字と小文字の区別や句読点は維持されます。JSON 入力は 32 MiB までに制限され、SRT 出力でのみ使用できます。SRT から SRT への変換では、元のキューを変更せずにコピーします。
次のファイル形式を変換元として使用できます。
aicsvdocdocxepsgifhtmljpglatexmdodaoddodtottpngpotppspptpptxppzpsrtfrtxsrtsvgtexttxtvttxhtmlxlaxlsxlsxxml
使用例
アップロードしたファイルを PDF ドキュメントに変換します:
{
"steps": {
"converted": {
"format": "pdf",
"robot": "/document/convert",
"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 には任意の名前を付けられます。ただし、
format— 必須ai | csv | doc | docx | eps | gif | html |ドキュメントの変換先の形式を指定します。
markdown_formatcommonmark | gfm(デフォルト:"gfm")Markdown には複数の派生仕様があるため、この Robot で Markdown を HTML に変換する際は、使用している仕様のリビジョンを指定してください。
markdown_themebare | github(デフォルト:"github")このパラメーターは、用意された複数のプリセットに基づいて Markdown ファイルのスタイルを全面的に変更します。
pdf_marginstring(デフォルト:"6.25mm,6.25mm,14.11mm,6.25mm")PDF の用紙の余白を、単位付きの値を
,で区切って指定します。使用できる単位は、
px、in、cm、mmです。現在、このパラメーターは
htmlからの変換でのみ使用できます。pdf_print_backgroundboolean(デフォルト:true)PDF の背景グラフィックを印刷します。
現在、このパラメーターは
htmlからの変換でのみ使用できます。pdf_formatA0 | A1 | A2 | A3 | A4 | A5 | A6 |(デフォルト:"Letter")PDF の用紙サイズを指定します。値の大文字と小文字は区別しません。
現在、このパラメーターは
htmlからの変換でのみ使用できます。pdf_display_header_footerboolean(デフォルト:false)PDF のヘッダーとフッターを表示します。
現在、このパラメーターは
htmlからの変換でのみ使用できます。pdf_header_templatestringPDF 印刷用ヘッダーの HTML テンプレートです。
有効な HTML マークアップを使用してください。次のクラスを使うと、印刷時の値を挿入できます。
date書式設定済みの印刷日titleドキュメントのタイトルurlドキュメントの場所pageNumber現在のページ番号totalPagesドキュメントの総ページ数
現在、このパラメーターは
htmlからの変換でのみ使用でき、pdf_display_header_footerを有効にする必要があります。HTML 要素の書式を変更するには、ラッパー内で
font-sizeを指定する必要があります。たとえば、ページ上部の中央にページ番号を配置する場合、ヘッダーテンプレートには次の HTML を使用します。<div style="font-size: 15px; width: 100%; text-align: center;"><span class="pageNumber"></span></div>pdf_footer_templatestringPDF 印刷用フッターの HTML テンプレートです。
pdf_header_templateと同じ形式を使用してください。現在、このパラメーターは
htmlからの変換でのみ使用でき、pdf_display_header_footerを有効にする必要があります。HTML 要素の書式を変更するには、ラッパー内で
font-sizeを指定する必要があります。たとえば、フッターのページ番号を中央に配置する場合、フッターテンプレートには次の HTML を使用します。<div style="font-size: 15px; width: 100%; text-align: center;"><span class="pageNumber"></span></div>