Hunyuan 3D v3.1 Rapid Image to 3D API
hunyuan-3d/v3.1/rapid/image-to-3dHunyuan 3D v3.1 Rapid Image to 3D turns one reference image into a 3D asset with geometry and PBR material controls. Use a clear view of the object to guide its shape, then inspect a white model or textured result.
Hunyuan 3D v3.1 Rapid Image to 3D API
How to Use API
Submit the input, retain the task_id, and retrieve the completed model files.
Authenticate your request
Send your Vidgo API key with Bearer authentication.
- Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Authentication
- Authorization: Bearer YOUR_API_KEY
Submit the input
Place model at the root and generation settings inside input.
REQUEST_BODY=$(cat <<'JSON'
{
"model": "hunyuan-3d/v3.1/rapid/image-to-3d",
"input": {
"enable_geometry": false,
"enable_pbr": false,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/rapid/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"Follow the task
Query the returned task_id until the status is finished or failed.
Status endpoint
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": "TPJ7YOJUFEGLC6UM",
"status": "running",
"created_time": "2026-09-27T22:20:05"
}
}{
"code": 200,
"data": {
"task_id": "TPJ7YOJUFEGLC6UM",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/rapid/image-to-3d/v1/02/E7PJ4ZBWIYF8Q6RH_1.obj",
"file_type": "3d"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/rapid/image-to-3d/v1/02/E7PJ4ZBWIYF8Q6RH_2.png",
"file_type": "image"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/rapid/image-to-3d/v1/02/material.mtl",
"file_type": "3d"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/rapid/image-to-3d/v1/02/texture_20250901.png",
"file_type": "image"
}
],
"created_time": "2026-09-27T22:20:05",
"error_message": null,
"progress": 100
}
}Read the generated files
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/rapid/image-to-3d",
"input": {
"enable_geometry": false,
"enable_pbr": false,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/hunyuan-3d/v3.1/rapid/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
doneAPI Request Parameters
Place generation parameters inside input; keep model and callback_url at the root.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| model | string | Yes | — | hunyuan-3d/v3.1/rapid/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.enable_geometry | boolean | No | — | Set true for a geometry-only white model or false for textured generation. |
| input.enable_pbr | boolean | No | — | Set true to generate PBR materials in textured mode. Geometry mode takes precedence. |
| callback_url | string | No | — | Public HTTP(S) URL for task completion notifications. |
API Response Fields
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. |
API Task Lifecycle
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.
API Result Handling
- Keep the current task identifierIf a status request is interrupted, query the same task_id again to recover its latest state.
- Read the generated filesUse file_url and file_name to download each returned asset.
- Inspect a failed taskWhen status is failed, read error_message and review the input and settings before submitting a new generation.
API Specifications
| Item | Value | Description |
|---|---|---|
| Input | image_urls | Provide exactly one publicly accessible HTTP(S) image URL. |
| Generation mode | enable_geometry | Set true for a geometry-only white model or false for textured generation. |
| Materials | enable_pbr | Set true to generate PBR materials in textured mode. Geometry mode takes precedence. |
Explore More Hunyuan 3D v3.1 Models
Hunyuan 3D v3.1 Rapid Image to 3D API frequently asked questions
What is the Hunyuan 3D v3.1 Rapid Image to 3D API?
Hunyuan 3D v3.1 Rapid Image to 3D is a Tencent model for generating 3D objects from reference images. Provide one object image through a public URL or upload it directly in the playground. The geometry switch selects white-model output, while PBR settings guide materials in textured mode. You can call it programmatically or try it from the playground above.
Which photo works well with Hunyuan 3D v3.1 Rapid Image to 3D?
Choose a clear image of one object with its main parts visible. Use a simple background and enough space around the silhouette to make the subject easy to distinguish.
How many reference images does Hunyuan 3D v3.1 Rapid Image to 3D use?
Provide exactly one image URL in image_urls. Choose the angle that best shows the object shape and the features you want to guide the generation.
How should I frame a product for Hunyuan 3D v3.1 Rapid Image to 3D?
Keep the full object in frame and make it the dominant subject. Use even lighting to show its shape and surface appearance clearly, including handles, corners, and other characteristic parts.
How do I generate a white model with Hunyuan 3D v3.1 Rapid Image to 3D?
Set enable_geometry to true. The result focuses on geometry for inspecting shape and proportions; this mode takes precedence over the PBR material setting.
How do I generate PBR materials with Hunyuan 3D v3.1 Rapid Image to 3D?
Set enable_geometry to false and enable_pbr to true. Review the generated model alongside its returned texture and material files to assess its surface appearance.
When should I choose Pro instead of Hunyuan 3D v3.1 Rapid Image to 3D?
Choose Pro Image to 3D when you have additional views of the object or want to set a target face count. Rapid Image to 3D uses one image with geometry and PBR controls.
How can I use Hunyuan 3D v3.1 Rapid Image to 3D for product visualization?
Generate the object from a clear product image, inspect the returned 3D model, and download its files. Review the asset in your scene for scale, silhouette, and material appearance before assembling the product presentation.