Quick Start

This page walks you through your first World Reconstruction or World Generation call with a few curl examples.

• API gateway: https://api.aholo3d.com (gateway routes use the /global prefix)
• Authentication: Authentication
• Full schemas and errors: API → sidebar Asset / World

Step 1: Get an API key

1. Sign in to Aholo Labs

   Open labs.aholo3d.com with your Aholo account.

2. Create and copy a key

   On the API keys page, create an API key and store it securely.

   Security

   Do not commit API keys to frontend code, mobile apps, or public repositories.

Step 2: Set the request header

All gateway calls (not OUS upload hosts) need:

Authorization: <your API key>

Do not add a Bearer prefix. See Authentication for details.

Step 3: Understand the flow

World APIs are asynchronous. Recommended order:

Step	What to do	Main endpoints
1	Upload images/video and get public URLs	GET /global/asset/v1/token, then upload on globalDomain (see Asset in the API sidebar)
2	Create a reconstruction or generation job	See table below
3	Poll status and outputs with worldId	GET /global/world/v1/{worldId}
4	(Optional) List your worlds	POST /global/world/v1/list

On OUS globalDomain, call /ous/api/... with header ous-token-v2 (ousToken from the token response). Those paths are not prefixed with /global.

Which endpoint creates a job?

Capability	Use case	Method
World reconstruction	3DGS from ≥20 images or from video	POST /global/world/v1/reconstructions
World generation	Text, one image, or both	POST /global/world/v1/generations

Success: HTTP 200, response body is WorldAsyncOperation with worldId (pass as {worldId} on GET .../{worldId} to poll details and outputs).

Failure: ApiError (code, message, status; legacy biz code in details.metaData.bizCode).

Polling and outputs

• Call GET /global/world/v1/{worldId} until status reaches a terminal state such as SUCCEEDED or FAILED.
• On success, assets.splats.urls may include plyPath, spzPath, and optionally lodMetaPath after LOD processing.
• createTime / updateTime are Unix milliseconds.

Input rules

Job type	Requirements
Reconstruction	Reachable resources[].url; ≥20 images (type=image or omit type), or video with type=video on each item; set scene (model / space) and taskQuality (low / normal / high)
Generation	Non-empty prompt and/or resources; at most one image. Interiors tend to converge more reliably today; non-indoor stays beta, so expect wider quality swings

Step 4: Run the examples

Replace <your API key>, <worldId>, and sample URLs with real values. Base URL: https://api.aholo3d.com.

Get upload token (when you need to upload media first)

curl -X GET 'https://api.aholo3d.com/global/asset/v1/token' \
  -H 'Authorization: <your API key>'

Then complete ousCos* uploads on the response globalDomain per the Asset group in the API.

Create a reconstruction job

curl -X POST 'https://api.aholo3d.com/global/world/v1/reconstructions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your API key>' \
  -d '{
    "name": "Living room reconstruction",
    "resources": [
      {
        "url": "https://cdn.example.com/input/room-001.jpg",
        "type": "image"
      }
    ],
    "taskQuality": "high",
    "scene": "space"
  }'

Image count

The sample shows one resource for structure only. Real image reconstruction needs ≥20 image entries—see the API.

On success:

{
  "worldId": "A1b2C3d4E5"
}

Create a generation job

Provide a non-empty prompt, and/or at most one image (you can combine both).

curl -X POST 'https://api.aholo3d.com/global/world/v1/generations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your API key>' \
  -d '{
    "name": "Living room generation",
    "cover": "https://cdn.example.com/cover/gen-cover.jpg",
    "prompt": "modern minimalist living room",
    "resources": [
      {
        "url": "https://cdn.example.com/input/room.jpg",
        "type": "image"
      }
    ]
  }'

Get job status and outputs

curl -X GET 'https://api.aholo3d.com/global/world/v1/<worldId>' \
  -H 'Authorization: <your API key>'

List my worlds (paged)

curl -X POST 'https://api.aholo3d.com/global/world/v1/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your API key>' \
  -d '{
    "pageNum": 0,
    "pageSize": 20,
    "statusList": ["RUNNING", "SUCCEEDED"]
  }'

---

For enums, multipart upload, and error codes, see Asset and World in the API. For Agent automation, see Skills.