Tripo3D H3.1 Text to 3D API
tripo3d/h3.1/text-to-3dTripo3D H3.1 Text to 3D 根据文字描述生成高细节三维物体,支持高密度几何、纹理和 PBR 材质。用提示词指定轮廓与部件,再以几何质量和目标面数控制模型细节。
Input
Output
已就绪Tripo3D H3.1 Text to 3D API
快速开始
提交 Tripo3D H3.1 Text 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/text-to-3d",
"input": {
"texture": true,
"pbr": true,
"quad": false,
"face_limit": 150000,
"texture_quality": "detailed",
"geometry_quality": "detailed",
"model_seed": 310101,
"texture_seed": 310201,
"prompt": "A single miniature astronomical observatory tower, a complete freestanding architectural miniature on a small circular stone foundation. Warm weathered sandstone masonry, three deep arched windows, a sturdy exterior curved staircase wrapping halfway around the lower tower with a solid stone parapet, a large oxidized copper hemispherical dome with a narrow observation slit. Clearly separated stone blocks and subtle green copper patina. Compact elegant silhouette, physically coherent connected structure, detailed PBR materials. No terrain, no surrounding buildings, no text or people.",
"image_seed": 310301
}
}
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": "PD4SCVAC6VM5QYEX",
"status": "running",
"created_time": "2026-09-27T22:01:18"
}
}{
"code": 200,
"data": {
"task_id": "PD4SCVAC6VM5QYEX",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/tripo3d/h3.1/text-to-3d/v1/01-observatory/output-01.glb",
"file_type": "3d"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/tripo3d/h3.1/text-to-3d/v1/01-observatory/output-02.png",
"file_type": "image"
}
],
"created_time": "2026-09-27T22:01:18",
"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/text-to-3d",
"input": {
"texture": true,
"pbr": true,
"quad": false,
"face_limit": 150000,
"texture_quality": "detailed",
"geometry_quality": "detailed",
"model_seed": 310101,
"texture_seed": 310201,
"prompt": "A single miniature astronomical observatory tower, a complete freestanding architectural miniature on a small circular stone foundation. Warm weathered sandstone masonry, three deep arched windows, a sturdy exterior curved staircase wrapping halfway around the lower tower with a solid stone parapet, a large oxidized copper hemispherical dome with a narrow observation slit. Clearly separated stone blocks and subtle green copper patina. Compact elegant silhouette, physically coherent connected structure, detailed PBR materials. No terrain, no surrounding buildings, no text or people.",
"image_seed": 310301
}
}
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。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| prompt | string | 是 | — | 用 1–1,024 个字符描述物体、形状、材质和关键细节。 |
| negative_prompt | string | 可选 | — | 描述希望从文本生成物体中排除的特征,最多 1,024 个字符。 |
| face_limit | integer | 可选 | — | 目标面数为 1,000–2,000,000 之间的整数。 |
| texture | boolean | 可选 | true | 生成模型纹理,默认 true。 |
| pbr | boolean | 可选 | — | 启用 Texture 时生成基于物理渲染的材质。 |
| model_seed | integer | 可选 | — | 可选整数,用于控制模型生成的随机种子。 |
| image_seed | integer | 可选 | — | 可选整数,用于控制 Text to 3D 中间图像的随机种子。 |
| 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/text-to-3d | 物体的文字描述 |
| face_limit | 1000–2000000 | 目标面数为 1,000–2,000,000 之间的整数。 |
| geometry_quality / texture_quality | standard / detailed | 分别设置几何与纹理细节。 |
Tripo3D H3.1 Text to 3D API 常见问题
Tripo3D H3.1 Text to 3D API 是什么?
Tripo3D H3.1 Text to 3D 是 Tripo AI 用于根据文字描述生成三维物体的模型。它将提示词转为可预览的高细节资产,并提供几何质量、纹理质量和 PBR 材质设置。其高密度几何生成着重呈现轮廓与细部,提示词和目标面数则用于指导物体形态与网格密度。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Tripo3D H3.1 Text to 3D 的 Prompt 应怎样描述物体?
先写主体及整体轮廓,再补充比例、标志性部件和表面材质。Prompt 接受 1–1,024 个字符,可围绕一个物体组织描述。
Tripo3D H3.1 Text to 3D 怎样使用 Negative Prompt?
在 Negative Prompt 中写入需要排除的视觉特征,例如额外的把手或装饰;在 Prompt 中保留主体及希望生成的细节。该字段最多接受 1,024 个字符。
Tripo3D H3.1 Text to 3D 的三种 Seed 各控制什么?
Model Seed、Image Seed 和 Texture Seed 分别对应模型生成、中间图像及纹理生成的随机种子。比较不同设置时,将种子与提示词、质量选项一起记录。
Tripo3D H3.1 Text to 3D 怎样设置特写模型的几何细节?
Geometry Quality 可选 standard 或 detailed;Face Limit 可填写 1,000–2,000,000 之间的目标面数。根据需要查看的轮廓和细小部件设置几何细节。
Tripo3D H3.1 Text to 3D 怎样配置 PBR 材质?
启用 Texture 后,可选择 standard 或 detailed 的 Texture Quality,并将 Pbr 设为 true,请求带物理渲染材质的纹理模型。
什么时候选择 Tripo3D H3.1 Text to 3D?
当物体主要由文字构想定义时,使用 Text to 3D 描述其轮廓、结构和材质。已有单张物体图片时,可选择 Tripo3D H3.1 Image to 3D 作为图片输入方式。

