# API の説明 — Argus

海外向けゲートウェイの Argus アップロード認証情報、タスク送信、タスク情報、再構成成果物を説明します。

Canonical: https://developer.realsee.ai/ja/docs/argus/reference
Source: https://developer.realsee.ai/ja/docs/argus/reference.md
Language: ja

# Argus API の説明

バックエンドから `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` の場合があります。

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

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

<span id="get-a-gateway-token" class="docs-anchor-alias" aria-hidden="true"></span>

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

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

```text
app_key=<app_key>&app_secret=<app_secret>
```

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

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

<span id="get-file-upload-credentials" class="docs-anchor-alias" aria-hidden="true"></span>

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

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

```http
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` とは異なります。 |

プロバイダー独自の項目がある場合もあります。完全な認証情報をアダプターに渡します。[クイックスタート](https://developer.realsee.ai/ja/docs/argus/quickstart) では `@realsee/universal-uploader@0.1.1` と海外向け AWS アダプターを使います。

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

<span id="submit-a-task" class="docs-anchor-alias" aria-hidden="true"></span>

## タスクを送信する

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

```http
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 を送らないでください。

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

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

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

<span id="query-task-information" class="docs-anchor-alias" aria-hidden="true"></span>

## タスク情報を照会する

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

```http
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` は停止して失敗に対応します。待機期限が過ぎてもコードを保持し、待機の再開だけを理由に新しいタスクを作成しないでください。

<span id="reconstruction-products" class="docs-anchor-alias" aria-hidden="true"></span>

## 再構成の成果物

| `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` でファイル名へ対応させます。

完全な意味と検証は [出力と結果の処理](https://developer.realsee.ai/ja/docs/argus/outputs) を参照してください。GLB 点群は完全な Realsee VR プロジェクトや Five SDK Work ではありません。その生成には別 API の [Pano-to-VR](https://developer.realsee.ai/ja/docs/pano-to-vr) を使います。

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