为 Unreal 资产工作流准备图片生成的 GLB

1. 生成 GLB

使用公开图片 URL 提交一个图片任务。响应是异步的，因此保留返回的任务 ID。

export TO3D_KEY='YOUR_API_KEY'
export TO3D_IMAGE_URL='https://example.com/prop-or-character.jpg'

TASK_JSON=$(curl --fail-with-body --silent --show-error \
  https://api.to3d.app/api/trellis/tasks \
  -H "x-api-key: $TO3D_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -cn --arg image "$TO3D_IMAGE_URL" \
    '{task_type:"image-to-3d",input:{image:$image}}')")
TASK_ID=$(jq -er '.id' <<<"$TASK_JSON")

轮询并保存 GLB

轮询直到任务成功，然后保存 `output.model_file` 中的 URL。不要把轮询描述成第二次生成请求。

curl --fail-with-body --silent --show-error \
  "https://api.to3d.app/api/trellis/tasks/$TASK_ID" \
  -H "x-api-key: $TO3D_KEY" | jq '{id,status,output,error}'

MODEL_URL=$(curl --fail-with-body --silent --show-error \
  "https://api.to3d.app/api/trellis/tasks/$TASK_ID" \
  -H "x-api-key: $TO3D_KEY" | jq -er '.output.model_file')
curl --fail --location --silent --show-error "$MODEL_URL" --output unreal-candidate.glb

2. 需要人形绑定时请求 UE5 骨骼名称

将下载的 GLB 上传或放置在公开 URL 上，然后提交独立的 Skin Tokens 请求。轮询 `/api/skin_tokens/tasks/$RIG_ID`，成功后下载返回的 `output.model_file`。不要把两次调用描述成一次自动转换。

export TO3D_MODEL_URL='https://example.com/unreal-candidate.glb'
RIG_JSON=$(curl --fail-with-body --silent --show-error \
  https://api.to3d.app/api/skin_tokens/tasks \
  -H "x-api-key: $TO3D_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -cn --arg model "$TO3D_MODEL_URL" \
    '{task_type:"rig",input:{model:$model,bone_names:"ue5"}}')")
RIG_ID=$(jq -er '.id' <<<"$RIG_JSON")
printf 'Rig task: %s\n' "$RIG_ID"

3. 检查 Unreal 侧

使用项目采用的导入器和插件导入 GLB。检查资产的单位与方向、材质和纹理引用、骨架层级、绑定姿势，以及动画或重定向行为。

• `ue5` 是 API 的骨骼命名选项。
• #56 没有执行 Unreal 导入或重定向验收测试，因此本教程不能承诺现成的 Unreal 骨架、碰撞设置、LOD 或游戏动画。

把样例作为结构参考

#56 检查的四个公开样例都包含一个 skin、关节、权重、UV 和一张内嵌 PNG 纹理。用它们理解可能收到的文件结构；每次新生成都要单独进行资产检查。

• 如果目标是静态道具，可以跳过绑定请求，改为验证比例和材质。