
蜷缩犰狳
hunyuan-3d/v3.1/pro/image-to-3dHunyuan 3D v3.1 Pro Image to 3D 将正面图转化为三维模型,提供七个附加视角、面数与 PBR 材质控制。搭配同一物体的对应角度图片,为各侧形体重建补充视觉依据。
Hunyuan 3D v3.1 Pro Image to 3D API
提交输入,保存 task_id,并查询生成完成后的模型文件。
通过 Bearer 认证传入 Vidgo API Key。
https://api.vidgo.ai/api/generate/submit将 model 放在请求根级,将生成设置放入 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"使用返回的 task_id 查询,直至状态变为 finished 或 failed。
GET https://api.vidgo.ai/api/generate/status/{task_id}查询任务,在状态为 finished 时读取 files。
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
}
}逐项读取 files 中的 file_url、file_type、label 与 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
done将生成参数放入 input,model 和 callback_url 保留在请求根级。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | hunyuan-3d/v3.1/pro/image-to-3d |
| input | object | 是 | — | 本次生成的输入与控制参数。 |
| input.prompt | string | 否 | — | 可填写非空文字描述,补充物体信息。 |
| input.image_urls | string[] | 是 | — | 提供恰好一个公开可访问的 HTTP(S) 图片 URL。 |
| input.generate_type | string | 否 | — | 选择 Normal 生成纹理模型,或选择 Geometry 生成几何白模。 |
| input.enable_pbr | boolean | 否 | — | 在纹理模式中设为 true 生成 PBR 材质,几何模式优先于此设置。 |
| input.face_count | integer | 否 | 500000 | 输入 40000–1500000 的整数目标面数,默认 500000。 |
| input.back_image_url | string | 否 | — | 提供同一物体背面视角的公开 HTTP(S) 图片 URL。 |
| input.left_image_url | string | 否 | — | 提供同一物体左侧视角的公开 HTTP(S) 图片 URL。 |
| input.right_image_url | string | 否 | — | 提供同一物体右侧视角的公开 HTTP(S) 图片 URL。 |
| input.top_image_url | string | 否 | — | 提供同一物体顶部视角的公开 HTTP(S) 图片 URL。 |
| input.bottom_image_url | string | 否 | — | 提供同一物体底部视角的公开 HTTP(S) 图片 URL。 |
| input.left_front_image_url | string | 否 | — | 提供同一物体左前方视角的公开 HTTP(S) 图片 URL。 |
| input.right_front_image_url | string | 否 | — | 提供同一物体右前方视角的公开 HTTP(S) 图片 URL。 |
| callback_url | string | 否 | — | 任务完成通知的公开 HTTP(S) URL。 |
任务响应包含状态、进度和生成文件。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 响应代码。 |
| data.task_id | string | 任务标识。 |
| data.status | string | not_started、running、finished、failed |
| data.progress | integer | 生成进度,范围为 0–100。 |
| data.files | array | 生成的模型、图片与配套文件。 |
| data.files[].file_url | string | 文件下载地址。 |
| data.files[].file_type | string | 3d、image 或 other。 |
| data.files[].label | string | 文件用途,例如 model_glb 或 thumbnail。 |
| data.files[].format | string | 文件格式,例如 glb 或 png。 |
| data.files[].file_name | string | 返回的文件名称。 |
| data.files[].file_size | integer | 返回的文件大小,单位为字节。 |
| data.error_message | string | null | 任务错误详情。 |
根据任务状态决定继续查询或读取结果。
not_started任务已接收,等待开始。
running正在生成三维模型,继续查询当前任务。
finished生成完成,从 files 获取三维资产。
failed生成失败,查看 error_message 后决定是否重新提交。
| 项目 | 规格 | 说明 |
|---|---|---|
| 输入 | image_urls | 提供恰好一个公开可访问的 HTTP(S) 图片 URL。 |
| 生成模式 | Normal / Geometry | 选择 Normal 生成纹理模型,或选择 Geometry 生成几何白模。 |
| 材质 | enable_pbr | 在纹理模式中设为 true 生成 PBR 材质,几何模式优先于此设置。 |
Hunyuan 3D v3.1 Pro Image to 3D 是腾讯用于根据参考图片生成三维物体的模型。使用一张正面图与七个具名附加视角,分别补充物体不同侧面的视觉信息。目标面数与生成模式共同控制几何,PBR 设置用于纹理模式的材质生成。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
在 image_urls 中放入一张正面图片。选择主体清晰、构图完整的单个物体,让轮廓和主要部件容易辨认,并为附加视角保持一致的主体比例。
提供一张主图,并搭配最多七个具名附加视角:back、left、right、top、bottom、left_front 和 right_front。每个附加视角使用各自的图片 URL 字段。
使用同一物体的图片,保持材质、光照与主体比例一致。按拍摄方向将图片填入对应字段,让各视角的取景范围相近,便于共同描述物体。
left_front_image_url 和 right_front_image_url 分别提供左前方与右前方的参考。用这些视角展示正面到侧面的过渡,例如把手、转角或向外突出的部件。
将 face_count 设置为 40000–1500000 的整数,默认目标为 500000。生成后在三维软件中检查网格,并结合场景需求评估模型复杂度。
选择 Normal 并设置 enable_pbr: true,可生成带 PBR 材质的纹理模型。选择 Geometry 可生成用于形体检查的白模,此模式优先于材质设置。
需要具名多视角参考和目标面数控制时,选择 Pro Image to 3D。Rapid Image to 3D 使用一张参考图,提供几何模式与 PBR 控制项。