Hunyuan 3D v3.1 Rapid Image to 3D API
hunyuan-3d/v3.1/rapid/image-to-3dHunyuan 3D v3.1 Rapid Image to 3D 将单张参考图转化为三维资产,提供几何与 PBR 材质控制。使用主体清晰的图片引导物体形状,再检查几何白模或纹理模型。
Hunyuan 3D v3.1 Rapid Image to 3D API
如何使用 API
提交输入,保存 task_id,并查询生成完成后的模型文件。
验证请求身份
通过 Bearer 认证传入 Vidgo API Key。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer YOUR_API_KEY
提交输入
将 model 放在请求根级,将生成设置放入 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"查询任务
使用返回的 task_id 查询,直至状态变为 finished 或 failed。
状态接口
GET https://api.vidgo.ai/api/generate/status/{task_id}查询任务,在状态为 finished 时读取 files。
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
}
}读取生成文件
逐项读取 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/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 请求参数
将生成参数放入 input,model 和 callback_url 保留在请求根级。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | hunyuan-3d/v3.1/rapid/image-to-3d |
| input | object | 是 | — | 本次生成的输入与控制参数。 |
| input.prompt | string | 否 | — | 可填写非空文字描述,补充物体信息。 |
| input.image_urls | string[] | 是 | — | 提供恰好一个公开可访问的 HTTP(S) 图片 URL。 |
| input.enable_geometry | boolean | 否 | — | 设为 true 生成几何白模,设为 false 使用纹理模式。 |
| input.enable_pbr | boolean | 否 | — | 在纹理模式中设为 true 生成 PBR 材质,几何模式优先于此设置。 |
| callback_url | string | 否 | — | 任务完成通知的公开 HTTP(S) URL。 |
API 响应字段
任务响应包含状态、进度和生成文件。
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 | 任务错误详情。 |
API 任务状态
根据任务状态决定继续查询或读取结果。
not_started任务已接收,等待开始。
running正在生成三维模型,继续查询当前任务。
finished生成完成,从 files 获取三维资产。
failed生成失败,查看 error_message 后决定是否重新提交。
API 结果处理
- 保留当前任务标识状态查询中断时,使用同一 task_id 再次查询,获取最新状态。
- 读取生成文件使用每个文件条目的 file_url 和 file_name 下载生成资产。
- 检查失败任务状态为 failed 时,查看 error_message 并检查输入与设置,再提交新的生成任务。
API 规格
| 项目 | 规格 | 说明 |
|---|---|---|
| 输入 | image_urls | 提供恰好一个公开可访问的 HTTP(S) 图片 URL。 |
| 生成模式 | enable_geometry | 设为 true 生成几何白模,设为 false 使用纹理模式。 |
| 材质 | enable_pbr | 在纹理模式中设为 true 生成 PBR 材质,几何模式优先于此设置。 |
Hunyuan 3D v3.1 Rapid Image to 3D API 常见问题
Hunyuan 3D v3.1 Rapid Image to 3D API 是什么?
Hunyuan 3D v3.1 Rapid Image to 3D 是腾讯用于根据参考图片生成三维物体的模型。通过公开 URL 或体验区上传一张物体图片,为三维生成提供参考。几何开关用于选择白模,PBR 设置用于纹理模式的材质生成。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Hunyuan 3D v3.1 Rapid Image to 3D 适合什么参考照片?
选择单个物体的清晰图片,让主要部件完整可见。使用简洁背景,在轮廓周围保留适当空间,使主体容易辨认。
Hunyuan 3D v3.1 Rapid Image to 3D 使用几张参考图?
在 image_urls 中提供恰好一个图片 URL。选择最能表现物体形状和关键特征的角度,为生成提供明确的视觉参考。
Hunyuan 3D v3.1 Rapid Image to 3D 的产品图片怎样构图?
将完整物体放在画面内,并让它成为主要主体。使用均匀光照展示形状与表面外观,让把手、转角等具有辨识度的部件清晰可见。
Hunyuan 3D v3.1 Rapid Image to 3D 怎样生成几何白模?
将 enable_geometry 设置为 true,生成用于检查形状和比例的几何模型。此模式优先于 PBR 材质设置,便于集中评审物体结构。
Hunyuan 3D v3.1 Rapid Image to 3D 怎样生成 PBR 材质?
设置 enable_geometry: false 和 enable_pbr: true。结合生成的模型、纹理和材质文件检查表面外观,为后续场景应用准备资产。
Hunyuan 3D v3.1 Rapid Image to 3D 与 Pro 怎样选择?
拥有物体的附加视角,或需要设置目标面数时,选择 Pro Image to 3D。Rapid Image to 3D 使用单张图片,提供几何与 PBR 控制项。
Hunyuan 3D v3.1 Rapid Image to 3D 怎样用于产品展示?
使用清晰的产品图片生成物体,检查返回的三维模型并下载文件。在场景中评估比例、轮廓与材质外观,再将资产用于产品展示制作。