APIと統合
SuperSplat APIを使うと、アプリケーションからGaussian Splatをsuperspl.atに公開したり、認証済みユーザーが所有するシーンを一覧表示したり、IDで任意のシーンを取得したり、オーナーがダウンロードを許可しているシーンをダウンロードしたりできます。キャプチャアプリケーション、トレーニングパイプライン、変換ツール、社内コンテンツワークフローをSuperSplatに直接接続できます。
アップロードされたシーンはユーザーのManageページに表示され、編集したり、Studioで開いたり、公開シーンページから共有したりできます。
エンドポイント定義、リクエストスキーマ、レスポンス例については、SuperSplat APIリファレンスを参照してください。
APIを使用する場面
APIは次のような場合に便利です:
- SuperSplat Editorを開かずにスプラットを公開する。
- キャプチャまたは再構築アプリケーションにSuperSplat公開機能を追加する。
- トレーニングまたは変換パイプラインの出力を一括アップロードする。
- ユーザーが所有するシーンを一覧表示する。
- IDで任意のシーンを取得し、ダウンロード可能なシーンを自分のツールに取り込む。
- 接続が中断された後に大容量アップロードを再開する。
認証
すべてのAPI操作にはPlayCanvasアクセストークンが必要です。REST APIの認証を参照してトークンを作成し、Authorizationヘッダーで送信します:
Authorization: Bearer YOUR_ACCESS_TOKEN
アクセストークンは秘密情報として扱ってください。公開されるクライアント側コードに埋め込んだり、別のユーザーと共有したりしないでください。
再開可能なアップロードフロー
SuperSplatは、大容量のシーンファイルを確実に転送できるようマルチパートアップロードを使用します:
- ソース形式とオプションのシーンメタデータを指定してアップロードセッションを作成します。
- 1つ以上のファイルパート用に署名付きアップロードURLを要求します。
- 各パートをストレージへ直接アップロードします。
- 返されたパートETagを使用してアップロードを完了します。
アップロードが完了するとSuperSplatがシーンを作成します。変換と最適化が終わるまで、シーンがprocessingのままになることがあります。新しいシーンはデフォルトで限定公開です。
シーンのダウンロード
GET /v1/splats/{splatId}は、オーナーが誰であっても、また公開・限定公開を問わず、IDで任意のシーンを返します。downloadableフィールドがtrueの場合、そのシーンのオーナーはクリエイティブ・コモンズライセンス(licenseに記載)のもとでダウンロードを許可しており、contentには公開済みファイルの情報が含まれます。APIでシーンのファイルを取得する方法は、ダウンロードだけです:
POST /v1/splats/{splatId}/downloadsでダウンロードをリクエストします。その際、シーンが提供しているtargetフォーマットを指定します。statusがreadyになるまでGET /v1/splats/{splatId}/downloads/{target}をポーリングします。failedになった場合は、もう一度ダウンロードをリクエストします。POST /v1/splats/{splatId}/downloads/{target}/fileで有効期限の短いURLを取得し、urlExpiresAtより前にそのURLからのダウンロードを開始します。
target | 提供対象 | 内容 |
|---|---|---|
ply | ダウンロード可能なすべてのシーン | 標準的なPLYに変換したファイル |
sog | SOGとして公開されたシーン | 公開されたSOGファイルをそのまま |
ssog | Streamed SOGとして公開されたシーン | LODを含む、公開されたStreamed SOGファイルをそのまま |
各ダウンロードはZIPアーカイブで、ルートにファイルが置かれ、シーンのタイトル、作者、ソース、ライセンスを記載したlicense.txtが含まれます。ダウンロードは共有・キャッシュされるため、最近ほかの誰かがダウンロードしたシーンは、すぐにreadyになることがよくあります。ダウンロードは、シーンが変更されない限り有効です。シーンが再公開されたり、名前やライセンスが変更されたりすると、ダウンロードは404を返すようになるため、もう一度リクエストしてください。
ダウンロードのリクエストとポーリングは無料です。ファイルの取得はアカウントの1日あたりのダウンロード許容量にカウントされます。カウントされるのは、シーンごとにUTCの1日につき1回です。
制限
リクエストが制限を超えると、APIは429を返し、どの制限に該当するかをcodeで示します。codeのない429は、クライアントのリクエスト送信が速すぎることを意味します。
code | 意味 |
|---|---|
daily_publish_limit_reached | アカウントが今日の公開許容量を使い切りました。公開許容量は圧縮後の出力のバイト数で計測され、00:00 UTCにリセットされます。 |
too_many_processing | アカウントで同時にアップロード中または処理中にできるシーン数の上限にすでに達しています。 |
publish_in_progress | アカウントで別の公開処理を開始しているところです。 |
daily_download_limit_reached | アカウントが今日(UTC)ダウンロードできるシーン数の上限に達しました。 |
ソース形式で許可されるサイズを超えるアップロードは拒否され、許可される最大サイズが返されます。各エラーのフィールドについては、APIリファレンスを参照してください。
クライアント統合
同じAPIをエンドユーザー向け統合とカスタム自動化の両方で利用できます:
- LichtFeld Studio向けSuperSplatプラグインはPLYまたはSOGシーンを書き出し、進捗表示と再開可能なアップロードを使ってSuperSplatに公開します。
クライアントはオプションのuploadClientフィールドで自身を識別できます:
{
"uploadClient": {
"id": "example-client",
"version": "1.0.0"
}
}
uploadClientはアップロードを実行するアプリケーションに使用します。シーンの作成に使用したツールを記録する場合は、別途softwareToolsを使用します。
関連項目
- SuperSplat APIリファレンス — 完全なエンドポイントとスキーマのドキュメント
- シーンページ — superspl.atのシーンページからシーンをダウンロードする
- Direct Upload — superspl.atインターフェースからファイルを公開
- Manage — アップロード済みシーンを操作
- Studio — 公開後の視聴体験をキュレーション