3D Generation

Generate a Hyper3D or Hitem3D mesh asynchronously through BytePlus ModelArk.

POST /v1/3d/generations returns a job_id immediately. Poll GET /v1/jobs/{job_id} until it completes. Every request needs a plm_ API key.

POST/v1/3d/generations

Submit a job#

Parameter	Type	Required	Description
model	string	Required	3D model ID, e.g. `Hyper3d-Rodin-Gen2` or `Hitem3d-2.0`.
prompt	string \| null	Optional	Text description. Up to 400 characters for every model. Either prompt or images is required.
images	string[]	Optional	HTTP(S) image-reference URLs. The global ceiling is 5; Hitem3D requires 1–4.
generation_mode	standard_white \| standard_textured \| high_precision_white \| high_precision_textured	Optional	Required Hitem3D price mode. It atomically fixes the matching resolution/request_type.
mesh_options	object	Optional	Structured Hyper3D-only mesh controls (material, mesh_mode, quality_override, and more). It cannot be combined with Hitem3D generation_mode.
output_format	glb \| obj \| stl \| fbx \| usdz	Optional	Preferred result file format.
seed	integer	Optional	Hyper3D-only seed from 0 to 65,535. It cannot be sent to Hitem3D.

request

curl https://apirouter.pleum.ai/v1/3d/generations \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-mesh-001" \
  -d '{
    "model": "Hitem3d-2.0",
    "images": ["https://example.com/product.png"],
    "generation_mode": "high_precision_textured",
    "output_format": "glb"
  }'

submit + poll (Python)

import os, time, requests

BASE = "https://apirouter.pleum.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['PLEUM_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Submit the job — returns job_id immediately.
resp = requests.post(f"{BASE}/3d/generations", headers=HEADERS, json={
    "model": "Hitem3d-2.0",
    "images": ["https://example.com/product.png"],
    "generation_mode": "high_precision_textured",
    "output_format": "glb",
})
job_id = resp.json()["job_id"]

# 2. Poll until the job finishes.
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS).json()
    if job["status"] != "processing":
        break
    time.sleep(5)

print(job["result_url"] if job["status"] == "succeeded" else job["error"])

submit + poll (TypeScript)

const BASE = "https://apirouter.pleum.ai/v1";
const HEADERS = {
  Authorization: `Bearer ${process.env.PLEUM_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Submit the job — returns job_id immediately.
const submit = await fetch(`${BASE}/3d/generations`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    model: "Hitem3d-2.0",
    images: ["https://example.com/product.png"],
    generation_mode: "high_precision_textured",
    output_format: "glb",
  }),
});
const { job_id } = await submit.json();

// 2. Poll until the job finishes.
let job: any;
do {
  await new Promise((r) => setTimeout(r, 5000));
  job = await (await fetch(`${BASE}/jobs/${job_id}`, { headers: HEADERS })).json();
} while (job.status === "processing");

console.log(job.status === "succeeded" ? job.result_url : job.error);

200 OK

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "processing",
  "model": "Hitem3d-2.0",
  "result_url": null,
  "cost": null,
  "error": null,
  "assets": []
}

BytePlus ModelArk model rules#

Model-specific inputs, formats, and price modes are validated before credits are deducted. Unsupported combinations return 400 with no charge.

Parameter	Type	Required	Description
Hyper3D Rodin Gen2	text-to-3D / image-to-3D	Optional	Accepts a prompt or up to five image references. generation_mode is not allowed; Hyper3D mesh_options and seed are available.
Hitem3D 2.0	image-to-3D	Optional	Requires both 1–4 image references and generation_mode. Choosing standard/high-precision × white/textured fixes the official variant and price together.

Poll a job#

GET/v1/jobs/{job_id}

POST initially returns processing. GET /v1/jobs/{job_id} returns the same job shape; on success, assets can contain GLB/OBJ/STL/FBX/USDZ files and result_url is the representative URL.

succeeded

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "succeeded",
  "model": "Hitem3d-2.0",
  "result_url": "https://cdn.pleum.ai/3d/f47ac10b-58cc-4372-a567-0e02b2c3d479.glb",
  "cost": {"krw": 2900},
  "error": null,
  "assets": [
    {"type": "3d", "url": "https://cdn.pleum.ai/3d/f47ac10b-58cc-4372-a567-0e02b2c3d479.glb", "format": "glb"}
  ]
}

Settlement and BYOK#

An async 3D job is settled with the model, price, and FX rate in effect at submission. Idempotency-Key is optional (max 128 chars). Resubmitting with the same key creates no new job and returns the job_id of the first submission. The same key with a different body returns 422, and a submission that is still processing returns 409. A key is kept for 24 hours.

Async generation such as 3D and video does not support BYOK. A BYOK-key request returns 400; a missing or not-owned job_id returns 404.