
胡桃木座头鲸雕刻
meshy/v6/image-to-3dMeshy 6 Image to 3D 将单张物体图片转化为三维模型,支持设置拓扑、对称模式和纹理生成。参考图片提供物体形状依据,你可以再用重网格处理与材质引导调整生成资产。
Meshy 6 Image to 3D API
提交 Meshy 6 Image to 3D 输入,保留 task_id,并查询任务以读取返回文件。
在 Bearer 身份验证请求头中发送 Vidgo API 密钥。
https://api.vidgo.ai/api/generate/submit将 model 放在请求根层,将 image_urls 放入 input。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "meshy/v6/image-to-3d",
"input": {
"image_urls": [
"https://example.com/object-front.png"
],
"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"使用返回的 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": "your_task_id",
"status": "not_started",
"created_time": "2026-09-27T10:00:00"
}
}{
"code": 200,
"data": {
"task_id": "your_task_id",
"status": "finished",
"files": [
{
"file_url": "https://example.com/model.glb",
"file_type": "3d",
"label": "model_glb",
"format": "glb",
"file_name": "model.glb"
},
{
"file_url": "https://example.com/preview.png",
"file_type": "image",
"label": "thumbnail",
"format": "png"
}
],
"progress": 100,
"error_message": null
}
}逐项读取返回的 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/v6/image-to-3d",
"input": {
"image_urls": [
"https://example.com/object-front.png"
],
"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/v6/image-to-3d |
| input | object | 是 | — | 当前端点的生成参数。 |
| input.image_urls | array | 是 | — | 提供 1 张展示目标物体的公开可访问 HTTP(S) 图片 URL。 |
| input.topology | string | 否 | triangle | 选择 triangle 三角面或 quad 四边面拓扑;默认 triangle。 |
| input.target_polycount | integer | 否 | 30000 | 以整数设置目标面数;默认 30000。 |
| input.should_remesh | boolean | 否 | true | 开启重网格处理,以应用所选拓扑与目标面数;默认 true。 |
| input.symmetry_mode | string | 否 | auto | 在 off、auto、on 中选择对称模式;默认 auto。 |
| input.should_texture | boolean | 否 | true | 根据参考图片生成纹理;默认 true。 |
| input.enable_pbr | boolean | 否 | — | 生成金属度、粗糙度与法线等 PBR 材质贴图。 |
| input.pose_mode | string | 否 | "" | 选择 a-pose、t-pose,或使用空字符串保留默认姿态;默认空字符串。 |
| input.texture_prompt | string | 否 | — | 描述颜色、图案和材质,为纹理生成提供文字引导。 |
| input.texture_image_url | string | 否 | — | 提供公开可访问的 HTTP(S) 图片 URL,作为纹理参考。 |
| input.enable_rigging | boolean | 否 | — | 为人形角色添加骨骼,以便设置姿态和动画。 |
| input.rigging_height_meters | number | 否 | 1.7 | 绑定骨骼时以米为单位设置角色身高;默认 1.7。 |
| input.enable_animation | boolean | 否 | — | 将 enable_rigging 设为 true 后应用动画预设。 |
| input.animation_action_id | integer | 否 | 1001 | 选择整数动画预设 ID;默认 1001。 |
| 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。
| 项目 | 规格 | 说明 |
|---|---|---|
| 输入 | 单张参考图片 | 提供恰好 1 张可公开访问的 HTTP(S) 图片。 |
| 拓扑 | triangle, quad | 选择 triangle 或 quad 网格拓扑。默认 triangle。 |
| 输出文件 | GLB, FBX, OBJ, USDZ, BLEND, STL | 从任务返回的 files 中读取模型格式、贴图与动画资产。 |
Meshy 6 Image to 3D 是 Meshy 用单张参考图片生成三维资产的模型。它结合物体图片与拓扑、重网格、对称模式和纹理设置生成模型。纹理与 PBR 选项用于处理材质,姿态、骨骼及动画设置可用于人形资产。你可以通过 API 提交任务,也可以在本页体验区上传图片运行。
提供恰好一张公开可访问的图片,让主体轮廓和主要部件清楚可见;该图片是此端点的物体形状参照。
将 should_texture 设为 true 可根据图片生成纹理,默认即为 true;也可用 texture_prompt 或 texture_image_url 补充表面引导。
通过 topology 选择 triangle 或 quad,并用整数 target_polycount 指定目标面数;should_remesh 用于应用网格设置,symmetry_mode 可选择 off、auto 或 on。
提供公开可访问的 texture_image_url 图片 URL,或用 texture_prompt 描述目标颜色与表面图案;两项均可用于纹理引导。
将 enable_pbr 设为 true,可请求金属度、粗糙度和法线材质贴图。
用 pose_mode 选择 a-pose 或 t-pose,再通过 enable_rigging 添加骨骼;启用骨骼后,可将 enable_animation 设为 true 应用动画预设。
有一张物体参考图时可选择 Image to 3D;如果有同一物体不同角度的 1–4 张图片,可选择 Meshy 6 Multi Image to 3D。