Java SDK

Official Java SDK for the Aholo Open API.

Requirements: Java 8+, Maven ≥ 3.6 (JDK 17 or 21 recommended when building from source)
GitHub: manycoretech/aholo-spatial-sdk

Installation

Add dependencies to pom.xml as needed (use the latest version on Maven Central):

<dependency>
  <groupId>com.manycoreapis</groupId>
  <artifactId>aholo-sdk-asset</artifactId>
  <version>1.2.0</version>
</dependency>

<dependency>
  <groupId>com.manycoreapis</groupId>
  <artifactId>aholo-sdk-world</artifactId>
  <version>1.2.0</version>
</dependency>

<dependency>
  <groupId>com.manycoreapis</groupId>
  <artifactId>aholo-sdk-lux3d</artifactId>
  <version>1.2.0</version>
</dependency>

Authentication

Recommended: set the environment variable; the SDK reads AHOLO_API_KEY:

export AHOLO_API_KEY=your_api_key_here

Or pass it in code:

import com.manycoreapis.sdk.core.AholoClientConfig;

AholoClientConfig config = AholoClientConfig.of("your_api_key_here", "com");

Security

Never hardcode API keys in source code, packages, or public repositories.

Region

Value	Description	API endpoint
`cn`	China	`https://api.aholo3d.cn`
`com`	Global	`https://api.aholo3d.com`

Asset upload

import com.manycoreapis.sdk.asset.AssetClient;
import com.manycoreapis.sdk.asset.UploadResult;
import com.manycoreapis.sdk.core.AholoClientConfig;
import java.nio.file.Files;
import java.nio.file.Paths;

AssetClient asset = AssetClient.create(AholoClientConfig.ofRegion("com"));

Upload a file

UploadResult result = asset.uploadFile(Paths.get("video.mp4"));
System.out.println(result.url()); // public URL

Upload bytes

byte[] data = Files.readAllBytes(Paths.get("image.jpg"));
UploadResult result = asset.uploadBytes(data, "image.jpg");

Upload with progress

UploadResult result = asset.uploadFile(
    Paths.get("video.mp4"),
    (uploaded, total) -> {
        int pct = (int) (uploaded * 100 / total);
        System.out.printf("\rUploading: %d%%", pct);
    }
);

UploadResult fields

Method	Type	Description
`url()`	`String`	Public URL of the uploaded file
`md5()`	`String`	File MD5
`uploadKey()`	`String`	OUS upload key

World

import com.manycoreapis.sdk.world.WorldClient;
import com.manycoreapis.sdk.world.model.ReconstructionCreateParams;
import com.manycoreapis.sdk.world.model.GenerationCreateParams;
import com.manycoreapis.sdk.world.model.WorldAsyncOperation;
import com.manycoreapis.sdk.world.model.WorldDetail;

WorldClient world = WorldClient.create(AholoClientConfig.ofRegion("com"));

3DGS reconstruction (video / images)

WorldAsyncOperation op = world.reconstructions().create(
    ReconstructionCreateParams.builder()
        .name("Living room")
        .addResource("https://cdn.example.com/room.mp4", "video") // "video" | "image"
        .taskQuality("normal")  // "low" | "normal" | "high"
        .scene("model")         // "model" | "space"
        .useMask(false)          // optional: segment uploaded resources when true
        .build());

WorldDetail detail = world.waitFor(op.worldId());
detail.assets().ifPresent(assets ->
    assets.splats().ifPresent(splats ->
        splats.urls().ifPresent(urls ->
            urls.plyPath().ifPresent(System.out::println)))); // PLY download URL

Image reconstruction requirement

When using images, you need ≥ 20 image resources (type is image or omitted).

3DGS generation (from prompt)

WorldAsyncOperation op = world.generations().create(
    GenerationCreateParams.builder()
        .name("Forest cabin")
        .prompt("A modern cabin in the forest")
        .build());

WorldDetail detail = world.waitFor(op.worldId());

Get world detail

WorldDetail detail = world.retrieve(worldId);
detail.status().ifPresent(System.out::println);

Task status & polling

Phase	Status	Description
In progress	`PENDING`	Queued
In progress	`PREPROCESSING`	Preprocessing
In progress	`RUNNING`	Running
Success	`SUCCEEDED`	Success
Failed	`FAILED`	Failed
Failed	`CANCELED`	Canceled
Failed	`TIMEOUT`	Timed out
Failed	`REJECTED`	Rejected

world.waitFor(worldId) polls until SUCCEEDED and returns WorldDetail. Terminal failures throw AholoException.

List worlds

import com.manycoreapis.sdk.world.model.WorldListParams;
import com.manycoreapis.sdk.world.model.WorldPagedList;

WorldPagedList page = world.list(
    WorldListParams.builder().pageNum(1).pageSize(20).build());
page.result().ifPresent(items ->
    items.forEach(w -> System.out.println(w.worldId() + " " + w.status())));

WorldDetail fields

Method	Type	Description
`worldId()`	`String`	World ID
`name()`	`Optional<String>`	Name
`status()`	`Optional<String>`	See task status table above
`assets().splats().urls().plyPath()` etc.	`Optional<String>`	Splat download URLs (`plyPath` / `spzPath` / `lodMetaPath`)
`assets().imagery().panoUrl()`	`Optional<String>`	AI panorama URL
`assets().semanticsMetadata().upAxis()`	`Optional<String>`	World up axis (`Y` / `Z`)
`createTime()`	`Optional<Long>`	Created at (Unix ms)
`updateTime()`	`Optional<Long>`	Updated at (Unix ms)

Lux3D

import com.manycoreapis.sdk.lux3d.Lux3dClient;
import com.manycoreapis.sdk.lux3d.model.ImgTo3dCreateParams;
import com.manycoreapis.sdk.lux3d.model.TextTo3dCreateParams;
import com.manycoreapis.sdk.lux3d.model.MaterialTransferCreateParams;
import com.manycoreapis.sdk.lux3d.model.TaskResult;
import java.nio.file.Paths;

Lux3dClient lux3d = Lux3dClient.create(AholoClientConfig.ofRegion("com"));

Image to 3D

// From URL
long taskId = lux3d.imgTo3d().create(
    ImgTo3dCreateParams.builder()
        .img("https://example.com/object.jpg")
        .version("v2.0-preview") // "v1.0-pro" | "v2.0-preview" (default)
        .build());

// From local file
long taskId2 = lux3d.imgTo3d().createFromFile(Paths.get("object.jpg"));

TaskResult result = lux3d.tasks().waitFor(taskId);
result.outputs().forEach(o -> o.content().ifPresent(System.out::println));

Text to 3D

long taskId = lux3d.textTo3d().create(
    TextTo3dCreateParams.builder()
        .prompt("A wooden chair with carved legs")
        // .style("photorealistic") // see styles below
        .build());
TaskResult result = lux3d.tasks().waitFor(taskId);

Material transfer

long taskId = lux3d.materialTransfer().create(
    MaterialTransferCreateParams.builder()
        .img("https://example.com/material.jpg")
        .meshUrl("https://example.com/model.glb")
        .build());
TaskResult result = lux3d.tasks().waitFor(taskId);

Version differences

Version	Default	Output formats	Notes
`v2.0-preview`	Yes	`.zip` + `.glb` + `.usdz` (3 files)	Enhanced text & texture detail
`v1.0-pro`		`.lux3d` (1 file)	Full PBR, supports transparent materials

Task result fields

Method	Type	Description
`taskId()`	`long`	Task ID
`status()`	`int`	`0` init; `1` running; `3` success; `4` failed
`outputs()`	`List<TaskOutput>`	Output files (`outputs().get(n).content()` is `Optional<String>` download URL, ~2 h TTL after success)

lux3d.tasks().waitFor(taskId) returns when status == 3; throws AholoException on 4. Poll every 10–15 seconds.

Error handling

import com.manycoreapis.sdk.core.AuthenticationException;
import com.manycoreapis.sdk.core.RateLimitException;
import com.manycoreapis.sdk.core.BusinessException;
import com.manycoreapis.sdk.core.AholoException;
import com.manycoreapis.sdk.world.model.WorldDetail;

try {
    WorldDetail detail = world.waitFor(worldId);
} catch (AuthenticationException e) {
    System.err.println("Invalid or missing API Key");
} catch (RateLimitException e) {
    System.err.println("Rate limit exceeded");
} catch (BusinessException e) {
    System.err.println("API error: " + e.getCode() + " " + e.getMessage());
} catch (AholoException e) {
    System.err.println("SDK error: " + e.getMessage());
}

Exception	Description
`AuthenticationException`	Invalid or missing API Key
`RateLimitException`	Rate limit exceeded
`BusinessException`	API business error (includes `getCode()`)
`AholoException`	Base class for other SDK errors

More examples

See GitHub examples:

File	Description
`UploadFile.java`	Upload a local file and print the URL
`WorldReconstruct.java`	Upload video → create 3DGS reconstruction → poll until done
`Lux3dImgTo3d.java`	Local image → Lux3D image-to-3D → poll until done

After cloning the repo, run from aholo-spatial-sdk/java:

export AHOLO_API_KEY=your_api_key_here
# optional: export AHOLO_REGION=com   # default cn

# Upload a file
mvn exec:java -pl examples \
  -Dexec.mainClass=com.manycoreapis.sdk.examples.UploadFile \
  -Dexec.args="/path/to/photo.jpg"

# 3DGS world reconstruction (video)
mvn exec:java -pl examples \
  -Dexec.mainClass=com.manycoreapis.sdk.examples.WorldReconstruct \
  -Dexec.args="/path/to/room.mp4"

# Lux3D image to 3D
mvn exec:java -pl examples \
  -Dexec.mainClass=com.manycoreapis.sdk.examples.Lux3dImgTo3d \
  -Dexec.args="/path/to/chair.png"

Dependencies

aholo-sdk-core uses OkHttp 4.x for HTTP (Java 8 compatible). It is pulled in transitively — no extra pom.xml entry required.

GitHub README is for installation only. If it conflicts with this page, this page wins. Source and runnable examples: GitHub.

Installation​

Authentication​

Region​

Asset upload​

Upload a file​

Upload bytes​

Upload with progress​

UploadResult fields​

World​

3DGS reconstruction (video / images)​

3DGS generation (from prompt)​

Get world detail​

Task status & polling​

List worlds​

WorldDetail fields​

Lux3D​

Image to 3D​

Text to 3D​

Material transfer​

Version differences​

Task result fields​

Error handling​

More examples​