# 腾讯混元与 Tripo 3D

> 使用腾讯原生协议提交和查询 3D 生成任务，取得限时下载链接。

Base URL：`https://platform.sgt.site/tencent`

本文中的接口路径均相对于此 Base URL；完整请求地址由二者拼接。

<a id="native-tencent-3d-h-0b4ec5e7"></a>

## 模型与鉴权

| 模型 ID | 能力 |
| --- | --- |
| `hy-3d-3.0` | 文生、图生、多视图、白模、草图及低面数 |
| `hy-3d-3.1` | 文生、图生、多视图、白模及草图 |
| `hy-3d-express` | 极速文生和图生 |
| `tripo-3d-3.1` | 文生、图生、多视图，可配置网格、部件和纹理 |
| `tripo-3d-p1` | 文生、图生、多视图，低面数资产 |

上述是已适配的型号；实际可调用范围以当前虚拟密钥的 `GET https://platform.sgt.site/v1/models` 和模型列表为准。价格、渠道及模型授权必须有效。Tripo 尚无默认平台售价，管理员明确配置后才可调用。

提交和查询都使用 `Authorization: Bearer <虚拟密钥>`。请求地址换成 mote 的 API 地址，无需向调用方提供腾讯渠道密钥。本页使用专用的 3D 提交与查询接口。格式转换、独立纹理、绑骨和动画后处理不在本期范围。

<a id="native-tencent-3d-h-36d5f450"></a>

## 提交任务

`POST /v1/api/3d/submit`，JSON 请求。一次提交对应一次生成；不要把重复提交作为轮询方式。

```bash
BASE_URL="https://platform.sgt.site/tencent"
KEY="YOUR_VIRTUAL_KEY"
curl "$BASE_URL/v1/api/3d/submit" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"hy-3d-3.1","prompt":"一只陶瓷小猫","enable_pbr":false}'
```

```json
{"id":"task_example","object":"3d_job","created_at":1791763200,"status":"queued"}
```

返回的是平台任务 ID，后续查询必须使用这个 ID 和提交时的模型名。平台会保存上游任务关联与提交时的价格快照。提交结果待确认时保留任务 ID 等待核对，不应重新生成；调整价格不重算已经提交的任务。

<a id="native-tencent-3d-h-1d90ee3b"></a>

### 混元参数

| 参数 | 规则 |
| --- | --- |
| `model` | 三个混元型号之一，必填 |
| `prompt` | 最多 1024 字符；普通模式与图片输入二选一 |
| `image_url` / `image_base64` | 图片 URL 或纯 Base64，二选一；Base64 解码后不超过 6 MiB |
| `enable_pbr` | PBR 材质，默认 false；专业版 Geometry 模式不计此项 |
| `generate_type` | 专业版：`Normal`、`Geometry`、`Sketch`；仅 3.0 额外支持 `LowPoly`。Sketch 同时需要提示词和图片 |
| `face_count` | 专业版 3000–1500000；LowPoly 不按此项加价 |
| `polygon_type` | 专业版低面数模式的 `triangle` 或 `quadrilateral` |
| `multi_view_images` | 专业版最多 7 个附加视图：`view_type`、`view_image_url`；需主图 |
| `result_format` | 专业版可额外指定 `stl`、`usdz`、`fbx`；省略时使用服务默认结果。极速版支持 `obj`、`glb`、`stl`、`usdz`、`fbx`、`mp4` |
| `enable_geometry` | 仅极速版；开启时不支持 OBJ |

视图可用 `left`、`right`、`back`、`top`、`bottom`、`left_front`、`right_front`，同一种视角不能重复。具体图片规格见下表。

<a id="native-tencent-3d-h-9ee49aa4"></a>

### 输入图片要求：先区分模型与来源

| 模型与输入字段 | 文件与格式 | 像素与其他要求 |
| --- | --- | --- |
| 混元 3.0 / 3.1 / Express 的 `image_url` 主图 | 腾讯要求不超过 8 MB；JPG、JPEG、PNG、WEBP | 宽和高各自为 128–5000 px，包含边界 |
| 同上 `image_base64` | 纯 Base64，不带 `data:image/...;base64,` 前缀；平台按解码后不超过 6 MiB 校验；格式同主图 | 宽和高各自为 128–5000 px；不能同时填写 `image_url` |
| 混元 3.0 / 3.1 的 `multi_view_images[].view_image_url` | 腾讯要求单张小于 8 MB、所有附加视图合计小于 100 MB；仅 JPG、PNG | 宽、高均大于 128 且小于 5000 px；每种附加视角最多一张，另须主图 |
| Tripo 3.1 / P1 的 `input`、`inputs[]` | 公网 HTTP(S) 图片 URL，不带 URL 用户名/密码；不要填 Base64、`file_id` 或 `asset_id` | 同一物体、主体清楚、尽量少遮挡；腾讯当前 Tripo 指南未公布统一的文件大小、像素范围或格式枚举，不能套用混元的数值 |

远程图片应能被服务端直接读取。输入 URL 通过结构校验不代表图像内容已满足腾讯要求；应在提交前自行确认实际文件格式、大小与尺寸。以上是腾讯原生输入规则，平台统一接口的文件上传上限不能替代这些要求。

<a id="native-tencent-3d-h-2e22a33a"></a>

### Tripo 参数

```json
{
  "model": "tripo-3d-3.1",
  "input": "https://files.example.com/cat.png",
  "texture": true,
  "pbr": true,
  "texture_quality": "standard",
  "model_seed": 0
}
```

| 参数 | 规则 |
| --- | --- |
| `prompt` | 文生模式，最多 1024 字符 |
| `input` / `inputs` | 单图 URL 或多视图对象数组，二选一；多视图使用 `front`、`back`、`left`、`right` URL，各视角最多一次 |
| `negative_prompt` | 最多 255 字符 |
| `image_seed`、`model_seed`、`texture_seed` | 有符号 32 位整数；显式 0 原样保留 |
| `texture`、`pbr` | 默认 true；PBR 开启时纹理被强制开启。纯白模应同时设为 false |
| `texture_quality` | `standard`、`detailed`、`extreme` |
| `texture_alignment` | `original_image`、`geometry` |
| `orientation` | `default`、`align_image` |
| `face_limit` | 3.1 标准三角面上限 1500000，detailed 几何上限 2000000；quad 上限 150000；P1 范围 50–20000 |
| `quad`、`smart_low_poly` | 仅 3.1；smart_low_poly 三角面 500–20000，四边面 500–10000 |
| `generate_parts` | 仅 3.1，要求 texture、pbr、quad 均为 false |
| `geometry_quality` | 仅 3.1：`standard`、`detailed` |
| `compress` | 可选 `geometry` |
| `enable_image_autofix`、`auto_size`、`export_uv` | 可选布尔值；显式 false 原样保留 |

<a id="native-tencent-3d-h-e47b43e9"></a>

## 原生完整生成示例

以下请求均提交到本页的腾讯原生地址，参数放在请求顶层；不要混入统一协议的 `references` 或 `provider_options`。把 `KEY` 和 JSON 中 `example.com` 的每个素材 URL 替换为自己的虚拟密钥与公网素材 URL；这些素材域名仅为占位。每次 POST 都会新建任务，超时或结果未知时先按平台任务 ID 查询，不重新 POST。

每个示例创建成功都返回 `{"id":"task_example","object":"3d_job","status":"queued","created_at":1791763200}`。保存实际 `id`，按“查询与下载”章节使用**相同模型名**查询。下列完成 JSON 是返回格式示例，ID、时间和签名为占位，展示的是可能返回的文件组合。

<a id="native-tencent-3d-h-41b20ff0"></a>

### 草图加文字（混元 3.1 Sketch）

Sketch 必须同时有 `prompt` 和一张主图；`image_url` 与 `image_base64` 仍二选一。3.0 也支持 Sketch，Express 不支持。

```bash
BASE_URL="https://platform.sgt.site/tencent"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v1/api/3d/submit" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "hy-3d-3.1",
  "generate_type": "Sketch",
  "prompt": "依照线稿生成一把四条腿、有靠背的木椅，保留轮廓",
  "image_url": "https://example.com/inputs/chair-sketch.png",
  "enable_pbr": false
}'
```
查询完成示例：

```json
{
  "id": "task_hy_sketch",
  "request_id": "req_example",
  "object": "3d_job",
  "created_at": 1791763200,
  "completed_at": 1791763380,
  "status": "completed",
  "data": [
    {
      "type": "glb",
      "url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_hy_sketch/artifacts/0?expires=1791849780&sig=EXAMPLE_SIGNATURE",
      "preview_image_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_hy_sketch/artifacts/1?expires=1791849780&sig=EXAMPLE_SIGNATURE"
    }
  ]
}
```

从 `data[].url` 下载模型，`data[].type` 表示该项格式，`preview_image_url` 是预览图；默认格式还可能有 OBJ 等其他项，应遍历整个数组。

<a id="native-tencent-3d-h-f8d9e949"></a>

### 智能低面数（混元 3.0 LowPoly）

此例使用单图，不再填写 `prompt`。`face_count` 在 LowPoly 下无效；`polygon_type` 只在此模式生效。`result_format` 影响需要返回的模型格式，与纹理/PBR 是不同选项。

```bash
BASE_URL="https://platform.sgt.site/tencent"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v1/api/3d/submit" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "hy-3d-3.0",
  "image_url": "https://example.com/inputs/chair.png",
  "generate_type": "LowPoly",
  "polygon_type": "quadrilateral",
  "enable_pbr": false,
  "result_format": "fbx"
}'
```
查询完成示例：

```json
{
  "id": "task_hy_lowpoly",
  "request_id": "req_example",
  "object": "3d_job",
  "created_at": 1791763200,
  "completed_at": 1791763380,
  "status": "completed",
  "data": [
    {
      "type": "fbx",
      "url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_hy_lowpoly/artifacts/0?expires=1791849780&sig=EXAMPLE_SIGNATURE",
      "preview_image_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_hy_lowpoly/artifacts/1?expires=1791849780&sig=EXAMPLE_SIGNATURE"
    }
  ]
}
```

<a id="native-tencent-3d-h-ec132aba"></a>

### 主图加附加视角（混元 3.1 多视图）

`image_url` 是正面主图；`multi_view_images` 只放附加视角，字段是 `view_type` + `view_image_url`，不是 Tripo 的 `inputs`。普通多视图不要再写 `prompt`。3.0 使用相同结构。

```bash
BASE_URL="https://platform.sgt.site/tencent"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v1/api/3d/submit" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "hy-3d-3.1",
  "image_url": "https://example.com/inputs/front.png",
  "multi_view_images": [
    {
      "view_type": "left",
      "view_image_url": "https://example.com/inputs/left.png"
    },
    {
      "view_type": "right",
      "view_image_url": "https://example.com/inputs/right.png"
    },
    {
      "view_type": "back",
      "view_image_url": "https://example.com/inputs/back.png"
    }
  ],
  "generate_type": "Normal",
  "enable_pbr": true,
  "face_count": 300000
}'
```
查询完成示例：

```json
{
  "id": "task_hy_views",
  "request_id": "req_example",
  "object": "3d_job",
  "created_at": 1791763200,
  "completed_at": 1791763380,
  "status": "completed",
  "data": [
    {
      "type": "glb",
      "url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_hy_views/artifacts/0?expires=1791849780&sig=EXAMPLE_SIGNATURE",
      "preview_image_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_hy_views/artifacts/1?expires=1791849780&sig=EXAMPLE_SIGNATURE"
    }
  ]
}
```

<a id="native-tencent-3d-h-8d3cf66c"></a>

### 四视图（Tripo 3.1）

`inputs` 是对象数组，每个对象中的 `front/back/left/right` 是 URL 字符串。下面每个对象只放一个视角，四个视角不重复；不能同时设置单图 `input`。

```bash
BASE_URL="https://platform.sgt.site/tencent"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v1/api/3d/submit" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "tripo-3d-3.1",
  "inputs": [
    {
      "front": "https://example.com/inputs/front.png"
    },
    {
      "back": "https://example.com/inputs/back.png"
    },
    {
      "left": "https://example.com/inputs/left.png"
    },
    {
      "right": "https://example.com/inputs/right.png"
    }
  ],
  "texture": true,
  "pbr": true,
  "texture_quality": "detailed",
  "texture_alignment": "original_image",
  "geometry_quality": "standard",
  "face_limit": 100000,
  "orientation": "align_image"
}'
```
查询完成示例：

```json
{
  "id": "task_tripo_views",
  "request_id": "req_example",
  "object": "3d_job",
  "created_at": 1791763200,
  "completed_at": 1791763380,
  "status": "completed",
  "input": {
    "pbr": true,
    "texture": true,
    "geometry_quality": "standard",
    "export_uv": false
  },
  "output": {
    "type": "multiview_to_model",
    "model_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_tripo_views/artifacts/0?expires=1791849780&sig=EXAMPLE_SIGNATURE",
    "generated_image_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_tripo_views/artifacts/1?expires=1791849780&sig=EXAMPLE_SIGNATURE",
    "rendered_image_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_tripo_views/artifacts/2?expires=1791849780&sig=EXAMPLE_SIGNATURE"
  }
}
```

<a id="native-tencent-3d-h-102fe085"></a>

### 多视图部件生成（Tripo 3.1 generate_parts）

三个冲突开关必须显式设为 false，因为 `texture`、`pbr` 的默认值都是 true。`quad` 为 true 时会生成四边面并改变输出格式，因此不能和部件生成一起开启。

```bash
BASE_URL="https://platform.sgt.site/tencent"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v1/api/3d/submit" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "tripo-3d-3.1",
  "inputs": [
    {
      "front": "https://example.com/inputs/front.png"
    },
    {
      "back": "https://example.com/inputs/back.png"
    },
    {
      "left": "https://example.com/inputs/left.png"
    },
    {
      "right": "https://example.com/inputs/right.png"
    }
  ],
  "texture": false,
  "pbr": false,
  "quad": false,
  "generate_parts": true,
  "geometry_quality": "standard",
  "face_limit": 100000,
  "export_uv": false
}'
```
查询完成示例：

```json
{
  "id": "task_tripo_parts",
  "request_id": "req_example",
  "object": "3d_job",
  "created_at": 1791763200,
  "completed_at": 1791763380,
  "status": "completed",
  "input": {
    "pbr": false,
    "texture": false,
    "geometry_quality": "standard",
    "export_uv": false
  },
  "output": {
    "type": "multiview_to_model",
    "model_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_tripo_parts/artifacts/0?expires=1791849780&sig=EXAMPLE_SIGNATURE",
    "generated_image_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_tripo_parts/artifacts/1?expires=1791849780&sig=EXAMPLE_SIGNATURE",
    "rendered_image_url": "https://platform.sgt.site/tencent/v1/api/3d/tasks/task_tripo_parts/artifacts/2?expires=1791849780&sig=EXAMPLE_SIGNATURE"
  }
}
```

`output.type` 的 `multiview_to_model` 是任务类型，**不是文件扩展名**。部件结果仍从单个 `output.model_url` 读取；`generated_image_url` 和 `rendered_image_url` 有值时分别是生成参考图与渲染预览。平台不会新增 `parts[]`、保证每个部件一个文件，或替调用方选择 Tripo 输出格式。

<a id="native-tencent-3d-h-b9850be3"></a>

### 选项的效果与费用不要混为一项

- Geometry 只生成白模，专业版的 PBR 选项在此模式不生效；Express 用 `enable_geometry`，且不能选择 OBJ。LowPoly 生成智能拓扑，`face_count` 不生效。Sketch 的草图+文字则是输入方式差异。
- 混元的 PBR、多视图、自定义面数和额外格式可能影响有效价格；无效的 PBR/面数选项不会按有效附加项重复计入。具体价格仍以提交时的平台合同为准，示例不构成报价。
- Tripo 的 `face_limit` 约束网格规模；`geometry_quality` 调整几何细节，`texture_quality` 调整贴图质量。`texture_alignment` 的 `original_image` 偏向图像外观，`geometry` 偏向三维贴合；`orientation: align_image` 仅在有纹理时生效。
- `auto_size` 用于真实世界尺寸，`compress: geometry` 压缩几何，`export_uv` 控制 UV 展开。它们不等价于改变面数；Tripo 费用按管理员配置的固定价或腾讯实际积分模式处理，不能凭一个开关自行推算价格。

<a id="native-tencent-3d-h-83f1f18c"></a>

## 查询与下载

`POST /v1/api/3d/query`：查询平台保存并由后台轮询更新的任务状态，查询不再创建生成任务。

```bash
BASE_URL="https://platform.sgt.site/tencent"
KEY="YOUR_VIRTUAL_KEY"
curl "$BASE_URL/v1/api/3d/query" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"hy-3d-3.1","id":"task_example"}'
```

常规状态为 `queued`、`in_progress`、`completed`、`failed`。Tripo 上游的 `success` 统一为 `completed`。提交或轮询结果不确定时不能视为成功或失败，应保留任务 ID 待核对。失败响应有受控 `error` 和 `diagnostic`，不会返回渠道密钥或上游原始错误全文。

混元结果在 `data[]`，Tripo 结果在 `output`。五款型号的默认与模式差异见[3D 默认输出](media-3d.md)：原生字段 `result_format` 对应统一接口的 `output_format`。专业版普通默认 OBJ + GLB、Geometry 默认 GLB；Express 普通参数默认 OBJ（官方示例含多格式，数量以结果为准），白模默认 GLB，指定 MP4 可仅有视频。Tripo 普通示例为 GLB，3.1 的 `quad=true` 强制 FBX，P1 不支持 quad；不能把所有 Tripo 结果都当成 GLB。

| 字段 | 类型与出现条件 | 含义 |
| --- | --- | --- |
| `data` | array，混元成功结果 | 全部结果；空数组表示无可读结果，不是下载完成 |
| `data[].type` | string，每个混元文件必有 | 模型/视频格式标识，如 obj/glb/fbx/mp4；按大小写归一后识别，不按数组下标选格式 |
| `data[].url` | 非空 string，每个混元文件必有 | 签名下载地址；OBJ 可能实际包装为 ZIP，应先识别包装再命名 |
| `data[].preview_image_url` | string，可选 | 对应结果的预览图片，可重复；缺失不是空模型 |
| `output.model_url` | 非空 string，Tripo 成功结果 | 模型文件；签名路径不保留格式后缀，用文件证据判断 |
| `output.type` | string，可选 | 任务类型，如 text_to_model/multiview_to_model，**不是文件格式** |
| `output.generated_image_url` | string，可选 | 生成参考图，不是模型预览优先级 |
| `output.rendered_image_url` | string，可选 | 渲染预览图，与模型文件分别保存 |

MIME 为 `application/octet-stream` 时只表示二进制。GLB 文件头为 `glTF`；ZIP 先保留包装，解包后再查看 OBJ、材质和贴图。FBX、STL、USDZ 等不能因客户端只接受 GLB 就改后缀。

Tripo 回包可能包含上游实际积分 `credits_consumed`；平台保留该可选数值，缺失时不推算。查询始终返回平台任务 ID，上游 Tripo 内部 UUID 不用于后续查询。

成功查询把产物地址转换为平台签名链接，形如：

```text
https://platform.sgt.site/tencent/v1/api/3d/tasks/task_example/artifacts/0?expires=...&sig=...
```

链接可直接 GET 下载，不需要额外 Authorization，支持 HEAD 与 Range。默认 24 小时有效，每次成功查询重新签发；平台可配置有效期，最长 7 天。它只授权该任务的该文件。持有者在有效期内可以读取，撤销虚拟密钥或模型授权不能收回已发链接。上游文件过期或丢失后，重签地址不能恢复文件；已完成的归档独立保留原始字节。

当前虚拟密钥失效、模型授权撤销或渠道停用后，不再通过查询接口签发新链接。文件下载不触发新生成。任务详情提供预览图与下载列表，本期不提供交互式 3D 查看器。


保存提交得到的 `TASK_ID`，`MODEL` 必须与提交一致。先将[快速开始脚本](overview.md#overview-h-600de8a7)保存为 `media_client.py`，下面脚本另存为 `tencent_download.py`；使用同一目录，Python 3.8+ 和 requests。它只调用原生查询与文件读取，不发起新生成：

```bash
export MODEL="tripo-3d-3.1"
export TASK_ID="YOUR_PLATFORM_TASK_ID"
python tencent_download.py
```

**完整脚本 `tencent_download.py`**

```python
import os
import time
from pathlib import Path
import requests
from media_client import GATEWAY, HEADERS, DeliveryPending, save_file


def download_native(result, folder="output", saved=None):
    saved = {} if saved is None else saved
    if result.get("status") != "completed":
        raise DeliveryPending("原任务尚未完成")
    outputs = []
    for index, item in enumerate(result.get("data") or []):
        declared = str(item.get("type", "")).lower()
        # 类型只用白名单命名；OBJ 的 ZIP 包由 save_file 识别，不改成 .obj。
        label = declared if declared in {"obj", "glb", "fbx", "stl", "usdz", "mp4"} else "unknown"
        outputs.append((f"hy-{index}-{label}", item.get("url")))
        if "preview_image_url" in item:
            outputs.append((f"hy-{index}-cover", item["preview_image_url"]))
    if result.get("output"):
        item = result["output"]
        outputs.append(("tripo-model", item.get("model_url")))
        for field, kind in [("generated_image_url", "image"), ("rendered_image_url", "cover")]:
            if field in item:
                outputs.append((f"tripo-{kind}", item[field]))
    if not outputs:
        raise DeliveryPending("完成但产物为空；继续查询原任务")
    for name, url in outputs:
        if not url:
            raise DeliveryPending("产物地址为空；继续查询原任务")
        if name not in saved:
            saved[name] = save_file(url, Path(folder) / name)
    return list(saved.values())


if __name__ == "__main__":
    task_id, model = os.environ["TASK_ID"], os.environ["MODEL"]
    deadline, saved = time.monotonic() + 1800, {}
    while time.monotonic() < deadline:
        try:
            response = requests.post(f"{GATEWAY}/tencent/v1/api/3d/query",
                                     json={"model": model, "id": task_id}, headers=HEADERS, timeout=30)
            response.raise_for_status()
            result = response.json()
            if result.get("status") == "failed":
                raise RuntimeError("原任务失败；保留 ID 核对结果与账务，不自动重提")
            download_native(result, saved=saved)
            print("文件已保存；原生结果不提供统一 billing，账务仍须在平台记录中核对")
            break
        except (DeliveryPending, requests.RequestException) as error:
            print("尚未完整取得产物：", type(error).__name__, "；继续查询原任务", task_id)
            time.sleep(5)
    else:
        raise TimeoutError("交付未完成；保留原任务 ID 后续恢复，不重新生成")
```

混元按 `data[].type` 区分格式并遍历全部文件；同一格式有多个条目时也分别保存。可筛选 `type` 为 `glb` 的文件供 GLB 查看器使用，没有就明确报告，不回退到第一个文件。Tripo 使用 `model_url`，不能把 `output.type` 当格式。脚本保留类型标记在文件名中，但扩展名由文件头或明确 MIME 决定；未知格式为 `.bin`，要用相应工具核对后再导入。

单格式、OBJ ZIP + GLB + 封面、Express 仅视频、Tripo 模型与预览以及乱序结果都按上述规则处理。下载 HTTP 失败/中断或空地址会报告并查询原任务，不能默默漏文件。签名过期可重新查询，**上游文件过期不能靠重签恢复**。客户端无法预览时先检查模型格式、包装与压缩支持；保存原文件，不重新生成。

<a id="native-tencent-3d-h-90e766fa"></a>

## 价格与积分

平台按生成请求的规格计价，企业使用当前有效费率或锁定价格。已知的混元初始规则来自腾讯公开价格：专业版 Normal 20 积分、Geometry 15、LowPoly/Sketch 25；PBR、多视图、自定义面数各加 10，额外格式加 5。极速版基础 15，PBR 加 10。混元公开换算为 0.12 元/腾讯积分。受模式忽略的参数不重复收费。

Tripo 支持管理员显式选择“按腾讯积分”计价：配置每腾讯积分人民币单价及预留积分。以 0.07 元/积分、预留 60 积分为例，提交时预留 ¥4.20，完成回报 20 积分时结算 ¥1.40、释放 ¥2.80；回报 40 积分时结算 ¥2.80。预留不是腾讯费用上限，实际用量超出预留时仅在原资金批次及使用上限允许的情况下补扣，否则进入账务复核。单价、企业费率和预留依据在提交时冻结，之后改价不会改变在途任务。已有固定按次价及锁价仍保持原义。

该模式的查询回包 `credits_consumed` 是用量证据，不是腾讯折后现金账单。缺少、异常或成功任务回报零积分时保留资金/用量预留并进入核对，成功模型仍可查询和下载。任务详情显示腾讯回报积分、单价、预留额、最终人民币费用与平台积分。平台管理员可根据腾讯账单补录待结算任务的积分，必须填写依据和原因；操作有审计及幂等保护，不能借此修改已结算的历史账单。失败任务带不明确或非零积分时同样进入核对；在该补录入口只允许核实为零后释放预留，不自动追收失败费用。

管理接口 `POST https://platform.sgt.site/api/task/{task_id}/credit-evidence` 仅平台超级管理员可用，使用管理身份鉴权；JSON 为 `{"credits":40,"reason":"腾讯账单依据与核对原因","idempotency_key":"本次核对唯一标识"}`。同一标识和内容重复提交不会再次扣费；更改内容必须重新核对，已完成结算的任务拒绝变更。生成状态和账务状态分别表达，日/月上限或余额复核沿用现有企业结算复核流程。

平台积分为费用展示单位（100 平台积分 = 1 元），与腾讯积分是不同口径。查询中的 `credits_consumed` 表示上游回报用量；显式按腾讯积分计价的任务使用该用量和提交时冻结的单价/费率结算，已有固定按次价和已结算账单不会据此重算。缺失或异常用量不能理解为零；失败任务在零消耗得到确认后才释放预留。人工补录先展示任务、核实积分、冻结单价和预计费用，二次确认后提交；补录与后续结算之间的进程退出不会释放用量预留，重复查询或重复处理不会再次收费。

<a id="native-tencent-3d-h-5b533294"></a>

## 错误与限制

| 情况 | 处理 |
| --- | --- |
| 参数不支持、组合冲突、数值越界 | 400；上游提交前拒绝 |
| 未配置价格或主体预算不可用 | 按平台价格/预算错误返回；不调用腾讯 |
| 任务不属于当前用户、模型与任务不匹配 | 404 |
| 当前模型授权或渠道不可用 | 403 |
| 成功状态但产物缺失 | 502，保留任务等待处理 |
| 下载签名被改动或过期 | 403 |

官方协议依据：[混元专业版](https://cloud.tencent.com/document/product/1823/137181)、[极速版](https://cloud.tencent.com/document/product/1823/137175)、[Tripo](https://cloud.tencent.com/document/product/1823/137074)、[腾讯价格页](https://cloud.tencent.com/document/product/1823/130055)。本页为实现说明，未声明真实 Provider 验收或生产上线。