# 3D 生成
> 用混元 3D 或 Tripo 生成 3D 模型：文生、单图、多视图和草图的输入方式，各模型的选项取值，以及提交、查询、下载模型文件的完整流程和响应。
## 接口
| 项目 | 内容 |
| --- | --- |
| 方法与地址 | `POST https://platform.sgt.site/media/v1/3d/generations` |
| 请求头 | `Authorization: Bearer <虚拟密钥>`、`Content-Type: application/json`；建议加 `Idempotency-Key` |
| 返回 | 任务对象 `media.task`，`type` 为 `3d`，通常是 HTTP 202、`status: "queued"` |
| 查询结果 | `GET https://platform.sgt.site/media/v1/tasks/{id}`，建议每 5–10 秒一次，直到 `succeeded` 或 `failed` |
| 结果位置 | `artifacts[]`：模型文件 `kind: "model3d"`，预览图 `cover`；Tripo 另有 `image`，Express 选 `mp4` 时有 `video` |
| 下载 | 产物一律是平台签名链接，直接 GET，不带 `Authorization` |
| 取消 | 当前五款模型都不支持 |
3D 生成可能需要数分钟。提交时用 `"wait": 0` 立即拿到任务 ID，再轮询；完整的轮询脚本见[快速开始](overview.md)。只接受下文的完整模型 ID，不接受 `hunyuan`、`tripo` 等简称；一次请求生成一个模型，不接受 `n`。
## 输入方式
| 输入方式 | 怎么填 | 混元 3.0 / 3.1 | 混元 Express | Tripo 3.1 / P1 |
| --- | --- | --- | --- | --- |
| 文生 3D | 只写 `prompt` | 支持 | 支持 | 支持 |
| 单图生 3D | 1 项 `reference` / `image` | 支持，此时不能再写 `prompt` | 支持，此时不能再写 `prompt` | 支持；`prompt` 仅文生模式生效，图片模式请省略 |
| 多视图 | 主图 + 其他视角，见下表 | 支持，主图 + 最多 7 个视角 | 不支持 | 支持，前、后、左、右最多 4 张 |
| 草图 | `generate_type: "Sketch"`，同时写 `prompt` 和主图 | 支持 | 不支持 | 不支持 |
多视图的 `role` 写法：
| 模型 | 主图 | 其他视角 |
| --- | --- | --- |
| 混元 3.0 / 3.1 | `reference` 或 `multi_view_front`（二选一，只能一张） | `multi_view_left`、`multi_view_right`、`multi_view_back`、`multi_view_top`、`multi_view_bottom`、`multi_view_left_front`、`multi_view_right_front` |
| Tripo 3.1 / P1 | 不需要单独主图 | `multi_view_front`、`multi_view_back`、`multi_view_left`、`multi_view_right`；不能和单图 `reference` 同时使用 |
图片规则：
| 项目 | 规则 |
| --- | --- |
| 来源 | 每项只能填 `url`（公网 HTTP(S) 地址）或 `file_id`（[上传文件](media-files.md)得到的 `id`）；不支持 `asset_id` |
| 类型 | `type` 固定为 `image`；平台参考文件上限为 10 MiB，直接 URL 和模型输入还需满足下方的厂商限制 |
| 数量 | 每个 `role` 最多一张，不能重复 |
**文件限制分两层检查。** 10 MiB 是平台参考文件的能力上限，不是所有 3D 模型都能接受 10 MiB 图片：混元主图的公网 URL 文件还需不超过 8 MB，格式为 JPG/JPEG/PNG/WEBP，宽、高各自 128–5000 px；附加视图只支持 JPG/PNG，单张小于 8 MB、合计小于 100 MB，宽、高均大于 128 且小于 5000 px。`file_id` 解析后也要满足目标模型的输入要求。Tripo 指南要求同一物体、主体清楚、遮挡少，未给出可套用到直接 URL 的统一像素或大小数值；不要把混元阈值当成 Tripo 官方限制。
## 通用参数
| 字段 | 类型 | 适用模型 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 全部 | 必填：`hy-3d-3.0`、`hy-3d-3.1`、`hy-3d-express`、`tripo-3d-3.1`、`tripo-3d-p1` |
| `prompt` | string | 全部 | 物体描述，最多 1024 字符。与图片能否同时使用见上表 |
| `references` | array | 全部 | 参考图片，见上文 |
| `output_format` | string | 仅混元 | 模型文件格式，取值见混元参数表 |
| `negative_prompt` | string | 仅 Tripo | 不希望出现的内容，最多 255 字符 |
| `seed` | integer | 仅 Tripo | 模型随机种子，-2147483648 至 2147483647 |
| `provider_options` | object | 全部 | 厂商选项，命名空间固定为 `tencent`，例如 `{"tencent": {"enable_pbr": true}}` |
| `metadata` | object | 全部 | 你的业务信息，随任务原样返回；不超过 64 KiB |
| `wait` | integer | 全部 | 本次请求最多等待的秒数，0–50，默认 0。3D 建议填 0 |
| `callback_url` | string | 全部 | 可选的 HTTPS 任务通知地址，由平台接管，不进入上游请求体；回调不能替代任务查询，见[任务回调](task-callbacks.md) |
某模型不接受的字段，传入会返回 400 `unsupported_parameter`。不用的字段直接省略，不要传 `null`。
图片、视频和上述五款 3D 模型的统一提交都受理符合规则的 `callback_url`。真实 Provider 与真实回调链路尚未验证；请保存任务 ID，并持续通过任务查询确认结果与账务状态，不能因未收到通知而重新生成。
## 混元 3D 参数怎么填
| 字段 | 位置 | `hy-3d-3.0` | `hy-3d-3.1` | `hy-3d-express` |
| --- | --- | --- | --- | --- |
| `output_format` | 顶层 | 可选 `stl`、`usdz`、`fbx`；省略时返回默认格式 | 同 3.0 | `obj`、`glb`、`stl`、`usdz`、`fbx`、`mp4` |
| `generate_type` | `provider_options.tencent` | `Normal`（默认）、`Geometry`、`Sketch`、`LowPoly` | `Normal`（默认）、`Geometry`、`Sketch` | 不接受 |
| `face_count` | `provider_options.tencent` | 3000–1500000 | 3000–1500000 | 不接受 |
| `polygon_type` | `provider_options.tencent` | `triangle` 或 `quadrilateral` | 同 3.0 | 不接受 |
| `enable_pbr` | `provider_options.tencent` | 布尔值，默认 `false` | 同 3.0 | 布尔值，默认 `false` |
| `enable_geometry` | `provider_options.tencent` | 不接受 | 不接受 | 布尔值，默认 `false`；`true` 时只生成白模，不能选 `obj` |
各选项的含义：
| 选项 | 含义 |
| --- | --- |
| `generate_type: "Normal"` | 带纹理的完整模型 |
| `generate_type: "Geometry"` | 只生成几何（白模），不带纹理 |
| `generate_type: "Sketch"` | 用草图加文字生成，必须同时提供 `prompt` 和主图 |
| `generate_type: "LowPoly"` | 低面数模型，仅 3.0 |
| `face_count` | 目标面数，越大细节越多 |
| `polygon_type` | 网格类型：三角面或四边面 |
| `enable_pbr` | 生成 PBR 材质贴图 |
| `output_format` | 选择输出格式，不保证追加文件；默认与模式差异见下表，遍历完整的 `artifacts` |
### 默认输出与格式选择
`output_format` 是可选字符串，统一接口映射为腾讯原生 `result_format`；省略表示使用该型号和模式的默认行为，空字符串和 `null` 不表示默认。以下按当前接入的五款型号分别说明：
**五款型号的默认输出、模式影响与显式格式**
| 型号 | 未指定格式时 | 模式和选项的影响 | 显式格式 |
| --- | --- | --- | --- |
| `hy-3d-3.0` | Normal 默认 OBJ 与 GLB；OBJ 可包装为 ZIP，附带材质/贴图 | Geometry 默认 GLB 且无纹理，PBR 不生效；Sketch 使用图文；LowPoly 改变拓扑，`face_count` 不生效 | `stl/usdz/fbx` 选择一种模型输出格式，不承诺在默认文件之外追加；预览图另计 |
| `hy-3d-3.1` | Normal 默认 OBJ 与 GLB | Geometry 默认 GLB；支持 Sketch，不支持 LowPoly；纹理、PBR 影响内容 | 同 3.0；以结果列表为准 |
| `hy-3d-express` | 腾讯参数表规定普通模式默认 OBJ；其示例又含 OBJ + GLB，不能据示例保证文件数量 | `enable_geometry=true` 默认 GLB，不支持 OBJ；`enable_pbr` 控制材质 | `obj/glb/stl/usdz/fbx/mp4`；MP4 可只有展示视频，没有可编辑模型 |
| `tripo-3d-3.1` | 普通示例为 GLB，但未承诺所有模式都固定 GLB | `quad=true` 强制 FBX；`generate_parts=true` 需关闭 texture/pbr/quad；`compress=geometry` 使用 meshopt，查看器需支持对应压缩 | 不支持 `output_format`；按返回文件识别，不按模型名猜 |
| `tripo-3d-p1` | 共用指南未单独规定 P1 默认格式；普通示例是 GLB，不能据此保证 P1 的所有结果 | 支持纹理、PBR、几何压缩等；不支持 quad、smart_low_poly、generate_parts、geometry_quality | 不支持 `output_format`；保留并识别实际文件 |
依据：[腾讯专业版](https://cloud.tencent.com/document/product/1823/137181)、[Express](https://cloud.tencent.com/document/product/1823/137175)、[Tripo](https://cloud.tencent.com/document/product/1823/137074)，核对于 2026-10-15。默认规则帮助选择请求，实际交付始终以本次结果为准。
模型格式（OBJ/GLB/FBX）和文件包装（如 ZIP）不同：ZIP 应按 ZIP 保存并解包查看其中模型与贴图，不能改名为 `.obj` 或 `.glb`。`kind=model3d` 只表示用途，`application/octet-stream` 只表示通用二进制。模型产物通过 `format` 标明可识别的模型格式，已知 ZIP 包装通过 `container=zip` 表达，`filename` 给出建议保存名；未知信息省略，不从请求的 `output_format` 推断。字段来源与完整性检查见[任务产物字段](media-tasks.md)。
## Tripo 参数怎么填
以下字段都放在 `provider_options.tencent`。Tripo 不接受顶层 `output_format`，模型文件格式不可选。
| 字段 | `tripo-3d-3.1` | `tripo-3d-p1` | 含义 |
| --- | --- | --- | --- |
| `texture` | 布尔值，默认 `true` | 同左 | 生成纹理 |
| `pbr` | 布尔值，默认 `true` | 同左 | 生成 PBR 材质；开启时纹理也会生成 |
| `texture_quality` | `standard`（默认）、`detailed`、`extreme` | 同左 | 纹理质量 |
| `texture_alignment` | `original_image`、`geometry` | 同左 | 纹理对齐方式 |
| `face_limit` | 1–1500000；见下方说明 | 50–20000 | 面数上限 |
| `geometry_quality` | `standard`（默认）、`detailed` | 不接受 | 几何质量 |
| `quad` | 布尔值 | 不接受 | 输出四边面 |
| `smart_low_poly` | 布尔值 | 不接受 | 智能低面数 |
| `generate_parts` | 布尔值 | 不接受 | 按部件拆分 |
| `orientation` | `default`、`align_image` | 同左 | 朝向是否对齐输入图 |
| `compress` | `geometry` | 同左 | 压缩几何 |
| `image_seed`、`texture_seed` | 32 位整数 | 同左 | 图片和纹理的随机种子；模型种子用顶层 `seed` |
| `enable_image_autofix`、`auto_size`、`export_uv` | 布尔值 | 同左 | 自动修正输入图、自动尺寸、导出 UV |
`tripo-3d-3.1` 的 `face_limit` 范围随其他选项变化，默认 1–1500000，`geometry_quality`、`quad`、`smart_low_poly` 会改变上下限：
**`tripo-3d-3.1` 各选项组合下的 `face_limit` 范围**
| 选项组合 | `face_limit` 范围 |
| --- | --- |
| 默认 | 1–1500000 |
| `geometry_quality: "detailed"` | 1–2000000 |
| `quad: true` | 1–150000 |
| `smart_low_poly: true` | 500–20000 |
| `smart_low_poly: true` 且 `quad: true` | 500–10000 |
`generate_parts: true` 时，`texture`、`pbr`、`quad` 必须都为 `false`。P1 不接受 3.1 独有的选项，显式传 `false` 也会被拒绝。
## 完整请求示例
以下示例可直接复制，先按[快速开始](overview.md)设置 `GATEWAY_ORIGIN` 和 `KEY`。每个新的生成请求请换一个新的 `Idempotency-Key`；图片地址替换为可公开访问的地址，或改用 `file_id`。
按使用场景选择示例。表中只列出支持该用法的型号；当前密钥能否使用，以[模型列表](models.md#models-media-3d)的查询结果为准：
| 我要做什么 | 支持的型号 | 示例 |
| --- | --- | --- |
| 只用文字描述生成 | 五款均支持 | [文生 3D（混元 Express）](#media-3d-h-847a137b) |
| 用一张图片生成 | 五款均支持 | [单图生 3D（Tripo 3.1）](#media-3d-h-11a4fb09) |
| 用多个视角的图片生成 | `hy-3d-3.0`、`hy-3d-3.1`（主图加最多 7 个视角）；`tripo-3d-3.1`、`tripo-3d-p1`（前、后、左、右） | [混元 3.0](#media-3d-h-5f425c87)、[Tripo P1](#media-3d-h-cdd17f5d)、[Tripo 3.1](#media-3d-h-b1d7a5c5) |
| 用草图加文字生成 | `hy-3d-3.0`、`hy-3d-3.1`（`generate_type: "Sketch"`） | [草图生 3D（混元 3.1）](#media-3d-h-2b7b5b32) |
| 只要白模，不要纹理 | `hy-3d-express`（`enable_geometry`）；`hy-3d-3.0`、`hy-3d-3.1`（`generate_type: "Geometry"`） | [只要白模（混元 Express）](#media-3d-h-8bc84f3d) |
| 低面数模型 | `hy-3d-3.0`（`LowPoly`）；`tripo-3d-3.1`（`smart_low_poly`） | [低面数模型（混元 3.0 LowPoly）](#media-3d-h-1cd3bdcd) |
| 按部件拆分、方便编辑 | 仅 `tripo-3d-3.1`（`generate_parts`） | [多视图生成可编辑部件（Tripo 3.1）](#media-3d-h-7916fbc7) |
| 指定模型文件格式 | 仅混元三款（`output_format`）；Tripo 不可选 | [默认输出与格式选择](#media-3d-h-978e5ef6) |
### 文生 3D（混元 Express）
```bash
curl -s "$GATEWAY_ORIGIN/media/v1/3d/generations" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3d-demo-001" \
-d '{
"model": "hy-3d-express",
"prompt": "一只坐着的橘色卡通猫，圆润造型",
"output_format": "glb",
"provider_options": {"tencent": {"enable_pbr": true}},
"metadata": {"order_id": "M1001"},
"wait": 0
}'
```
### 单图生 3D（Tripo 3.1）
```json
{
"model": "tripo-3d-3.1",
"references": [
{"role": "reference", "type": "image", "url": "https://files.example.com/cat.png"}
],
"provider_options": {
"tencent": {"texture_quality": "detailed", "face_limit": 100000}
},
"wait": 0
}
```
### 多视图（混元 3.0）
混元的多视图不能再写 `prompt`：
```json
{
"model": "hy-3d-3.0",
"references": [
{"role": "multi_view_front", "type": "image", "url": "https://files.example.com/front.png"},
{"role": "multi_view_left", "type": "image", "url": "https://files.example.com/left.png"},
{"role": "multi_view_back", "type": "image", "url": "https://files.example.com/back.png"}
],
"output_format": "fbx",
"provider_options": {
"tencent": {"enable_pbr": true, "face_count": 300000, "polygon_type": "triangle"}
},
"wait": 0
}
```
### 多视图（Tripo P1）
```json
{
"model": "tripo-3d-p1",
"references": [
{"role": "multi_view_front", "type": "image", "file_id": "替换为正面图的文件 id"},
{"role": "multi_view_back", "type": "image", "file_id": "替换为背面图的文件 id"},
{"role": "multi_view_left", "type": "image", "file_id": "替换为左侧图的文件 id"},
{"role": "multi_view_right", "type": "image", "file_id": "替换为右侧图的文件 id"}
],
"provider_options": {"tencent": {"face_limit": 20000}},
"wait": 0
}
```
### 草图生 3D（混元 3.1）
```json
{
"model": "hy-3d-3.1",
"prompt": "木质椅子，四条腿，带靠背",
"references": [
{"role": "reference", "type": "image", "url": "https://files.example.com/chair-sketch.png"}
],
"provider_options": {"tencent": {"generate_type": "Sketch"}},
"wait": 0
}
```
### 只要白模（混元 Express）
```json
{
"model": "hy-3d-express",
"prompt": "一只坐着的猫",
"output_format": "stl",
"provider_options": {"tencent": {"enable_geometry": true, "enable_pbr": false}},
"wait": 0
}
```
### 低面数模型（混元 3.0 LowPoly）
选择 `hy-3d-3.0`；3.1 和 Express 不支持此模式。`polygon_type: "quadrilateral"` 表示四边面与三角面混合，并非保证全部为四边面。LowPoly 下 `face_count` 不生效，所以此示例省略它。
```bash
BASE_URL="https://platform.sgt.site"
KEY="YOUR_VIRTUAL_KEY"
curl -sS --request POST "$BASE_URL/media/v1/3d/generations" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: hy-lowpoly-001" \
-d '{
"model": "hy-3d-3.0",
"prompt": "一把用于游戏场景的简洁木椅，结构清晰，低面数风格",
"output_format": "fbx",
"provider_options": {
"tencent": {
"generate_type": "LowPoly",
"polygon_type": "quadrilateral",
"enable_pbr": false
}
},
"wait": 0
}'
```
提交返回平台 `media.task`；保存 `id`，按本页下方的查询流程读取 `artifacts` 中的 `model3d`。`output_format` 选择模型格式，不保证追加文件；不应凭数组位置假定文件数量。
### 多视图（Tripo 3.1）
四个 URL 分别替换为同一物体的正、后、左、右图。此处每个视角是一条 `references`；不要再同时提供单图 `reference`。Tripo 的图片输入不靠 `prompt` 改写物体，此例不填写提示词。
**完整请求：Tripo 3.1 四视图**
```bash
BASE_URL="https://platform.sgt.site"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/media/v1/3d/generations" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: tripo31-multiview-001" \
-d '{
"model": "tripo-3d-3.1",
"references": [
{
"role": "multi_view_front",
"type": "image",
"url": "https://example.com/inputs/front.png"
},
{
"role": "multi_view_back",
"type": "image",
"url": "https://example.com/inputs/back.png"
},
{
"role": "multi_view_left",
"type": "image",
"url": "https://example.com/inputs/left.png"
},
{
"role": "multi_view_right",
"type": "image",
"url": "https://example.com/inputs/right.png"
}
],
"provider_options": {
"tencent": {
"texture": true,
"pbr": true,
"face_limit": 100000,
"geometry_quality": "standard",
"texture_quality": "detailed",
"texture_alignment": "original_image",
"orientation": "align_image"
}
},
"wait": 0
}'
```
### 多视图生成可编辑部件（Tripo 3.1）
这是独立的新生成请求。`generate_parts` 必须同时关闭 `texture`、`pbr`、`quad`；只关闭其中一项不够。P1 不支持该功能。部件属于返回模型文件的内容，接口不会额外生成一个 `parts[]` 下载列表。
**完整请求：Tripo 3.1 可编辑部件**
```bash
BASE_URL="https://platform.sgt.site"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/media/v1/3d/generations" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: tripo31-parts-001" \
-d '{
"model": "tripo-3d-3.1",
"references": [
{
"role": "multi_view_front",
"type": "image",
"url": "https://example.com/inputs/front.png"
},
{
"role": "multi_view_back",
"type": "image",
"url": "https://example.com/inputs/back.png"
},
{
"role": "multi_view_left",
"type": "image",
"url": "https://example.com/inputs/left.png"
},
{
"role": "multi_view_right",
"type": "image",
"url": "https://example.com/inputs/right.png"
}
],
"provider_options": {
"tencent": {
"texture": false,
"pbr": false,
"quad": false,
"generate_parts": true,
"geometry_quality": "standard",
"face_limit": 100000,
"export_uv": false
}
},
"wait": 0
}'
```
任务成功的结构示例如下。这里上游只返回模型和渲染预览图；若同时返回生成参考图，还会有 `kind: "image"` 项。ID、时间、签名和金额均为示意，金额不是当前报价，实际费用以本次任务的 `billing` 为准：
**成功响应示例（部件模型）**
```json
{
"id": "task_tripo_parts",
"object": "media.task",
"model": "tripo-3d-3.1",
"type": "3d",
"status": "succeeded",
"progress": 100,
"created_at": 1791763200,
"started_at": null,
"finished_at": 1791763380,
"artifacts": [
{
"index": 0,
"kind": "model3d",
"mime_type": "application/octet-stream",
"state": "available",
"url": "https://platform.sgt.site/media/v1/tasks/task_tripo_parts/artifacts/0?expires=1791849780&sig=EXAMPLE_SIGNATURE",
"url_type": "signed",
"expires_at": 1791849780
},
{
"index": 1,
"kind": "cover",
"mime_type": "image/png",
"state": "available",
"url": "https://platform.sgt.site/media/v1/tasks/task_tripo_parts/artifacts/1?expires=1791849780&sig=EXAMPLE_SIGNATURE",
"url_type": "signed",
"expires_at": 1791849780
}
],
"error": null,
"billing": {
"status": "settled",
"currency": "CNY",
"amount": "1.400000"
},
"metadata": {},
"request_id": "req_example"
}
```
多视图普通模型与部件模型都按相同方式读取 `artifacts`；下载 `model3d` 文件后，在支持该文件格式的 3D 软件中查看网格/部件。不要假设一个部件对应一个 HTTP 下载地址。查询、费用与下载流程见下文。
## 响应
### 提交成功（HTTP 202）
```json
{
"id": "task_example",
"object": "media.task",
"model": "hy-3d-express",
"type": "3d",
"status": "queued",
"progress": 0,
"created_at": 1791763200,
"started_at": null,
"finished_at": null,
"artifacts": [],
"error": null,
"billing": {"status": "reserved", "currency": "CNY", "amount": null},
"metadata": {"order_id": "M1001"},
"request_id": "req_example"
}
```
保存 `id`，用 `GET /media/v1/tasks/{id}` 查询。生成过程中 `status` 为 `running`；以 `status` 判断是否完成，不要只看 `progress`。
### 生成成功
下例为混元任务的完成结果，包含模型文件和预览图。ID、签名与金额均为示意：
**完整成功响应（混元，模型文件与预览图）**
```json
{
"id": "task_example",
"object": "media.task",
"model": "hy-3d-express",
"type": "3d",
"status": "succeeded",
"progress": 100,
"created_at": 1791763200,
"started_at": null,
"finished_at": 1791763380,
"artifacts": [
{
"index": 0,
"kind": "model3d",
"mime_type": "application/octet-stream",
"format": "glb",
"filename": "model-0.glb",
"state": "available",
"url": "https://platform.sgt.site/media/v1/tasks/task_example/artifacts/0?expires=1791849780&sig=example-signature",
"url_type": "signed",
"expires_at": 1791849780
},
{
"index": 1,
"kind": "cover",
"mime_type": "image/png",
"state": "available",
"url": "https://platform.sgt.site/media/v1/tasks/task_example/artifacts/1?expires=1791849780&sig=example-signature",
"url_type": "signed",
"expires_at": 1791849780
}
],
"error": null,
"billing": {"status": "settled", "currency": "CNY", "amount": "2.400000"},
"metadata": {"order_id": "M1001"},
"request_id": "req_example"
}
```
| 产物 `kind` | 内容 | 出现情况 |
| --- | --- | --- |
| `model3d` | 模型文件，可能是模型与贴图的 ZIP 包 | 仅结果包含模型时出现，可有多项；Express 仅视频结果没有此项 |
| `cover` | 渲染预览图 | 通常有 |
| `image` | 模型生成过程中的参考图 | Tripo |
| `video` | 展示视频 | 混元 Express 选 `output_format: "mp4"` 时 |
请按 `kind` 识别产物，并用 `format` 选择模型文件，不要按 `index` 写死。例如需要 FBX 时筛选 `kind=model3d && format=fbx`，按 `filename` 保存；OBJ 压缩包会标为 `format=obj, container=zip`，文件名以 `.zip` 结尾。同一任务可能返回多种模型格式，每种格式和封面分别占一个产物序号。`state` 为 `unavailable` 时该产物暂不可读，稍后重新查询原任务；无法恢复时保留 ID 核对，不要重新提交生成。
### 下载模型文件
使用[快速开始的完整 Python 示例](overview.md#overview-h-600de8a7)，保存为 `media_client.py`；设置已有任务 ID 后只查询和下载：
```bash
export TASK_ID="替换为已有的 3D 任务 id"
python media_client.py
```
脚本遍历全部产物并按实际文件头命名：ZIP → `.zip`、GLB → `.glb`、可识别的二进制 FBX → `.fbx`，图片/视频按文件头或明确 MIME 保存。未知格式（例如通用 MIME 的文本 OBJ、STL 或无法辨明包装的 USDZ）保留 `.bin` 并提示。可再用文件识别工具或对应 3D 软件检查，不根据序号、签名 URL 或请求格式强改扩展名。
- OBJ ZIP + GLB + 封面应分别保存；使用已确认的 GLB 预览，或解包 OBJ 与贴图后导入支持它们的软件。单格式结果直接处理唯一模型项。
- Express 仅视频是有效的展示视频结果；下载 `video`，不能报告“模型文件必有”。Tripo 的模型、渲染预览和生成参考图用途不同。
- 产物可以乱序；序号只标识文件，没有首选格式或预览优先级。客户端不支持 FBX、材质或压缩时，使用相应软件查看/转换，改名不完成格式转换，也不应重新生成。
- 签名地址直接 GET，不带密钥，支持 HEAD/Range。重新查询可更新过期签名；上游文件过期/丢失不能靠重签恢复。尽快转存，下载失败只恢复原任务。
## 费用
- 提交时按模型价格预留费用（`billing.status: "reserved"`）；有可信计费证据并完成结算后为 `settled`，同时给出 `amount`。只有确定未发送、明确拒绝且确认没有收费，或可信证据确认零消耗时，才释放预留为 `released`。不能仅凭生成失败就判定免费。
- 按腾讯积分计价的失败任务，如果积分缺失、异常或非零，账务保持 `reconciling` 并保留冻结等待核对；不自动退款，也不重新提交生成。以任务账务状态和权威账单为准。
- 混元按次或按参数定价，使用提交时冻结的价格，之后改价不影响在途任务。
- Tripo 由管理员配置按次价，或按腾讯回报的实际积分计价。按积分计价时，预留只是估算，完成后按实际积分多退少补。
- 生成成功但用量证据缺失或异常时，`status` 为 `succeeded`、`billing.status` 为 `reconciling`、`amount` 为 `null`，表示费用待核对，不代表免费。重复查询不会重复扣费。
各账务状态的完整含义见[任务查询与结算](media-tasks.md)。
## 常见错误
| 报错信息（`error.message`） | 原因 | 改法 |
| --- | --- | --- |
| Model type does not match the submission path | 把图片或视频模型提交到了 3D 地址 | 3D 模型使用 `/media/v1/3d/generations` |
| prompt and image are mutually exclusive outside Sketch mode | 混元同时写了 `prompt` 和图片 | 二选一；需要图文结合时使用 `generate_type: "Sketch"` |
| Sketch requires both prompt and image | Sketch 模式缺少提示词或主图 | 同时提供两者 |
| prompt, image_url or image_base64 is required | 混元既没写提示词也没传图片 | 提供 `prompt` 或一张 `reference` 图片 |
| prompt, input or inputs is required | Tripo 既没写提示词也没传图片 | 提供 `prompt`、单图或多视图 |
| input and inputs are mutually exclusive | Tripo 同时传了单图 `reference` 和多视图 | 二选一 |
| multi_view_images requires a main image | 混元多视图缺少主图 | 加一张 `multi_view_front` 或 `reference` |
| 3D generation accepts only one main image | 混元同时传了 `reference` 和 `multi_view_front` | 只保留一张主图 |
| Repeated 3D reference role | 同一视角传了两张图 | 每个 `role` 只传一张 |
| prompt exceeds 1024 characters | 提示词过长 | 缩短到 1024 字符以内 |
| hy-3d-3.1 does not support LowPoly | 3.1 选了 `LowPoly` | 改用 `hy-3d-3.0` 或其他模式 |
| Express geometry output does not support obj | Express 白模选了 `obj` | 改用 `glb`、`stl` 等格式 |
| face_limit must be between 500 and 20000 for this configuration | Tripo 面数超出当前组合的范围（数字随组合变化） | 按 Tripo 面数表调整 |
| generate_parts requires texture, pbr and quad to be false | 开启部件拆分时未关闭纹理、PBR 或四边面 | 把三者都设为 `false` |
| Parameter output_format is not supported by this model | 给 Tripo 传了 `output_format` | 删除该字段 |
| Parameter provider_options.tencent.face_count is not supported by this model | 选项与模型不匹配，例如给 Express 传 `face_count` | 按本页参数表删除不支持的选项 |
| Parameter references.asset_id is not supported by this model | 3D 模型使用了素材库 `asset_id` | 改用 `url` 或 `file_id` |
| This model does not support task cancellation | 对 3D 任务调用了取消 | 3D 任务不能取消，等待完成即可 |
完整错误码见[媒体错误处理](media-errors.md)。已有腾讯原生调用方式的，可以继续使用[腾讯混元与 Tripo 3D](native-tencent-3d.md)；两种协议的任务互不相通，请用提交时的协议查询。