快速开始

一、控制台准备

注册账号并完成邮箱验证。
登录用户控制台，创建工程。
绑定有效证书并确认额度。
在工程设置中查看 Project Key。

平台转换支持：.prt、.prt.x、.step、.stp、.igs、.iges、.x_t、.sldprt、.catpart、.jt、.par、.psm、.sat、.sab。

请将 Project Key 放入服务端环境变量或密钥管理系统，不要写入浏览器代码、URL、LocalStorage 或 Cookie。

控制台截图应使用正式环境页面，并对邮箱、Project Key 和模型名称打码。线上 Demo：https://tiangongtuxue.com/manual/demo-app/。

接入流程图

二、换取访问令牌

export TUO_API_BASE_URL=https://tiangongtuxue.com/api
export TUO_PROJECT_KEY='在服务端配置，不要写入源码'
curl "$TUO_API_BASE_URL/app/projects/access-token" -H "Authorization: Bearer $TUO_PROJECT_KEY"

三、创建模型并取得上传授权

ACCESS_TOKEN='从上一步响应读取并短期缓存'
UPLOAD=$(curl -s "$TUO_API_BASE_URL/v1/models/upload-token" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"bracket.step","description":"quick start"}')
echo "$UPLOAD"

响应包含 modelId、uploadToken 和 uploadUrl。使用上传地址和凭证将文件直接上传到云存储，上传完成后平台会自动进入处理流程，不需要额外提交任务。

四、上传文件

创建模型接口返回的 uploadUrl 和 uploadToken 是一组配套的上传授权。上传时必须使用这两个字段，不要自行拼接上传地址，也不要把上传凭证保存为长期凭据。

使用 curl 上传

MODEL_ID=$(echo "$UPLOAD" | jq -r '.data.modelId')
UPLOAD_TOKEN=$(echo "$UPLOAD" | jq -r '.data.uploadToken')
UPLOAD_URL=$(echo "$UPLOAD" | jq -r '.data.uploadUrl')

curl --fail-with-body -X POST "$UPLOAD_URL" \
  -F "token=$UPLOAD_TOKEN" \
  -F "file=@bracket.step;filename=bracket.step"

表单字段说明：

字段	类型	说明
`token`	string	创建模型接口返回的一次性上传凭证
`file`	file	要上传的模型文件，文件名应与创建模型时的 `name` 对应

上传成功表示文件已提交到云存储；后续处理由平台自动触发，不需要再次调用“提交解析”接口。上传失败时请保留 modelId，根据 HTTP 状态和响应消息判断是否重新获取授权。

浏览器 JavaScript 上传

async function uploadModelFile(grant, file) {
  const form = new FormData();
  form.append('token', grant.uploadToken);
  form.append('file', file, file.name);

  const response = await fetch(grant.uploadUrl, {
    method: 'POST',
    body: form,
  });
  if (!response.ok) {
    throw new Error(`文件上传失败：${response.status}`);
  }
}

不要手动设置 Content-Type，浏览器会自动补充 multipart boundary。大文件建议展示上传进度，并在失败后重新获取上传授权。

上传后的状态

上传完成后，使用创建模型返回的 modelId 查询状态。上传回调尚未确认时可能仍为 uploading；文件确认后进入 uploaded，随后进入 queued 或 running。

五、查询状态和浏览结果

MODEL_ID='上一步响应中的 modelId'
curl -H "Authorization: Bearer $ACCESS_TOKEN" "$TUO_API_BASE_URL/v1/models/$MODEL_ID/result"

只有 status 为 succeeded 时才使用 url 或 imageUrl。

六、使用 Viewer

<div id="viewer" style="height:600px"></div>
<script>
  let viewer;
  async function loadTgvdata(resultUrl, accessToken) {
    const asset = await fetch(resultUrl, {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    if (!asset.ok) throw new Error(`三维结果获取失败：${asset.status}`);

    // 解析完成后再按需加载 Viewer，避免页面启动阶段加载大型 UMD 包。
    await new Promise((resolve, reject) => {
      if (typeof window.TuoVisualViewer?.TuoVisualViewer === 'function') return resolve();
      const script = document.createElement('script');
      script.src = 'https://resource.api.tiangongtuxue.com/tuo-visual-viewer/1.0.0/tuo-visual-viewer.umd.js';
      script.onload = () => typeof window.TuoVisualViewer?.TuoVisualViewer === 'function'
        ? resolve()
        : reject(new Error('Viewer 构造函数未找到'));
      script.onerror = () => reject(new Error('Viewer 脚本加载失败'));
      document.head.appendChild(script);
    });

    viewer?.destroy();
    viewer = new window.TuoVisualViewer.TuoVisualViewer(document.querySelector('#viewer'));
    await viewer.load(await asset.blob(), { format: 'tgvdata' });
  }
</script>

线上 Demo 已采用相同的按需加载方式：打开 Project Key 上传与 Viewer Demo。

一、控制台准备​

接入流程图​

二、换取访问令牌​

三、创建模型并取得上传授权​

四、上传文件​

使用 curl 上传​

浏览器 JavaScript 上传​

上传后的状态​

五、查询状态和浏览结果​

六、使用 Viewer​