\r \r

Aholo 3D Reconstruction Skill — Global (OpenAPI v1)\r

\r

Scope: Aholo global Open Platform (api.aholo3d.com) 3D tasks — not 2D text-to-image.\r \r

When to use / not use (decide first)\r

\r

Use this skill when\r

\r

• The user wants 3D reconstruction (model / space)\r
• The user wants a 3D world (worldId, online preview, PLY / SPZ / SOG downloads)\r
• The user asks to query worldId status or keep polling\r \r

Do not use this skill when\r

\r

• The user only wants 2D renders / concept art / still images\r
• The user did not ask for a 3D outcome (worldId, model files, online 3D preview)\r
• The user wants general image editing or text-to-image (use image-generation capabilities)\r \r

Ambiguous requests (clarify first)\r

\r When the user says something like “generate a room in this style from a reference image”, ask:\r \r

Which do you want?\r
1) 2D room render (single image)\r
2) 3D room task (returns worldId and can be polled)\r
```\r
\r
Enter this skill’s flow only after the user clearly picks **2)**.\r
\r
Upload images or video and create 3D tasks:\r
\r
- **reconstruction**\r
- **generation** / spatial gen\r
\r
When complete, model download URLs (PLY / SPZ / SOG) may be returned.\r
\r
## Prerequisites\r
\r
Environment variable:\r
\r
- `AHOLO_API_KEY` — API Key from [labs.aholo3d.com/api-keys](https://labs.aholo3d.com/api-keys)\r
\r
Auth header: `Authorization: \x3CAPI Key>` (**no** `Bearer` prefix).\r
\r
### When `AHOLO_API_KEY` is missing (agent behavior)\r
\r
- Tell the user to set `AHOLO_API_KEY` in the terminal or system environment, then reply **“continue”** or describe the same 3D task again.\r
- **Do not** ask the user to run `python ... aholo_reconstruct.py` as the main path; the agent runs the script by default.\r
- Local debugging by the user is optional.\r
\r
## TLS verification (skipped by default)\r
\r
- SSL verification is off by default to avoid `CERTIFICATE_VERIFY_FAILED` on corporate/self-signed networks.\r
- Set `AHOLO_FORCE_SSL_VERIFY=1` to force verification on.\r
- `AHOLO_INSECURE_SKIP_VERIFY` still skips verify unless explicitly `0` / `false` / `no` / `off`.\r
\r
## Service endpoints\r
\r
- API gateway: `https://api.aholo3d.com`\r
- Upload host: from `GET /global/world/v1/asset/token` → `globalDomain` (OUS direct upload; response uses OUS V2 `c` / `m` / `d` envelope)\r
- Typical `globalDomain` example: `https://ous-sg.kujiale.com` (always use the token response value)\r
\r
## Open Platform APIs\r
\r
| Method | Path | Success body |\r
|--------|------|--------------|\r
| GET | `/global/world/v1/asset/token` | `ousToken`, `globalDomain`, `blockSize` |\r
| POST | `/global/world/v1/reconstructions` | `WorldAsyncOperation`: `{"worldId":"\x3Cencrypted id>"}` |\r
| POST | `/global/world/v1/generations` | Same as above |\r
| GET | `/global/world/v1/{worldId}` | World detail (`status`, `assets`, etc.) |\r
| POST | `/global/world/v1/list` | Paginated list (not wrapped in script) |\r
\r
OUS upload paths remain `/ous/api/...` (no `/global` prefix on OUS).\r
\r
## Response conventions\r
\r
- **Success:** HTTP 200, business object returned directly (not OUS `c` / `m` / `d`).\r
  - Create: JSON `WorldAsyncOperation` with field **`worldId`** only. Script also accepts legacy plain-text `worldId` if present.\r
- **Failure:** HTTP 4xx/5xx, **`ApiError`**: `code`, `message`, `status`, `details.metaData.bizCode` (e.g. auth **401**, bizCode **10004**).\r
\r
## Supported actions\r
\r
| Action | Purpose |\r
|--------|---------|\r
| `create` | Unified entry; set `workflow` to `reconstruction` or `generation` |\r
| `create-reconstruction` | Reconstruction only |\r
| `create-generation` | Generation only |\r
| `poll` | Poll by `worldId` until terminal state (recommended) |\r
| `status` | Single status query |\r
\r
## Agent hard constraints (must follow)\r
\r
0. 2D image requests → **do not** call create / status / poll from this skill.\r
1. Reconstruction without confirmed `scene` and `taskQuality` → **no** create.\r
2. Confirm with the user first:\r
   - `scene`: `model` or `space`\r
   - `taskQuality`: `low` / `normal` / `high`\r
3. **Do not** substitute defaults (e.g. `model` or `high`) without user choice.\r
4. Call create only after explicit user choice (and obey rule 9).\r
5. After `worldId`, **ask** whether to wait for polling:\r
   - **Will wait:** run synchronous `poll` in-session until done\r
   - **Will not wait:** return `worldId` and viewer link only\r
6. **Do not** background-poll and promise “notify when done” — the session cannot notify later.\r
7. If 3D intent is unclear, clarify 2D vs 3D before creating.\r
8. **Image directories:** when the user points at a folder of images, use **`imageDir`** so all images upload — **never** upload only a subset (e.g. first 20).\r
9. **One create POST per user task round** (high cost):\r
   - At most **one** `POST /global/world/v1/reconstructions` or `POST /global/world/v1/generations` per user’s stated order in this conversation round.\r
   - On failure, timeout, or missing `worldId` locally, **do not** create again unless the user explicitly starts a **new** order.\r
   - Exception: if create POST was **never sent** (auth, missing assets, etc.), one first create is allowed after fixes.\r
   - If the server may have charged but `worldId` is missing: guide the user to the platform task list or use `status` / `list` — **not** another create.\r
   - If create was already sent this round, pass `forbidCreate: true` or skip create actions.\r
10. **`projectName`:** omit unless the user explicitly requests a project name.\r
\r
## Required parameter interaction\r
\r
1. Prefer `AskQuestion` for `scene` × `taskQuality` (six combinations).\r
2. Ask both in one step when possible.\r
3. No create until the user has chosen.\r
4. If the user writes free text (e.g. “high quality space”), normalize, confirm once, then proceed.\r
\r
### Recommended options\r
\r
| Option | scene | taskQuality | Note |\r
|--------|-------|-------------|------|\r
| 1 | model | low | Object, faster |\r
| 2 | model | normal | Object, balanced |\r
| 3 | model | high | Object, recommended |\r
| 4 | space | low | Scene, faster |\r
| 5 | space | normal | Scene, balanced |\r
| 6 | space | high | Scene, recommended |\r
\r
**After create — ask whether to wait:**\r
\r
```text\r
Task created, worldId: {worldId}\r
\r
When complete, view at: https://www.aholo3d.com/3dgs-model/{worldId}\r
(Link may not work until the task finishes.)\r
\r
Reconstruction usually takes minutes to tens of minutes.\r
\r
Wait until complete?\r
- "wait" / "yes" — I poll in this session until done\r
- "no" — use the link later or ask me to poll/status\r
```\r
\r
## Recommended flow\r
\r
1. Confirm `reconstruction` vs `generation`.\r
2. For reconstruction: confirm `scene`, `taskQuality`.\r
3. **One** create for the whole round.\r
4. Record `worldId`; ask whether to poll.\r
5. Afterwards only `poll` / `status` / `list` unless the user starts a new task.\r
\r
## Execution logging (default on)\r
\r
Each step should log: start, end, duration (seconds). Suggested steps: token, upload, create, status, each poll tick.\r
\r
## Polling strategy\r
\r
After `worldId`, **ask** before polling.\r
\r
**User will wait** — synchronous poll (use `-u`):\r
\r
```bash\r
python -u aholo_reconstruct.py '{"action":"poll","worldId":"xxx","intervalSeconds":60,"timeoutSeconds":14400}'\r
```\r
\r
**User will not wait** — return `worldId` and `https://www.aholo3d.com/3dgs-model/{worldId}`.\r
\r
Suggested: `intervalSeconds=60`, `timeoutSeconds=14400`.\r
\r
**Forbidden:** background poll with a promise to notify later; polling without asking.\r
\r
## Task type rules\r
\r
### reconstruction\r
\r
- Input: `videoPaths` **or** `imagePaths` / `imageDir` (one of)\r
- `videoPaths`: 1–3 files\r
- `imagePaths` / `imageDir`: at least 20 images\r
- Required: `scene` (`model` / `space`), `taskQuality` (`low` / `normal` / `high`)\r
\r
### generation\r
\r
- `imagePaths` only, at most 1 image\r
- `prompt` and `imagePaths` cannot both be empty\r
- No `videoPaths`\r
\r
## Parameters\r
\r
### General\r
\r
| Parameter | Type | Description |\r
|-----------|------|-------------|\r
| `action` | enum | `create` / `create-reconstruction` / `create-generation` / `status` / `poll` |\r
| `workflow` | enum | For `create` only: `reconstruction` or `generation` |\r
| `projectName` | string | Optional → request `name`; omit unless user asked |\r
| `coverPath` | string | Local cover image (optional) |\r
| `cover` | string | Existing cover URL (optional) |\r
| `worldId` | string | Required for `status` / `poll` |\r
| `forbidCreate` | bool | If `true`, block any `create*` in this run |\r
\r
### reconstruction\r
\r
| Parameter | Type | Rule |\r
|-----------|------|------|\r
| `videoPaths` | string[] | 1–3 video paths |\r
| `imagePaths` | string[] | ≥20 image paths |\r
| `imageDir` | string | **Preferred** for folders — scans all images |\r
| `scene` | enum | `model` / `space` (required) |\r
| `taskQuality` | enum | `low` / `normal` / `high` (required) |\r
\r
### generation\r
\r
| Parameter | Type | Rule |\r
|-----------|------|------|\r
| `imagePaths` | string[] | At most 1 |\r
| `prompt` | string | Optional; cannot be empty together with images |\r
\r
## Examples\r
\r
Agent should run the script; users only need `AHOLO_API_KEY` set.\r
\r
```bash\r
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{\r
  "action": "create",\r
  "workflow": "reconstruction",\r
  "imageDir": "D:/images",\r
  "scene": "space",\r
  "taskQuality": "high"\r
}'\r
\r
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{\r
  "action": "create-reconstruction",\r
  "videoPaths": ["D:/videos/angle1.mp4"],\r
  "scene": "model",\r
  "taskQuality": "high"\r
}'\r
\r
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{\r
  "action": "create-generation",\r
  "imagePaths": ["D:/images/seed.jpg"],\r
  "prompt": "modern minimal interior"\r
}'\r
\r
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{\r
  "action": "status",\r
  "worldId": "A1b2C3d4E5"\r
}'\r
\r
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{\r
  "action": "poll",\r
  "worldId": "A1b2C3d4E5",\r
  "intervalSeconds": 60,\r
  "timeoutSeconds": 14400\r
}'\r
```\r
\r
## Windows PowerShell (optional local debug)\r
\r
```powershell\r
$env:AHOLO_API_KEY="your_api_key"\r
```\r
\r
```powershell\r
$env:AHOLO_FORCE_SSL_VERIFY="1"\r
```\r
\r
## Terminal status values\r
\r
`SUCCEEDED` | `FAILED` | `CANCELED` | `TIMEOUT` | `REJECTED`\r
\r
## Viewer URL after successful create\r
\r
`https://www.aholo3d.com/3dgs-model/{worldId}`\r