API の説明 — Argus | Realsee Developer Platform

バックエンドから https://app-gateway.realsee.ai を使います。Argus は Team 所有の Developer app と共通の /open 権限を使います。Authorization には Bearer を付けず、生のゲートウェイトークンを送信します。

メソッド	パス	用途
`POST`	`/auth/access_token`	AK/SK をゲートウェイトークンと交換。
`GET`	`/open/v1/argus/file/token`	入力 ZIP 用の一時アップロード認証情報を取得。
`POST`	`/open/v1/argus/task/submit`	オブジェクトキーを送信し `task_code` を取得。
`GET`	`/open/v1/argus/task/info`	タスクと一時ダウンロード情報を照会。

HTTP 成功だけでは業務上の成功を意味しません。数値の code: 0 と有効な data を確認してから項目を読みます。エラー時は data: null の場合があります。

{
  "code": 0,
  "status": "success",
  "data": {}
}

トレースや時間の項目が含まれる場合もあります。一時認証情報や URL を含むため、応答全体をログに記録しないでください。

ゲートウェイトークンを取得する

POST /auth/access_token を Content-Type: application/x-www-form-urlencoded で送信します：

app_key=<app_key>&app_secret=<app_secret>

応答 data	型	意味
`access_token`	string	後続リクエスト用の短期トークン。
`expire_at`	integer	秒単位の Unix 有効期限。

SK とトークンをバックエンドに保持し、認証付きリクエストの前に有効なトークンを取得します。

アップロード認証情報を取得する

GET /open/v1/argus/file/token に業務用クエリや本文はありません。

GET /open/v1/argus/file/token
Host: app-gateway.realsee.ai
Authorization: <access_token>

アップロード用の認証情報は data 直下に返ります：

項目	型	意味
`tmpSecretId`, `tmpSecretKey`, `sessionToken`	string	一時ストレージ認証情報。永続保存やログ記録をしないでください。
`bucket`, `region`	string	保存先。
`prefix`	string	許可されたオブジェクトキーのプレフィックス。
`expire`, `ttl`	number	サービスが返す認証情報の期限と有効期間。タスク結果の `expiration_timestamp` とは異なります。

プロバイダー独自の項目がある場合もあります。完全な認証情報をアダプターに渡します。クイックスタートでは @realsee/universal-uploader@0.1.1 と海外向け AWS アダプターを使います。

複数の 2:1 正距円筒パノラマ、または複数の 1:1 ピンホール画像を ZIP 直下にまとめます。バッチ内の形式を統一し、送信前にアップロードします。プレフィックスを含む完全な objectPath を保持してください。

タスクを送信する

POST /open/v1/argus/task/submit を Content-Type: application/json で送信します：

POST /open/v1/argus/task/submit
Host: app-gateway.realsee.ai
Authorization: <access_token>
Content-Type: application/json

{
  "private_cos_keys": ["<full_uploaded_object_key>"],
  "title": "My reconstruction"
}

リクエスト項目	型	必須	意味
`private_cos_keys`	string[]	はい	完全なオブジェクトキーの空でない配列。入力 ZIP のキー全体を渡し、すべて同じ許可されたリソースディレクトリに属する必要があります。
`title`	string	はい	空でないタスク名。

入力形式のパラメーターはありません。オブジェクトキーの代わりにストレージ URL を送らないでください。

成功した応答には以下が含まれます：

{
  "code": 0,
  "status": "success",
  "data": {
    "task_code": "<task_code>"
  }
}

参照用に task_code を永続保存します。送信は冪等ではありません。タイムアウトや応答消失で結果が不明な場合、すでにタスクが存在する可能性があるため自動で再試行しないでください。

タスク情報を照会する

GET /open/v1/argus/task/info?task_code=<task_code>：

GET /open/v1/argus/task/info?task_code=<task_code>
Host: app-gateway.realsee.ai
Authorization: <access_token>

task_code は必須の空でないクエリです。応答の data 項目は以下です：

項目	型	意味
`status`	integer	`0` 待機、`1` 処理中、`2` 成功、`3` 失敗。
`output_url`	string	成功後の `output.zip` 用一時 URL。待機中は空。
`expiration_timestamp`	integer	ダウンロード URL の有効期限。秒単位の Unix 時刻。
`error_message`	string	失敗の詳細。失敗していない場合は通常空。
`create_timestamp`, `modify_timestamp`	integer	作成・最終更新時刻。

0 と 1 は照会を継続し、2 は空でない output_url を期限前に取得します。3 は停止して失敗に対応します。待機期限が過ぎてもコードを保持し、待機の再開だけを理由に新しいタスクを作成しないでください。

再構成の成果物

`output.zip` 内のファイル	成果物
`output.json`	必須マニフェスト、画像名対応、相対パス、アルゴリズム状態。
`depth/*_depth.exr`	画像ごとの 32 ビット浮動小数点深度。メートル単位。
`pointcloud/merged.glb`	右手系・Y 軸上方向の結合点群。
`pose/*_pose.json`	画像ごとのワールドからカメラへの回転と平行移動。
`intrinsics/*_intrinsics.json`	任意のカメラ較正。返された実際のモデルを解釈します。

タスク成功でも全画像の再構成成功は保証されません。output.json.status の success、partial、error を確認します。一部成功の失敗画像は missing_ids にあり、name_mapping でファイル名へ対応させます。

完全な意味と検証は出力と結果の処理を参照してください。GLB 点群は完全な Realsee VR プロジェクトや Five SDK Work ではありません。その生成には別 API の Pano-to-VR を使います。

結果 URL を永続ストレージとみなしたり、7 日間有効と仮定したりしないでください。取得ファイルは自分のアクセス管理下で保存します。AK/SK、トークン、一時認証情報、結果 URL、未加工の診断をフロントエンドのログや解析に含めないでください。

ゲートウェイトークンを取得する#

アップロード認証情報を取得する#

タスクを送信する#

タスク情報を照会する#

再構成の成果物#

ゲートウェイトークンを取得する

アップロード認証情報を取得する

タスクを送信する

タスク情報を照会する

再構成の成果物