Meshy 7.1 Image to 3D API
meshy/v7.1/image-to-3dMeshy 7.1 Image to 3D 将一张照片或概念图转为带贴图的三维模型,支持最高4K 几何、智能拓扑和 PBR 贴图。它沿用图片中的轮廓与表面细节,同时由你设置拓扑、面数、姿态和骨骼。
Input
Output
Meshy 7.1 Image to 3D 模型已生成Meshy 7.1 Image to 3D API
快速开始
提交 Meshy 7.1 Image to 3D 输入,保留 task_id,并查询任务以读取返回文件。
为 Meshy 7.1 Image to 3D 请求提供身份凭证
在 Bearer 身份验证请求头中发送 Vidgo API 密钥。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer YOUR_API_KEY
提交 Meshy 7.1 Image to 3D 请求
将 model 放在请求根层,将 image_urls 放入 input。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "meshy/v7.1/image-to-3d",
"input": {
"image_urls": [
"https://cdn.vidgo.ai/apis/models/meshy/v7.1/image-to-3d/v1/01/input-1.png"
],
"model_type": "standard",
"geometry_resolution": "4k",
"should_texture": true,
"enable_pbr": true,
"topology": "triangle",
"target_polycount": 30000,
"should_remesh": true,
"symmetry_mode": "auto"
}
}
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 Image 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": "12GKNDTSJZ15XDP0",
"status": "not_started",
"created_time": "2026-11-05T07:07:24"
}
}{
"code": 200,
"data": {
"task_id": "12GKNDTSJZ15XDP0",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/meshy/v7.1/image-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/image-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/image-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/image-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/image-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/image-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:24",
"error_message": null,
"progress": 100
}
}读取 Meshy 7.1 Image 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/image-to-3d",
"input": {
"image_urls": [
"https://cdn.vidgo.ai/apis/models/meshy/v7.1/image-to-3d/v1/01/input-1.png"
],
"model_type": "standard",
"geometry_resolution": "4k",
"should_texture": true,
"enable_pbr": true,
"topology": "triangle",
"target_polycount": 30000,
"should_remesh": true,
"symmetry_mode": "auto"
}
}
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/image-to-3d |
| input | object | 是 | — | 当前端点的生成参数。 |
| input.image_urls | string[] | 是 | — | 上传一张清晰的物体 JPG 或 PNG 图片,或填写公开的 HTTP(S) URL。 |
| input.should_texture | boolean | 否 | true | true 为模型生成贴图(+80 credits);false 仅返回几何。默认 true。 |
| 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.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张图片 | JPG 或 PNG 的 URL,或上传文件。 |
| 几何分辨率 | 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 Image to 3D API 常见问题
Meshy 7.1 Image to 3D API 是什么?
Meshy 7.1 Image to 3D 是 Meshy 用于根据单张图片生成三维资产的模型。它将一张照片或概念图转为带贴图的模型,支持最高4K 几何、智能拓扑、PBR 贴图和可选骨骼绑定。基于 Meshy 注重细节的 7.1 系列,它保留图片的轮廓和表面细节,同时由你控制拓扑与面数。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Meshy 7.1 Image to 3D 适合什么样的图片?
使用清晰、光线均匀的 JPG 或 PNG,物体居中、遮挡少、背景简洁。模型会根据可见面推断隐藏面,四分之三视角往往更有帮助。
Meshy 7.1 Image to 3D 支持4K 几何吗?
支持。在 model_type 为 standard 时将 geometry_resolution 设为 4k,可获得最密集的表面细节。它控制网格细节,而非贴图尺寸。
Meshy 7.1 Image to 3D 的智能拓扑有什么作用?
model_type smart-topology 生成更整洁轻量的网格,目标面数为100–15,000(默认4,000)。Geometry Resolution 与 standard 模型类型配合使用。
Meshy 7.1 Image to 3D 的费用是多少?
默认请求带贴图,费用为240 credits($1.200)。仅几何为160 credits($0.800);骨骼绑定增加40 credits($0.200),动画增加24 credits($0.120)。分辨率、拓扑和面数不影响价格。
Meshy 7.1 Image to 3D 如何为角色绑定骨骼和动画?
将 enable_rigging 设为 true 添加人形骨骼,并用 rigging_height_meters 设置身高(默认1.7)。再将 enable_animation 设为 true,从0–696中选择 animation_action_id(默认92)。A 姿势或 T 姿势的输入有助于骨骼绑定。
Meshy 7.1 Image to 3D 返回哪些文件?
任务完成后文件列在 files 中:通常包括 GLB,并视情况包括 FBX、OBJ、USDZ 或 STL、贴图和缩略图。请求骨骼与动画时会额外返回相应文件。
Meshy 7.1 Image to 3D 与 Meshy 6 Image to 3D 有什么不同?
Meshy 7.1 Image to 3D 属于 Meshy 更新、更注重细节的系列,几何分辨率最高4K,并支持智能拓扑,动画预设编号为0–696。Meshy 6 Image to 3D 在 Vidgo 上每次60 credits($0.300),适合快速草稿;Meshy 7.1 Image to 3D 视选项为160–304 credits。