Transloadit
料金
  • ファイルアップロード
  • ファイルインポート
  • バッチ処理
  • 動画エンコーディング
  • 音声エンコーディング
  • 画像処理
  • ドキュメント処理
  • 人工知能
  • ファイルフィルタリングとセキュリティ
  • メディアカタログ化
  • ファイル圧縮
  • コード評価
  • ファイルエクスポート
  • Smart CDN
  • すべてのサービスを表示
  • 連携機能を見る
  • 実行可能なデモを試す (English)
  • Uppy
  • TransloaditKit
  • Android 用 SDK
  • Node.js 用 SDK
  • Next.js 用ビューアー
  • Python 用 SDK
  • Ruby 用 SDK
  • Go 用 SDK
  • Java 用 SDK
  • PHP 用 SDK
  • Zapier
  • MCP サーバー
  • Transloadit CLI
  • Terraform
  • 基本事項
  • ベストプラクティス
  • よくある質問
  • Robot
  • API
  • 形式
  • 初めてのアプリ開発
  • 会社概要
  • 比較
  • オープンソース
  • お客様の声
  • 採用情報 (English)
  • セキュリティ
  • 記事
  • 開発者ニュース (English)
  • 開発のヒント
  • プレス
  • 研究 (English)
  • 導入事例
  • ソリューション
  • ガイド (English)
  • 用語集
  • 法務 (English)
  • ツール
  • 世界中の数百万人に教育を届ける Coursera を支援
  • Transloadit サポート
  • オープンソースサポート
  • サービスレベル契約 (English)
  • エンジニアによるデモを予約 (English)
基本事項Robotよくある質問API形式ベストプラクティス
トピック
  • エンドポイント
  • レスポンスコード
  • 認証
  • ウェブフック
  • メタデータ
  • API のセキュリティ
  • レート制限
  • キュー
  • 再開可能なアップロード
認証
  • Bearer トークンを作成する
  • 新しい Auth Key を作成する
  • Auth Keys の一覧を取得する
  • Auth Key のスコープを取得する
  • Auth Key を編集する
  • Auth Key を削除する
  • Auth Key のシークレットを取得する
Assemblies
  • 新しい Assembly を作成する
  • Assembly Status を取得する
  • 指定された ID で Assembly を作成する
  • Assembly の変更をリアルタイムでストリーミングする
  • 実行中の Assembly をキャンセルする
  • Assembly を再実行する
  • Assemblies の一覧を取得する
  • Assembly Status レスポンス
  • Assembly の統計情報を取得する
ウェブフック
  • Assembly Notifications を取得する
  • Assembly Notification を再送する
請求
  • 対象月の請求書を取得する
キュー
  • 現在使用中の Priority Job Slots を取得する
  • Priority Job Slots の統計を取得する
再開可能なアップロード
  • tus の機能を確認する
  • tus アップロードを作成する
  • tus アップロードのオフセットを取得する
  • tus ファイルのバイト列をアップロードする
  • tus アップロードを終了する
  • tus アップロードをダウンロードする
Template 認証情報
  • 新しい Template 認証情報を作成する
  • Template 認証情報を取得する
  • Template 認証情報を編集する
  • Template 認証情報を削除する
  • Template 認証情報の一覧を取得する
  • Template 認証情報の種類を取得する
Templates
  • 新しい Template を作成する
  • Template を取得する
  • Template を編集する
  • Template を削除する
  • Templates の一覧を取得する
  • Cron Template の実行履歴を取得する alpha
デジタルアセット管理
  • DAM アセットを移動するか、名前を変更する alpha
  • DAM アセットを削除 alpha
  • DAM アセットを一括移動する alpha
  • DAM アセットを一括削除する alpha
  • ストレージ内のファイルまたはフォルダーを移動 alpha
  • ストレージ内のアセットを取得
  • ストレージ内のアセットを一覧表示

再開可能なアップロード

ユーザーがデバイスからファイルをアップロードしているときに、ネットワークの中断やサーバーの問題が発生すると、アップロードが失敗し、通常はファイル全体の再送信が必要になることがあります。再開可能なアップロードは、こうした中断からシームレスに復旧でき、より堅牢で効率的かつ快適なユーザー体験を提供します。

Transloadit には、サーバーにファイルをアップロードする方法が 2 つあります。

  1. Assembly の作成時に、multipart/form-data の POST リクエストにファイルを含めることができます。このリクエストが中断されると、アップロードと Assembly が失敗します。
  2. tus の再開可能なアップロードプロトコル⁠を使ってファイルをアップロードできます。ネットワークやサーバーの問題からアップロードを復旧でき、ユーザーは必要に応じてアップロードを一時停止したり再開したりすることもできます。tus は、HTTP 経由でファイルを再開可能な形でアップロードするための、オープンで無料のプロトコルです。利用できるオープンソースのクライアント実装⁠が多数あります。

このドキュメントでは、2 つ目の再開可能な方式で使用する API について説明します。この方式は 2 つのステージで構成されており、それぞれをこのドキュメントで説明します。

アップロード → 処理 → 非公開ストレージという流れの例と、制御された中断テストの手順については、ファイルアップロードガイドの大容量動画ワークフロー EN (English)を参照してください。転送を再開しても、処理やエクスポートの成功が保証されるわけではありません。Assembly ID を保持し、終了時の Assembly Status を確認して、保存された出力を検証してからアセットを公開してください。クライアントのリトライ設定とリロード後の復旧は、tus プロトコル自体とは別のものです。

Java クライアントの例については、DevTip の tus-java-client を使った再開可能なファイル転送を参照してください。ファイルアップロードのチュートリアル EN (English)では、HTML フォームやカスタムのブラウザーインターフェースも取り上げています。

補足

Node SDK や Uppy など、既製の連携機能の多くは、ファイルのアップロードに内部でデフォルトで tus を使用しています。これらを使用している場合は、再開可能なアップロードを自分で実装する必要はありません。このドキュメントは、SDK を開発したい方、tus 連携のない SDK を使用したい方、または Transloadit が提供する SDK をまったく使用しない方を対象としています。

ステージ 1: 新しい Assembly を作成する

新しい Assembly は、Assemblies を作成するためのエンドポイントに multipart/form-data の POST リクエストを送信することで作成されます。従来のアップロードでは、すべてのファイルをこのリクエストの追加パートとして含めます。再開可能なアップロードでは、クライアントはこのリクエストにファイルを含めず、アップロードするファイルの数だけを Transloadit API に伝えます。

これを行うには、マルチパート POST リクエストに num_expected_upload_files フィールドを追加します。この値は、クライアントがこの Assembly にアップロードしたいファイルの数です。params など、Assembly Instructions を制御するための追加フィールドも含める必要があります。

次のスニペットは HTTP リクエストの例です。クライアントは、認証の詳細と Assembly Instructions を params フィールドに指定します。num_expected_upload_files フィールドは、クライアントが 2 つのファイルをアップロードしたいことを示しています。ただし、これらのファイルの実際の内容は、このリクエストには含まれていません。

POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIAWBI8vxocZzsG03

------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="params"

{"auth":{"key":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"},"steps":{"encode":{"robot":"/image/resize"}}}
------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="num_expected_upload_files"

2
------WebKitFormBoundaryIAWBI8vxocZzsG03--

Assembly の作成に成功すると、API は対応する Assembly Status レスポンスを返します。次のスニペットはその例です。

{
    "ok": "ASSEMBLY_UPLOADING",
    "assembly_id": "b841ea401e1a11e7b37d7bda1b503cdd",
    "assembly_ssl_url": "https://api2-freja.transloadit.com/assemblies/b841ea401e1a11e7b37d7bda1b503cdd",
    "websocket_url": "https://api2-freja.transloadit.com/ws20277",
    "tus_url": "https://api2-freja.transloadit.com/resumable/files/",
    "expected_tus_uploads": 2,
    "started_tus_uploads": 0,
    "finished_tus_uploads": 0,
    // …
}

Assembly がアップロード中の状態にあり、アップロードを受け入れる準備ができていることがわかります。レスポンスには、この Assembly を一意に識別する assembly_ssl_url プロパティが含まれています。また、ファイルのアップロード先エンドポイントを定義する tus_url プロパティも含まれています。expected_tus_uploads、started_tus_uploads、finished_tus_uploads の各プロパティは、Transloadit がこの Assembly で受け入れる予定のファイル数と、開始済みおよび完了済みのアップロード数を示します。

ステージ 2: 各ファイルをアップロードする

最初のステージで Assembly を作成すると、クライアントは Transloadit の再開可能なアップロードサーバーへのファイルのアップロードを開始できます。

補足

Transloadit は最大 200 GB のファイルサイズをサポートしています。アプリケーションでより高い上限が必要な場合は、お問い合わせください。

Transloadit は、tusd ソフトウェアを使用して tus⁠ サーバーを稼働させています。その URL は、最初のステージで説明したように、Assembly Status の tus_url プロパティで提供されます。この tus アップロードサーバーはプロトコル仕様⁠に準拠しており、tus クライアントからファイルをアップロードできます。仕様に従って独自の tus クライアントを実装することも、使用するプログラミング言語に対応したオープンソースのクライアント実装⁠を選ぶこともできます。

tus を使ったアップロードは、次の 2 つの手順で進みます。

  1. まず、tus サーバー上にアップロードリソースを作成します。クライアントは POST リクエスト⁠を送信し、Assembly URL、ファイル名、fieldname メタデータを含めます。サーバーは、クライアントが実際のファイル内容をアップロードできるアップロード URL を返します。
  2. アップロード URL を受信すると、クライアントはこのエンドポイントにファイル内容を含む PATCH リクエスト⁠を送信し、実際のアップロードを行います。ファイル全体の転送が完了すると、tus サーバーは、追加のやり取りを必要とせずに、そのファイルを処理のために Assembly にシームレスに渡します。

このやり取りの厳密なセマンティクスについて詳しくは、プロトコル仕様⁠を参照してください。次のセクションでは、Transloadit との連携に関係する部分に焦点を当てます。

アップロードの作成

最初の手順では、tus_url で指定されたエンドポイントに POST リクエストを送信して、tus サーバー上にアップロードリソースを作成します。アップロードを先ほど作成した Assembly に関連付けるには、特別なメタデータを含める必要があります。メタデータには、次の 3 つの値がすべて必要です。

  • assembly_url: 最初のステージで、Assembly Status の assembly_ssl_url プロパティから取得した Assembly URL
  • filename: ファイルの名前
  • fieldname: HTML フォームの入力フィールド名に相当するもの

追加のメタデータはすべて、file.user_meta 内の Assembly Variable になります。これを使うと、Assembly 内のすべてのファイルで共有される fields の代わりに、Template 内で ファイルごと に動的な処理を行えます。検出された内容に応じて分岐する必要がある場合は、${file.mime} を優先して使い、image/*、video/*、audio/* などの MIME ファミリーと照合してください。${file.type} も、Assembly Status レスポンス内でファイルの大まかなカテゴリとして利用できます。その値は、"audio"、"document"、"image"、"office"、"pdf"、"swf"、"video"、"xls" のいずれかで、カテゴリが検出されなかった場合は null です。利用側では、将来のカテゴリとの互換性を保つために、ほかの文字列値も受け入れるようにしてください。通常は、MIME による照合のほうがより厳密な確認方法です。

次のリクエスト例では、サイズが 10,000 バイトの isaac.png という名前のファイルを、ID が b841ea401e1a11e7b37d7bda1b503cdd の Assembly に、フィールド名 file-input でアップロードしています。Base64 を使ったメタデータのエンコードの詳細は、プロトコル仕様⁠に記載されています。

POST /resumable/files/ HTTP/1.1
Content-Length: 0
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Length: 10000
Upload-Metadata: assembly_url aHR0cHM6Ly9hcGkyLWZyZWphLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzL2I4NDFlYTQwMWUxYTExZTdiMzdkN2JkYTFiNTAzY2Rk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==

正しいリクエストに対して、サーバーはアップロードリソースを作成し、そのアップロード URL を Location ヘッダーで返します。次に例を示します。

HTTP/1.1 201 Created
Tus-Resumable: 1.0.0
Location: https://api2-freja.transloadit.com/resumable/files/136058f2ef4dc9de3f5c23ceed591545

データ転送

アップロードの作成後、クライアントは PATCH リクエストを使って、実際のファイル内容を tus アップロード URL にアップロードする必要があります。

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Length: 10000
Content-Type: application/offset+octet-stream

[content of file]

1 つの tus アップロードが完了すると、Transloadit は、Assembly の作成時に使用したパラメーターを使って、そのファイルを自動的に処理します。特別な操作は必要ありません。すべての tus アップロードが完了するまで、すでに一部のファイルの処理が完了していても、Assembly は ASSEMBLY_UPLOADING 状態のままになります。

これらの手順を、クライアントがアップロードしたい各ファイルについて繰り返します。クライアントは、アプリケーションのニーズに応じて、これらのファイルを並列にアップロードするか、順番にアップロードするかを自由に選択できます。

予定アップロード数は、アップロードを完了する必要があるファイル数を Assembly に伝えるものであり、作成できる tus アップロードリソース数の厳密な上限ではありません。アップロード作成のレスポンスが失われた場合にクライアントが復旧できるように、Assembly のアップロード中は追加のリソースが許容されます。進捗カウンターでは、放棄されたリソースを除き、進捗が最も進んでいるアップロードを予定数分使用します。意図したファイルのみをアップロードし、再開時には既知の各アップロード URL を再利用してください。Assembly が ASSEMBLY_UPLOADING 状態でなくなると、新しいアップロードの作成は拒否されます。

再開

ネットワークの中断やユーザーによるアップロードの一時停止によってデータ転送が失敗した場合、クライアントは停止した位置からアップロードを再開できます。

まず、クライアントはアップロード URL に HEAD リクエストを送信して、中断前にサーバーがどれだけのデータを受信できたかを確認します。

HEAD /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0

レスポンスの Upload-Offset ヘッダーには、受信済みのバイト数が含まれます。たとえば、次のレスポンスは、10,000 バイトのうち 3,000 バイトを受信済みのアップロードを示しています。

HTTP/1.1 200 OK
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Upload-Length: 10000

続いて、別の PATCH リクエストを使って、残りの 7,000 バイトをアップロードできます。

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream

[remaining content of file]

tus を使った再開可能なアップロードの詳細については、tus FAQ⁠を参照してください。

前のページ ← キュー次のページ Bearer トークンを作成する →
サポートに問い合わせる
Transloadit稼働状況を確認中…

製品

  • サービス
  • 料金
  • デモ EN (English)
  • ツール
  • セキュリティ
  • サポート

会社

  • 会社概要/プレス
  • ブログ/採用情報 EN (English)
  • 比較/コンプライアンス対応表
  • 研究 EN (English)
  • オープンソース
  • ソリューション
  • ウェブの先駆者たち

ドキュメント

  • はじめに
  • トランスコーディング
  • よくある質問
  • API
  • ガイド EN (English)/開発のヒント
  • 対応フォーマット

その他

  • プラットフォームの稼働状況⁠
  • コミュニティフォーラム⁠
  • Uppy
  • tus⁠

© 2009–2026 Transloadit-II GmbH

Transloadit®、tus®、Uppy® は、米国における Transloadit-II GmbH の登録商標です。

プライバシー EN (English)利用規約 EN (English)運営者情報 EN (English)商標 EN (English)DMCA ポリシー EN (English)
EnglishDeutschEspañolFrançaisPortuguês (Brasil)日本語