Hunyuan 3D 3.1 Pro Image to 3D Serverless API

Convert images to textured, game-ready 3D models with PBR.

PlaygroundAPI
Pricing
~175.80s
POST /v2/hunyuan-3d-3.1-pro-image-to-3d · submit + poll
 1# pip install "segmind>=1.1.0"
 2# export SEGMIND_API_KEY="YOUR_API_KEY"
 3import segmind
 4
 5# Async (v2): submit to the queue and block until COMPLETED.
 6# run() returns the final result dict (600s deadline, 1.0s poll by default).
 7result = segmind.run(
 8    "hunyuan-3d-3.1-pro-image-to-3d",
 9    input_image_url="https://segmind-resources.s3.amazonaws.com/input/hunyuan-3d-3.1-pro-image-to-3d-default-rooster-d3603389.jpg",
10    generate_type="Normal",
11    enable_pbr=False,
12    face_count=500000,
13)
14print(result["status"])                      # COMPLETED
15print(result.get("output"))                  # model output (e.g. media URL)
16print(result["metrics"]["inference_time"])   # server compute seconds
17
18# --- Or submit + poll manually (track request_id, control the cadence) ---
19from segmind import SegmindClient, InferenceFailed, InferenceTimeout
20
21client = SegmindClient()                      # reads SEGMIND_API_KEY
22payload = {
23    "input_image_url": "https://segmind-resources.s3.amazonaws.com/input/hunyuan-3d-3.1-pro-image-to-3d-default-rooster-d3603389.jpg",
24    "generate_type": "Normal",
25    "enable_pbr": False,
26    "face_count": 500000,
27}
28job = client.submit_async("hunyuan-3d-3.1-pro-image-to-3d", **payload)
29print(job.request_id)                         # available immediately
30try:
31    result = job.wait(timeout=600, interval=1.0)
32except InferenceTimeout as e:
33    print("still running:", e.request_id)
34except InferenceFailed as e:
35    print("failed:", e.detail)

API Endpoint

POSThttps://api.segmind.com/v1/hunyuan-3d-3.1-pro-image-to-3d

Parameters

input_image_urlrequired
string (uri)

Front view of a single object. JPG, PNG or WEBP, 128-5000 px, up to 8 MB. Works best on a plain background with the object filling over half the frame.

back_image_urloptional
string (uri)

Back/rear view of the object. Optional. Adding any extra view adds a multi-view surcharge (flat, not per image).

bottom_image_urloptional
string (uri)

Bottom view. Optional. Adding any extra view adds a multi-view surcharge (flat, not per image).

enable_pbroptional
boolean

Generate PBR materials (metallic, roughness, normal maps). Adds a surcharge. Ignored, and not charged, when Generate type is Geometry.

Default: false
face_countoptional
integer

Target polygon count, 40,000 to 1,500,000. Any value other than the 500,000 default adds a surcharge.

Default: 500000Range: 40000 - 1500000
generate_typeoptional
string

Normal returns a textured model. Geometry returns an untextured white mesh.

Default: "Normal"
Allowed values :
Normal (textured)→"Normal"
Geometry only→"Geometry"
left_front_image_urloptional
string (uri)

Left-front view at 45 degrees. Optional. Adding any extra view adds a multi-view surcharge (flat, not per image).

left_image_urloptional
string (uri)

Left side view. Optional. Adding any extra view adds a multi-view surcharge (flat, not per image).

right_front_image_urloptional
string (uri)

Right-front view at 45 degrees. Optional. Adding any extra view adds a multi-view surcharge (flat, not per image).

right_image_urloptional
string (uri)

Right side view. Optional. Adding any extra view adds a multi-view surcharge (flat, not per image).

top_image_urloptional
string (uri)

Top-down view. Optional. Adding any extra view adds a multi-view surcharge (flat, not per image).

Response Type

Returns: 3D Model

Asynchronous requests (v2)

Use Async for video, long-running (>~60s), or high-concurrency workloads; Sync is simplest for fast image & LLM calls. Async submits a request and you poll it to completion.

  1. 1
    POST /v2/hunyuan-3d-3.1-pro-image-to-3d

    Submit — returns request_id, status_url, response_url

  2. 2
    GET /v2/requests/{id}/status

    Poll — until COMPLETED or FAILED

  3. 3
    GET /v2/requests/{id}

    Result — final response body

Status states

QUEUED— Accepted, waiting for a worker
PROCESSING— Running on a worker
COMPLETED— Done — result body is ready
FAILED— Errored (incl. content/RAI blocks)
  • A FAILED request is served as HTTP 422 — the body still carries the error detail.
  • An unknown or expired request_id returns HTTP 404.
  • Results are retained for 1 hour, then expire.
  • Content / RAI blocks surface as FAILED, not a separate state.
  • Track completion by polling the status endpoint.

Common Error Codes

The API returns standard HTTP status codes. Detailed error messages are provided in the response body.

400

Bad Request

Invalid parameters or request format

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions

404

Not Found

Model or endpoint not found

406

Insufficient Credits

Not enough credits to process request

429

Rate Limited

Too many requests

500

Server Error

Internal server error

502

Bad Gateway

Service temporarily unavailable

504

Timeout

Request timed out