---

name: aholo-3dgs-reconstruction-global description: "Aholo OpenAPI v1 global 3D tasks (reconstruction/generation): upload, create (worldId), poll/status. Gateway api.aholo3d.com, /global/world/v1. Default one create per single intent; multiple creates allowed when user explicitly chooses separate 3DGS per video. Not for 2D."

Aholo 3D Reconstruction Skill — Global (OpenAPI v1)

Aholo global Open Platform (api.aholo3d.com). Agent runs aholo_reconstruct.py; user sets AHOLO_API_KEY only.

1. When to use

Use: 3D reconstruction, 3D generation, worldId status/poll, PLY/SPZ/SOG.

Do not use: 2D renders only; no 3D outcome requested.

Ambiguous requests: Clarify 2D single image vs 3D task (worldId + poll). Example: "generate a room from a reference image" → ask whether the user wants a 2D single render or a 3D task (worldId, pollable). Enter this skill only if user picks 3D.

2. Prerequisites & API

Item	Detail
Env	AHOLO_API_KEY — api-keys
Auth	Authorization: <API Key>, no Bearer
Create header	x-source: skills → platform OPEN_API_SKILL
Gateway	https://api.aholo3d.com; upload token GET /global/asset/v1/token; world tasks /global/world/v1/*
Viewer	https://studio.aholo3d.com/3dgs-model/{worldId}
Actions	create / create-reconstruction / create-generation / status / poll / list
Create success	WorldAsyncOperation contains worldId only
Credits 11003	Say insufficient credits; link www.aholo3d.com/pricing; no invented URLs; no create* retry for same video / same intent

Missing API key: Tell user to set env and reply continue; agent runs script — do not make manual python the main path.

TLS (script default behavior)

• Script enables SSL verification by default (secure by default).
• Corporate/self-signed certs: set AHOLO_INSECURE_SKIP_VERIFY=1 (or true / yes / on) to explicitly disable verification; prefer REQUESTS_CA_BUNDLE to point at your enterprise CA.
• On CERTIFICATE_VERIFY_FAILED, configure CA certs first; use AHOLO_INSECURE_SKIP_VERIFY only when you accept the risk.

Responses & errors

• OpenAPI success: HTTP 200; create returns JSON WorldAsyncOperation with worldId only.
• OpenAPI failure: HTTP 4xx/5xx, body is ApiError: code, message, status, details.metaData.bizCode (e.g. 10004 not authenticated, 11003 insufficient credits).
• OUS upload: asset upload uses the upload domain returned by the token endpoint.

3. Agent hard constraints (mandatory)

#	Rule
0	2D-only → no create/status/poll from this skill
7	Unclear 3D intent → 2D/3D clarify first (§1)
1–3	Reconstruction only: need confirmed scene (model/space) + taskQuality (low/normal/high) before create; no defaults (e.g. high/model) placed on behalf of the user
1–4	Reconstruction only: the initial AskQuestion round must simultaneously include the useMask option (note: "only effective when scene=model; ignored when scene=space"); never default to false silently; never defer to a second round
4	Generation: do not ask scene/taskQuality; create when prompt/image ready
8	Image folder → use imageDir for all images; never upload a subset only
11	Multiple videos: ask before create (do not choose for user): A one 3DGS (one create, all in videoPaths); B one 3DGS per video (see #9). Only 1 video → skip question
9	Create POST (high cost) — Default: one user single 3D intent → at most one create per conversation round; no retry on same intent after fail/timeout/missing worldId unless user explicitly re-orders. Pre-upload failure (POST not sent) → one first create after fix. Charged but no worldId → task list / status/list, not another create. Multi-video B: user chose separate 3DGS → create per video (videoPaths one each), warn N tasks/charges upfront; no duplicate create for same video; failed video → no retry, continue with remaining. Use forbidCreate only to block accidental duplicate for the same completed task, not the next video in B
10	projectName only if user explicitly asks; never invent from folder name or timestamp
5–6	After each worldId → ask wait or not; if wait → sync poll (intervalSeconds=60, timeoutSeconds=14400); if not → link only. No background poll + "I'll notify you"; no poll without asking

taskQuality display names (API values unchanged)

Value	Display
low	Fast Preview (极速预览)
normal	Standard (标准)
high	Professional — recommended (专业，推荐)

4. Standard flow

1. Applicability + 2D/3D (§1).
2. reconstruction vs generation.
3. Reconstruction: AskQuestion first — confirm scene, taskQuality, and useMask in one round (§5 table); normalize free text before confirming; do not split into two rounds.
4. Multiple videos (2+): A merge vs B separate (§5 template).
5. token → upload → create (§3 #9, #11).
6. Record worldId; ask wait (§5 template).
7. Wait → sync poll; else link only.
8. No further create same round except new order or next video in B (§3 #9).

5. User prompts

Reconstruction — initial confirm (scene, taskQuality, useMask — one round, do not split):

Use AskQuestion with all three questions simultaneously:

Question	Options
scene	model (object) / space (scene)
taskQuality	low Fast Preview / normal Standard / high Professional (recommended)
useMask	Enable (auto background removal, best for plain backgrounds) / Disable (keep original background, default) — only effective when scene=model; ignored when scene=space

Multiple videos:

You provided N videos. Choose (I will not choose for you):
A) One 3DGS — one worldId
B) Separate 3DGS per video — N worldIds (N tasks, processed one video at a time)

After create:

Task created, worldId: {worldId}
View when ready: https://studio.aholo3d.com/3dgs-model/{worldId}
(Link may not be accessible until the task completes)

Wait until complete?
- wait / yes — sync poll in this session
- no — poll later or open the link yourself

6. Task rules & parameters

reconstruction

• videoPaths (no fixed limit) or imagePaths/imageDir (≥20 images), pick one
  • .mp4 / .mov → type=video; .insv (Insta360 panoramic video) → type=insv; detected automatically from extension
• Required: scene, taskQuality
• Optional: useMask (boolean; auto background removal; only effective when scene=model; default false; ignored when scene=space)
• imageDir scans jpg/jpeg/png/webp only (excludes bmp/gif)

generation

• ≤1 image; prompt and image not both empty; no videoPaths; no scene/taskQuality

Key params

Param	Description
action / workflow	see §2 actions
imageDir	preferred for image-folder reconstruction
videoPaths	no fixed limit; .insv auto-detected as type=insv, others as type=video
useMask	boolean, background removal (optional; reconstruction + scene=model only; default false)
worldId	for status / poll
pageNum / pageSize / statusList	list pagination params
forbidCreate	guard against accidental duplicate create for same task; do not set for next video in multi-video B

Examples (agent runs with python -u)

JSON argument on a single line as the second argv. See Windows/PowerShell section below for Windows-specific rules.

# Reconstruction (image directory)
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{"action":"create","workflow":"reconstruction","imageDir":"D:/images","scene":"space","taskQuality":"high"}'

# Reconstruction (Insta360 panoramic video, auto-detected as type=insv)
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{"action":"create","workflow":"reconstruction","videoPaths":["D:/room.insv"],"scene":"space","taskQuality":"high"}'

# Reconstruction (with background removal)
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{"action":"create","workflow":"reconstruction","videoPaths":["D:/obj.mp4"],"scene":"model","taskQuality":"normal","useMask":true}'

# Generation
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{"action":"create-generation","imagePaths":["D:/seed.jpg"],"prompt":"modern minimal interior"}'

# Poll
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{"action":"poll","worldId":"xxx","intervalSeconds":60,"timeoutSeconds":14400}'

# List (running + succeeded)
python -u .cursor/skills/aholo-3dgs-reconstruction-global/aholo_reconstruct.py '{"action":"list","pageNum":0,"pageSize":20,"statusList":["RUNNING","SUCCEEDED"]}'

Windows / PowerShell (agent must read)

When the user is on Windows, the agent must follow these rules:

• Shell: Use PowerShell by default; no bash syntax (e.g. && chaining); use ; to separate commands, or issue one python -u ... at a time.
• JSON arg: Put the entire JSON on a single line wrapped in single quotes as the second argument; never break it across multiple lines (PowerShell will split arguments).
• Paths: Use forward slashes in Windows paths, e.g. D:/images/0001.jpg, to avoid unescaped backslash issues.
• Working directory: Run from the repo root or the directory containing .cursor/skills/aholo-3dgs-reconstruction-global/.
• Output: Always include -u so create/upload/poll progress streams in real time.
• User self-debug (optional): $env:AHOLO_API_KEY="..." then the same single-line python -u ...; agent-run is still the preferred path.

7. Appendix

API paths: GET /global/asset/v1/token · POST /global/world/v1/reconstructions · POST /global/world/v1/generations · GET /global/world/v1/{worldId} · POST /global/world/v1/list · OUS upload uses domain from token response (no /global prefix on OUS)

Terminal states: SUCCEEDED · FAILED · CANCELED · TIMEOUT · REJECTED

Output fields (after SUCCEEDED): plyPath · spzPath · lodMetaPath (LOD chunk metadata, optional) · panoUrl (AI panorama, generation only)

Local debug (optional)

$env:AHOLO_API_KEY="your_api_key"
# Self-signed certs (not recommended): $env:AHOLO_INSECURE_SKIP_VERIFY="1"
# Or set CA bundle: $env:REQUESTS_CA_BUNDLE="D:/certs/corp-ca.pem"

Agent-run is preferred; user sets the key and replies continue.