Use https://app-gateway.realsee.ai from your backend. Argus shares the Team-owned Developer app's /open scope. Send the raw gateway access token in the Authorization header, without a Bearer prefix.
| Method | Path | Purpose |
|---|---|---|
POST | /auth/access_token | Exchange AK/SK for a gateway token. |
GET | /open/v1/argus/file/token | Get temporary credentials for uploading the input ZIP. |
POST | /open/v1/argus/task/submit | Submit uploaded object keys and get a task_code. |
GET | /open/v1/argus/task/info | Query that task and its temporary result download metadata. |
Responses use a gateway envelope. HTTP success alone does not mean business success: require numeric code: 0 and valid data before reading fields. Error responses may have data: null.
{
"code": 0,
"status": "success",
"data": {}
}Trace and timing fields may also appear. Do not log the full response: it can contain temporary credentials or download URLs.
Get a gateway token
POST /auth/access_token, with Content-Type: application/x-www-form-urlencoded:
app_key=<app_key>&app_secret=<app_secret>| Response data | Type | Meaning |
|---|---|---|
access_token | string | Short-lived raw token for subsequent requests. |
expire_at | integer | Unix token-expiry timestamp in seconds. |
Keep the app secret and token on your backend. Obtain a current token before authenticated requests.
Get file-upload credentials
GET /open/v1/argus/file/token has no business query parameters or request body.
GET /open/v1/argus/file/token
Host: app-gateway.realsee.ai
Authorization: <access_token>The upload lease is returned directly under data:
| Field | Type | Meaning |
|---|---|---|
tmpSecretId, tmpSecretKey, sessionToken | string | Temporary storage credentials. Do not persist or log them. |
bucket, region | string | Storage destination. |
prefix | string | Authorized object-key prefix. |
expire, ttl | number | Credential-expiry information and lifetime returned by the service. These are distinct from the task result's expiration_timestamp. |
Additional provider fields can be present. Pass the complete lease to the upload adaptor; the Quickstart uses @realsee/universal-uploader@0.1.1 and the overseas AWS adaptor.
Package multiple 2:1 equirectangular panoramas or multiple 1:1 pinhole images in one ZIP, with images at the root. Use one image type per batch. Upload before submitting a task. Retain the uploader's full objectPath, including its prefix.
Submit a task
POST /open/v1/argus/task/submit, with 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"
}| Request field | Type | Required | Meaning |
|---|---|---|---|
private_cos_keys | string[] | Yes | Nonempty array of full uploaded object keys. Pass the full key for the input ZIP. Keys must belong to the same granted resource directory. |
title | string | Yes | Nonempty task title. |
There is no input-type parameter in this request. Do not send storage URLs instead of object keys.
A successful response includes:
{
"code": 0,
"status": "success",
"data": {
"task_code": "<task_code>"
}
}Persist task_code as the task reference. Submission is not idempotent. Do not automatically retry when a timeout or lost response leaves the outcome unknown; the task may already exist.
Query task information
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 is a required nonempty query parameter. The response's data fields are:
| Field | Type | Meaning |
|---|---|---|
status | integer | 0 queued, 1 processing, 2 task succeeded, 3 task failed. |
output_url | string | Temporary URL for output.zip after success; empty while work is pending. |
expiration_timestamp | integer | Unix expiration timestamp for that download URL, in seconds. |
error_message | string | Failure detail; usually empty when the task has not failed. |
create_timestamp, modify_timestamp | integer | Task creation and last-update timestamps. |
Continue queries for 0 or 1. For 2, require a nonempty output_url and download before expiration_timestamp. For 3, stop and handle the failure. Retain the task code when a local waiting deadline expires; do not create another task merely to resume waiting.
Reconstruction products
File in output.zip | Product |
|---|---|
output.json | Required manifest, image-name mapping, relative product paths, and algorithm result status. |
depth/*_depth.exr | Per-image 32-bit floating-point depth maps in meters. |
pointcloud/merged.glb | Merged point cloud; right-handed, Y-up coordinates. |
pose/*_pose.json | Per-image world-to-camera rotation and translation. |
intrinsics/*_intrinsics.json | Optional camera calibration; interpret the actual returned model. |
Task success does not guarantee that every input image reconstructed. Read output.json.status: success, partial, or error. A partial result identifies unsuccessful images in missing_ids; map IDs back to filenames with name_mapping.
See Outputs and Result Handling for full semantics and validation. A GLB point cloud is not a complete Realsee VR project or Five SDK Work payload. Pano-to-VR uses a separate API for that workflow.
Do not treat a temporary result URL as permanent storage or assume a fixed seven-day lifetime. Store downloaded files under your own access controls. Keep AK/SK, tokens, temporary upload credentials, result URLs, and raw task diagnostics out of frontend logs and analytics.