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://router.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"
  }'

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.