API Reference — Argus | Realsee Developer Platform

Argus requests use the overseas app gateway:

https://app-gateway.realsee.ai

The gateway exposes four endpoints for the current reconstruction flow:

Method	Path	Content type	Purpose
`POST`	`/auth/access_token`	`application/x-www-form-urlencoded`	Exchange reviewed app credentials for an Argus gateway access token.
`POST`	`/open/saas/v1/vggt/upload/token`	`application/json`	Create or continue an `input_image_id` upload session and return temporary upload credentials.
`POST`	`/open/saas/v1/vggt/trigger`	`application/json`	Trigger Argus/VGGT reconstruction for an uploaded image.
`GET`	`/open/saas/v1/vggt/poll`	query string	Poll task status and output metadata.

The response envelope follows the gateway convention:

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

Auth token

POST /auth/access_token

This endpoint is scoped to the Argus gateway. Do not confuse it with any regular OpenAPI auth endpoint with the same path name.

Request

POST /auth/access_token
Host: app-gateway.realsee.ai
Content-Type: application/x-www-form-urlencoded

app_key=<reviewed_app_key>&app_secret=<reviewed_app_secret>

Response

{
  "code": 0,
  "status": "success",
  "data": {
    "access_token": "eyJ..."
  }
}

Keep both the app secret and returned access token server-side.

Upload token

POST /open/saas/v1/vggt/upload/token

Create or continue an upload session for one panorama.

Send an empty input_image_id to create a session. Reuse the non-empty identifier returned by the gateway when refreshing credentials or making later trigger and poll requests.

Request

POST /open/saas/v1/vggt/upload/token
Host: app-gateway.realsee.ai
Authorization: <argus_access_token>
Content-Type: application/json

{
  "input_image_id": ""
}

Response

{
  "code": 0,
  "status": "success",
  "data": {
    "input_image_id": "2aa48574-86a7-41ae-9643-000000000000",
    "upload_token": {
      "tmpSecretId": "...",
      "sessionToken": "...",
      "tmpSecretKey": "...",
      "ttl": "3600",
      "prefix": "...",
      "expire": 1784089762,
      "app_id": "...",
      "bucket": "...",
      "region": "...",
      "is_accelerate": "0",
      "host": "...",
      "primaryid": "...",
      "download_type": "presign",
      "download_host": "...",
      "custom_domain": "",
      "custom_scheme": "https"
    }
  }
}

Pass data.upload_token directly to @realsee/universal-uploader@0.1.1. Install cos-js-sdk-v5@1.8.3 with it when using the COS adaptor. The lower-camel-case fields match the package's UploadToken type. Upload the panorama as panoImage.jpg.

Trigger

POST /open/saas/v1/vggt/trigger

Start reconstruction after upload succeeds.

Request

POST /open/saas/v1/vggt/trigger
Host: app-gateway.realsee.ai
Authorization: <argus_access_token>
Content-Type: application/json

{
  "input_image_id": "2aa48574-86a7-41ae-9643-000000000000",
  "type": "pano"
}

The type enum is pinhole | pano. Use pano for an equirectangular panorama and only use pinhole for a workflow explicitly provisioned for ordinary perspective images.

Poll

GET /open/saas/v1/vggt/poll

Poll with the same input_image_id and type.

Request

GET /open/saas/v1/vggt/poll?type=pano&input_image_id=2aa48574-86a7-41ae-9643-000000000000
Host: app-gateway.realsee.ai
Authorization: <argus_access_token>

Status handling

Status	Meaning	Client behavior
`pending`	The task is queued.	Continue polling with backoff.
`success`	Output is ready.	Read the returned output URL or metadata.
`failed`	The task failed.	Stop polling and show retry or support guidance.

Response data

Field	Required	Description
`status`	Yes	`pending`, `success`, or `failed`.
`alg_task_id`	No	Gateway task identifier when returned.
`result_url`	No	Output URI. The schema does not define its media type or Five SDK compatibility.
`failed_reason`	No	Failure detail when the task cannot complete.

Preserve the full response payload in server logs when troubleshooting, along with input_image_id, but do not log credentials or expose raw diagnostics to the browser.

Implementation notes

Direct overseas calls use https://app-gateway.realsee.ai; the domestic h5 proxy prefix /api/v1/argus is not part of this portal contract.
Argus App request review happens in the developer portal. Argus generation calls happen later through the gateway endpoints on this page.
The upload token and gateway access token are credentials. Do not expose them in static examples, frontend logs, analytics, or public error messages.
For a first implementation, keep polling server-side and return only final output metadata to the browser.