3D Object Generation
Generate 3D meshes from text or images and poll for the finished asset.
3D generation is asynchronous: submit a job, receive a record with a status, then poll until it is
completed. Discover 3D models with the Models API
(GET /v1/models?type=3d_generation).
Text-to-3D
POST /v1/3d/generationsParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | 3D model id (e.g. modelscope/shap-e, meshy). |
prompt | string | Yes | Text description of the 3D object (10–5000 chars). |
output_format | string | No | glb (default), obj, ply, or stl. |
guidance_scale | number | No | How closely to follow the prompt, 1.0–50.0. Default 15.0. |
num_inference_steps | integer | No | Denoising steps, 16–256. Default 64. |
Response
The endpoint returns a job record. While the mesh renders, status is pending or processing:
{
"id": "3d_abc123",
"status": "processing",
"created_at": "2026-06-18T12:00:00Z",
"model": "model-id",
"prompt": "A low-poly medieval castle with towers and a moat",
"output_format": "glb",
"url": null,
"preview_url": null,
"vertices": null,
"faces": null,
"error": null
}When finished, status is completed and the mesh is downloadable via url, with an optional
preview_url and mesh stats (vertices, faces). On failure, status is failed and error
describes why.
Image-to-3D
POST /v1/3d/image-to-3dReconstruct a 3D mesh from a single image.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | No | 3D model id. Default meshy. |
image_url | string | Yes | URL of the input image. |
output_format | string | No | glb (default), obj, ply, or stl. |
remove_background | boolean | No | Strip the background before reconstruction. Default true. |
Poll a job
GET /v1/3d/{id}Returns the current job record (same shape as the create response). Poll until status is completed
or failed.
Delete a job
DELETE /v1/3d/{id}Removes the job and its generated asset.
Example
import os, time, httpx
BASE = "https://api.yuhuanstudio.com/v1"
headers = {"Authorization": f"Bearer {os.environ['YUNXIN_API_KEY']}"}
# Submit the generation job
job = httpx.post(
f"{BASE}/3d/generations",
headers=headers,
json={
"model": "model-id",
"prompt": "A futuristic sports car with a metallic blue finish",
"output_format": "glb",
},
).json()
job_id = job["id"]
# Poll until the job finishes
while True:
status = httpx.get(f"{BASE}/3d/{job_id}", headers=headers).json()
if status["status"] == "completed":
print(f"3D model ready: {status['url']}")
break
if status["status"] == "failed":
print(f"Generation failed: {status.get('error')}")
break
time.sleep(5)3D models are provider-specific and may not be enabled on every account. List what's available with
GET /v1/models?type=3d_generation.
How is this guide?