Tripo3D H3.1 Image to 3D API
tripo3d/h3.1/image-to-3dTripo3D H3.1 Image to 3D 将一张物体图片转为高细节三维模型,呈现主体轮廓与表面特征,并提供几何和材质设置。选用完整、清晰的参考图,再调整几何质量与目标面数来组织模型细节。
Input
拖拽文件、粘贴剪贴板素材,或输入 URL。 提供一张图片的地址。
1/1 个素材
Output
已就绪Tripo3D H3.1 Image to 3D API
快速开始
提交 Tripo3D H3.1 Image to 3D 任务并获取模型文件。
连接 Vidgo
在服务端保存 API Key,并作为 Bearer token 发送。
- 端点
- POST
https://api.vidgo.ai/api/generate/submit - 认证
- Authorization: Bearer VIDGO_API_KEY
提交三维任务
选择主体完整、轮廓清楚的图片,保留材质特征和关键结构。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "tripo3d/h3.1/image-to-3d",
"input": {
"texture": true,
"pbr": true,
"quad": false,
"face_limit": 150000,
"texture_quality": "detailed",
"geometry_quality": "detailed",
"model_seed": 310104,
"texture_seed": 310204,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/tripo3d/h3.1/image-to-3d/v1/01-chameleon/input-01.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 时读取全部文件;finished 或 failed 时停止轮询。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "O4C9K7R5J31MY34O",
"status": "running",
"created_time": "2026-09-28T14:36:43"
}
}{
"code": 200,
"data": {
"task_id": "O4C9K7R5J31MY34O",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/tripo3d/h3.1/image-to-3d/v1/01-chameleon/output-01.glb",
"file_type": "3d"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/tripo3d/h3.1/image-to-3d/v1/01-chameleon/output-02.png",
"file_type": "image"
}
],
"created_time": "2026-09-28T14:36:43",
"error_message": null,
"progress": 100
}
}完整轮询示例
提交请求并查询状态,直至任务结束。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "tripo3d/h3.1/image-to-3d",
"input": {
"texture": true,
"pbr": true,
"quad": false,
"face_limit": 150000,
"texture_quality": "detailed",
"geometry_quality": "detailed",
"model_seed": 310104,
"texture_seed": 310204,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/tripo3d/h3.1/image-to-3d/v1/01-chameleon/input-01.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请求参数
在请求根层设置 model 和可选 callback_url,将以下参数放入 input。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| image_urls | string[] | 是 | — | 提供一张图片的地址。 |
| face_limit | integer | 可选 | — | 目标面数为 1,000–2,000,000 之间的整数。 |
| texture | boolean | 可选 | true | 生成模型纹理,默认 true。 |
| pbr | boolean | 可选 | — | 启用 Texture 时生成基于物理渲染的材质。 |
| model_seed | integer | 可选 | — | 可选整数,用于控制模型生成的随机种子。 |
| texture_seed | integer | 可选 | — | 可选整数,用于控制纹理生成的随机种子。 |
| texture_quality | string | 可选 | standard | 启用 Texture 时设置纹理细节:standard 或 detailed,默认 standard。 |
| geometry_quality | string | 可选 | standard | 设置几何细节:standard 或 detailed,默认 standard。 |
| auto_size | boolean | 可选 | — | 自动调整生成模型的尺寸。 |
| quad | boolean | 可选 | false | 生成四边形网格拓扑,默认 false。 |
响应字段
读取任务状态及全部结果文件,并保留可用的文件元数据。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 0 或 200 表示请求成功。 |
| data.task_id | string | 用于查询状态的任务标识。 |
| data.status | string | not_started、running、finished 或 failed。 |
| 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。 |
| data.files[].content_type | string | 可用的 MIME 类型。 |
| data.files[].file_name | string | 可用的文件名称。 |
| data.files[].file_size | integer | 可用的文件大小,单位为字节。 |
| data.error_message | string | null | 任务失败原因。 |
任务生命周期
排队或生成中继续查询,任务完成或失败时结束查询。
not_started排队中
running生成中
finished已就绪
failed失败
请求处理
- 认证在 Authorization 请求头中发送有效的 API Key。
- 状态查询每 2–5 秒查询一次,对 429/5xx 响应使用退避,并设置总超时。
- 回调在请求根层设置公开 callback_url,接收完成或失败的任务通知。
模型规格
| 项目 | 取值 | 说明 |
|---|---|---|
| 模型 | tripo3d/h3.1/image-to-3d | 一张物体图片 |
| face_limit | 1000–2000000 | 目标面数为 1,000–2,000,000 之间的整数。 |
| geometry_quality / texture_quality | standard / detailed | 分别设置几何与纹理细节。 |
Tripo3D H3.1 Image to 3D API 常见问题
Tripo3D H3.1 Image to 3D API 是什么?
Tripo3D H3.1 Image to 3D 是 Tripo AI 用于根据单张物体图片生成三维资产的模型。它将图片中的主体转为可预览的高细节模型,并提供几何质量、纹理质量和 PBR 材质设置。其高密度几何生成侧重呈现可见轮廓与细部,参考图和目标面数分别用于指导外观与网格密度。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Tripo3D H3.1 Image to 3D 适合什么参考图?
选择一张主体完整、边界清楚、表面细节可见的物体图片。简洁背景和均匀光照有助于展示轮廓与材质特征。
Tripo3D H3.1 Image to 3D 怎样呈现细小部件?
把支脚、把手等部件完整纳入画面,并选用能展示其连接位置和体积的角度。预览生成模型时,可旋转检查这些部件。
Tripo3D H3.1 Image to 3D 与 Multiview to 3D 怎样选?
Image to 3D 在 Image Urls 中使用一张物体图片;有同一物体的 2–4 张不同角度图片时,选择 Tripo3D H3.1 Multiview to 3D。
Tripo3D H3.1 Image to 3D 怎样设置产品模型的几何细节?
Geometry Quality 可选 standard 或 detailed,Face Limit 可填写 1,000–2,000,000 之间的目标面数。根据产品轮廓和需要查看的细小结构设置几何细节。
Tripo3D H3.1 Image to 3D 怎样配置表面材质?
启用 Texture 后,选择 standard 或 detailed 的 Texture Quality;需要物理渲染材质时,将 Pbr 设为 true。
Tripo3D H3.1 Image to 3D 的 Quad 有什么作用?
将 Quad 设为 true 可请求四边形网格拓扑。该选项可与几何质量设置组合,用于规划后续资产处理流程。

