
Curled armadillo
hunyuan-3d/v3.1/pro/image-to-3dHunyuan 3D v3.1 Pro Image to 3D builds models from a front image with seven optional views, PBR materials, and face count control. Supply matching angles to describe the object from more sides and guide its reconstructed shape.
Hunyuan 3D v3.1 Pro Image to 3D API
Submit the input, retain the task_id, and retrieve the completed model files.
Send your Vidgo API key with Bearer authentication.
https://api.vidgo.ai/api/generate/submitPlace model at the root and generation settings inside input.
REQUEST_BODY=$(cat <<'JSON'
{
"model": "hunyuan-3d/v3.1/pro/image-to-3d",
"input": {
"generate_type": "Normal",
"face_count": 500000,
"enable_pbr": false,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/pro/image-to-3d/v1/02/input.png"
]
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"Query the returned task_id until the status is finished or failed.
GET https://api.vidgo.ai/api/generate/status/{task_id}Query the task and read files when its status is finished.
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "LQ01Q4YUIXAQNUJT",
"status": "running",
"created_time": "2026-09-27T22:07:45"
}
}{
"code": 200,
"data": {
"task_id": "LQ01Q4YUIXAQNUJT",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/pro/image-to-3d/v1/02/PEDHSYNDDS8HNBB9_1.glb",
"file_type": "3d"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/pro/image-to-3d/v1/02/PEDHSYNDDS8HNBB9_2.png",
"file_type": "image"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/pro/image-to-3d/v1/02/material.mtl",
"file_type": "3d"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/pro/image-to-3d/v1/02/PEDHSYNDDS8HNBB9_4.obj",
"file_type": "3d"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/pro/image-to-3d/v1/02/texture_20250901.png",
"file_type": "image"
}
],
"created_time": "2026-09-27T22:07:45",
"error_message": null,
"progress": 100
}
}Read every files item for its file_url, file_type, label, and format.
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "hunyuan-3d/v3.1/pro/image-to-3d",
"input": {
"generate_type": "Normal",
"face_count": 500000,
"enable_pbr": false,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/pro/image-to-3d/v1/02/input.png"
]
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
donePlace generation parameters inside input; keep model and callback_url at the root.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| model | string | Yes | — | hunyuan-3d/v3.1/pro/image-to-3d |
| input | object | Yes | — | Inputs and controls for this generation. |
| input.prompt | string | No | — | Optionally add a nonblank description of the object. |
| input.image_urls | string[] | Yes | — | Provide exactly one publicly accessible HTTP(S) image URL. |
| input.generate_type | string | No | — | Choose Normal for a textured model or Geometry for a geometry-only white model. |
| input.enable_pbr | boolean | No | — | Set true to generate PBR materials in textured mode. Geometry mode takes precedence. |
| input.face_count | integer | No | 500000 | Set an integer target face count from 40000 to 1500000. Default: 500000. |
| input.back_image_url | string | No | — | Provide a public HTTP(S) image URL showing the same object from the back view. |
| input.left_image_url | string | No | — | Provide a public HTTP(S) image URL showing the same object from the left view. |
| input.right_image_url | string | No | — | Provide a public HTTP(S) image URL showing the same object from the right view. |
| input.top_image_url | string | No | — | Provide a public HTTP(S) image URL showing the same object from the top view. |
| input.bottom_image_url | string | No | — | Provide a public HTTP(S) image URL showing the same object from the bottom view. |
| input.left_front_image_url | string | No | — | Provide a public HTTP(S) image URL showing the same object from the left front view. |
| input.right_front_image_url | string | No | — | Provide a public HTTP(S) image URL showing the same object from the right front view. |
| callback_url | string | No | — | Public HTTP(S) URL for task completion notifications. |
The task response contains status, progress, and generated files.
| Field | Type | Description |
|---|---|---|
| code | integer | Response code. |
| data.task_id | string | Task identifier. |
| data.status | string | not_started, running, finished, failed |
| data.progress | integer | Generation progress from 0 to 100. |
| data.files | array | Generated model, image, and companion files. |
| data.files[].file_url | string | File download URL. |
| data.files[].file_type | string | 3d, image, or other. |
| data.files[].label | string | File role, such as model_glb or thumbnail. |
| data.files[].format | string | File format, such as glb or png. |
| data.files[].file_name | string | File name when provided. |
| data.files[].file_size | integer | File size in bytes when provided. |
| data.error_message | string | null | Task error details. |
Use the task state to decide when to check again or read the result.
not_startedThe task has been accepted and is waiting to start.
running3D model generation is in progress. Continue checking the same task.
finishedGeneration is complete. Read files to retrieve the 3D assets.
failedGeneration failed. Read error_message before deciding whether to submit a new request.
| Item | Value | Description |
|---|---|---|
| Input | image_urls | Provide exactly one publicly accessible HTTP(S) image URL. |
| Generation mode | Normal / Geometry | Choose Normal for a textured model or Geometry for a geometry-only white model. |
| Materials | enable_pbr | Set true to generate PBR materials in textured mode. Geometry mode takes precedence. |
Hunyuan 3D v3.1 Pro Image to 3D is a Tencent model for generating 3D objects from reference images. Use one front image and seven named extra views to provide visual information about different sides of the object. Face-count and generation-mode controls guide geometry, while PBR settings guide material generation. You can call it programmatically or try it from the playground above.
Place one front-view image in image_urls. Use a clearly visible, single object with consistent framing so that its silhouette and main parts are easy to distinguish.
Provide one primary image plus up to seven named extra views: back, left, right, top, bottom, left_front, and right_front. Each extra view has its own image URL field.
Use images of the same object with consistent materials, lighting, and proportions. Assign each image to the field matching its viewing direction, and keep the object framing comparable across views.
left_front_image_url and right_front_image_url provide front-diagonal references. Use them to show the transition from the front to each side, such as a handle, corner, or projecting component.
Set face_count to an integer from 40000 to 1500000. The default target is 500000. Review the generated mesh in your 3D application against the needs of the scene.
Choose Normal with enable_pbr: true for textured generation with PBR materials. Choose Geometry for a white model focused on shape; this mode takes precedence over the material setting.
Choose Pro Image to 3D for named multi-view references and a configurable face count. Rapid Image to 3D uses one reference image with geometry and PBR controls.