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	Optional	3D model ID. Defaults to `Hyper3d-Rodin-Gen2`.
prompt	string \| null	Optional	Text description. Up to 4,000 characters, or 400 for Hyper3D. 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.
charge_amount_krw	integer \| null	Optional	Fixed KRW settlement amount. Normal API keys cannot use it; only first-party delegated keys may.

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 time, requests

BASE = "https://apirouter.pleum.ai/v1"
HEADERS = {"Authorization": "Bearer plm_...", "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"] in ("succeeded", "failed"):
        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 plm_...", "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 !== "succeeded" && job.status !== "failed");

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 a credit hold is created. 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 snapshots its selected offering, variant, FX rate, and markup at submission, then settles from that snapshot on completion. Idempotency-Key is optional (max 128 chars) and replays the same body 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.