Meshy 7.1 Text to 3D API
meshy/v7.1/text-to-3dMeshy 7.1 Text to 3D 将物体文字描述转为带贴图的三维模型,支持最高4K 几何、四边面或三角面拓扑以及 PBR 贴图。可先预览几何,也可直接生成贴图模型,并为人形角色添加骨骼与动画预设。
Input
Output
Meshy 7.1 Text to 3D 模型已生成Meshy 7.1 Text to 3D API
快速开始
提交 Meshy 7.1 Text to 3D 输入,保留 task_id,并查询任务以读取返回文件。
为 Meshy 7.1 Text to 3D 请求提供身份凭证
在 Bearer 身份验证请求头中发送 Vidgo API 密钥。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer YOUR_API_KEY
提交 Meshy 7.1 Text to 3D 请求
将 model 放在请求根层,将 prompt 放入 input。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "meshy/v7.1/text-to-3d",
"input": {
"prompt": "A vintage brass diving helmet with three round porthole windows, riveted seams, a leather neck collar and a small air valve on the side",
"mode": "full",
"model_type": "standard",
"geometry_resolution": "4k",
"topology": "triangle",
"target_polycount": 30000,
"should_remesh": true,
"symmetry_mode": "auto",
"enable_pbr": true
}
}
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"查询 Meshy 7.1 Text to 3D 任务
使用返回的 task_id 查询,直到 status 为 finished 或 failed。
状态接口
GET https://api.vidgo.ai/api/generate/status/{task_id}当 status 为 finished 时,检查 files 并下载返回的资产。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "P3B7BJMQ44EBHPR5",
"status": "not_started",
"created_time": "2026-11-05T07:07:06"
}
}{
"code": 200,
"data": {
"task_id": "P3B7BJMQ44EBHPR5",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/meshy/v7.1/text-to-3d/v2/01/model-01.glb",
"file_type": "3d",
"label": "model_glb",
"format": "glb",
"file_name": "model-01.glb"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/meshy/v7.1/text-to-3d/v2/01/model-01.fbx",
"file_type": "3d",
"label": "model_fbx",
"format": "fbx",
"file_name": "model-01.fbx"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/meshy/v7.1/text-to-3d/v2/01/model-01.obj",
"file_type": "3d",
"label": "model_obj",
"format": "obj",
"file_name": "model-01.obj"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/meshy/v7.1/text-to-3d/v2/01/model-01.stl",
"file_type": "3d",
"label": "model_stl",
"format": "stl",
"file_name": "model-01.stl"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/meshy/v7.1/text-to-3d/v2/01/model-01.usdz",
"file_type": "3d",
"label": "model_usdz",
"format": "usdz",
"file_name": "model-01.usdz"
},
{
"file_url": "https://cdn.vidgo.ai/apis/models/meshy/v7.1/text-to-3d/v2/01/thumbnail-01.png",
"file_type": "image",
"label": "thumbnail",
"format": "png",
"file_name": "thumbnail-01.png"
}
],
"created_time": "2026-11-05T07:07:06",
"error_message": null,
"progress": 100
}
}读取 Meshy 7.1 Text to 3D 文件
逐项读取返回的 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": "meshy/v7.1/text-to-3d",
"input": {
"prompt": "A vintage brass diving helmet with three round porthole windows, riveted seams, a leather neck collar and a small air valve on the side",
"mode": "full",
"model_type": "standard",
"geometry_resolution": "4k",
"topology": "triangle",
"target_polycount": 30000,
"should_remesh": true,
"symmetry_mode": "auto",
"enable_pbr": true
}
}
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。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | meshy/v7.1/text-to-3d |
| input | object | 是 | — | 当前端点的生成参数。 |
| input.prompt | string | 是 | — | 用1–600个字符描述一个物体及其主要部件、形状和材质。 |
| input.mode | string | 否 | full | preview 仅生成几何(160 credits);full 额外生成贴图(240 credits)。默认 full。 |
| input.model_type | string | 否 | standard | standard 保留常规网格;smart-topology 生成更整洁轻量的网格,目标面数为100–15,000。默认 standard。 |
| input.geometry_resolution | string | 否 | — | 几何细节:standard, 2k, 4k。需 model_type 为 standard。不设置时使用默认值。 |
| input.topology | string | 否 | triangle | triangle 三角面或 quad 四边面。默认 triangle。 |
| input.target_polycount | integer | 否 | 30000 | 目标面数:100–300,000(默认30,000),smart-topology 时为100–15,000(默认4,000)。 |
| input.should_remesh | boolean | 否 | true | true 按所选拓扑和目标面数重建网格;false 保留原始三角网格。默认 true。 |
| input.symmetry_mode | string | 否 | auto | off、auto 或 on。默认 auto。 |
| input.seed | integer | 否 | — | 可选整数,用于复现同一组生成设置。 |
| input.enable_prompt_expansion | boolean | 否 | false | true 时由模型为简短提示词补充细节。默认 false。 |
| input.enable_pbr | boolean | 否 | false | 在基础色之外生成金属度、粗糙度和法线贴图。 |
| input.texture_prompt | string | 否 | — | 最多600个字符,描述颜色、图案和材质。 |
| input.texture_image_url | string | 否 | — | 作为贴图参考的公开图片 URL。 |
| input.pose_mode | string | 否 | "" | 角色可选 a-pose 或 t-pose,留空表示不指定姿态。默认空。 |
| input.enable_rigging | boolean | 否 | false | 添加人形骨骼(+40 credits)。默认 false。 |
| input.rigging_height_meters | number | 否 | 1.7 | 骨骼绑定时的角色身高(米),需大于0。默认1.7。 |
| input.enable_animation | boolean | 否 | false | 应用动画预设(+24 credits),需 enable_rigging 为 true。 |
| input.animation_action_id | integer | 否 | 92 | 动画预设 ID,取值0–696。默认92。 |
| input.enable_safety_checker | boolean | 否 | true | 启用上游安全检查。默认 true。 |
| callback_url | string | 否 | — | 提供公开可访问的 HTTP(S) URL,接收任务完成或失败通知。 |
响应字段
状态响应返回任务状态、进度及生成文件。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | API 响应代码。 |
| data.task_id | string | 用于查询状态的任务 ID。 |
| data.status | string | 任务状态:not_started、running、finished 或 failed。 |
| data.progress | integer | 返回的生成进度,范围为 0–100。 |
| data.files | array | 生成的模型、预览图片和附属文件。 |
| data.files[].file_url | string | 返回文件的 URL。 |
| 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 | 失败任务的错误详情。 |
任务状态
使用 task_id 查询同一生成任务,直到任务完成或失败。
not_started任务已接收,等待开始生成。
running正在生成三维模型;继续查询同一任务。
finished生成已完成;从 files 读取资产。
failed任务失败;再次提交前先读取 error_message。
轮询与错误处理
- 保留任务 ID状态查询中断后,使用相同 task_id 读取最新状态。
- 下载返回的资产用每个文件的 file_url 与 file_name 下载模型及附属资产。
- 检查失败任务当 status 为 failed 时,读取 error_message,再核对输入并决定是否重新提交。
端点规格
| 项目 | 规格 | 说明 |
|---|---|---|
| 输入 | 提示词,1–600字符 | 描述一个物体及其部件和材质。 |
| 几何分辨率 | standard, 2k, 4k | 需 model_type 为 standard。 |
| 拓扑 | triangle, quad | 目标面数100–300,000;智能拓扑为100–15,000。 |
| 输出文件 | GLB, FBX, OBJ, USDZ, STL | 返回格式因任务而异,请读取 files 获取完整列表。 |
| 价格 | 默认 $1.200 | 几何160 credits + 贴图80;骨骼+40,动画+24。 |
Meshy 7.1 Text to 3D API 常见问题
Meshy 7.1 Text to 3D API 是什么?
Meshy 7.1 Text to 3D 是 Meshy 用于根据文字描述生成三维资产的模型。它将提示词转为带贴图的模型,支持最高4K 几何、三角面或四边面拓扑、PBR 贴图以及可选的骨骼与动画。基于 Meshy 注重细节的 7.1 系列,它遵循你描述的部件与材质,同时让你设置目标面数和对称。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Meshy 7.1 Text to 3D 什么时候用 preview 模式?
迭代提示词时使用 mode preview,以160 credits 仅获取几何。确定要保留的版本后切换为 full(默认,240 credits)生成贴图模型。
Meshy 7.1 Text to 3D 支持4K 几何吗?
支持。在 model_type 为 standard 时将 geometry_resolution 设为 4k。该选项控制网格细节,而非贴图尺寸;standard 和 2k 结果更轻。
Meshy 7.1 Text to 3D 的提示词扩展如何工作?
将 enable_prompt_expansion 设为 true,模型会在生成前为简短提示词补充细节。希望严格按描述生成时保持关闭,并可填写 seed 复现设置。
Meshy 7.1 Text to 3D 的费用是多少?
默认请求带贴图,费用为240 credits($1.200)。仅几何为160 credits($0.800);骨骼绑定增加40 credits($0.200),动画增加24 credits($0.120)。分辨率、拓扑和面数不影响价格。
Meshy 7.1 Text to 3D 如何为角色绑定骨骼和动画?
将 enable_rigging 设为 true 添加人形骨骼,并用 rigging_height_meters 设置身高(默认1.7)。再将 enable_animation 设为 true,从0–696中选择 animation_action_id(默认92)。A 姿势或 T 姿势的输入有助于骨骼绑定。
Meshy 7.1 Text to 3D 返回哪些文件?
任务完成后文件列在 files 中:通常包括 GLB,并视情况包括 FBX、OBJ、USDZ 或 STL、贴图和缩略图。请求骨骼与动画时会额外返回相应文件。
Meshy 7.1 Text to 3D 与 Meshy 6 Text to 3D 有什么不同?
Meshy 7.1 Text to 3D 属于 Meshy 更新、更注重细节的系列,几何分辨率最高4K,并支持智能拓扑,动画预设编号为0–696。Meshy 6 Text to 3D 在 Vidgo 上每次60 credits($0.300),适合快速草稿;Meshy 7.1 Text to 3D 视选项为160–304 credits。