> ## Documentation Index
> Fetch the complete documentation index at: https://docs-model.skyengine.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Tripo 3D 生成示例

> 通过 TokenHub 使用 Tripo 3.1、P1、P2，支持文生、单图和多视图 3D 生成。

# Tripo 3D 生成

Tripo 使用异步接口：提交生成任务后，保存平台任务 ID，再查询生成状态并下载模型文件。

```text theme={null}
POST /v1/3d/submit
POST /v1/3d/query
```

> [!NOTE]
>
> 请使用平台域名、平台 API Key 和模型广场展示的模型名称。
> 本文中的模型名为配置示例；可先通过 `GET /v1/models` 确认当前账号可用的模型。

## 模型与输入方式

| 模型名称示例 | 文本 | 单图 / 多视图 | 主要限制 |
| - | - | - | - |
| `tokenhub/tripo-3d-3.1` | 支持 | 支持 | 支持智能低模、分部件与超清几何 |
| `tokenhub/tripo-3d-p1` | 支持 | 支持 | 不支持 `quad`、智能低模、分部件与超清几何 |
| `tokenhub/tripo-3d-p2` | 支持 | 支持 | 支持 `quad`，面数范围与 3.1 不同 |

## 快速开始

下面生成不带纹理的简单模型。`texture` 和 `pbr` 都需要显式设为 `false`。
Python 示例依赖 `requests`，运行前设置环境变量 `API_KEY`。

```bash cURL theme={null}
curl --request POST \
  --url https://model-api.skyengine.com.cn/v1/3d/submit \
  --header 'Authorization: Bearer <API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "tokenhub/tripo-3d-3.1",
    "prompt": "一个边角略微圆润的简单立方体",
    "texture": false,
    "pbr": false
  }'
```

```python Python theme={null}
import os
import time
from pathlib import Path
from urllib.parse import urlparse

import requests

BASE_URL = "https://model-api.skyengine.com.cn"
HEADERS = {
    "Authorization": f"Bearer {os.environ['API_KEY']}",
    "Content-Type": "application/json",
}

# 只提交一次；超时后先核查已有任务，避免重复扣费。
response = requests.post(
    f"{BASE_URL}/v1/3d/submit",
    headers=HEADERS,
    json={"model": "tokenhub/tripo-3d-3.1", "prompt": "一个边角略微圆润的简单立方体", "texture": False, "pbr": False},
    timeout=120,
)
if response.headers.get("X-Task-ID"):
    print("任务 ID:", response.headers["X-Task-ID"])
response.raise_for_status()
task_id = response.json()["id"]
print("已提交:", task_id)

deadline = time.monotonic() + 15 * 60
while time.monotonic() < deadline:
    response = requests.post(
        f"{BASE_URL}/v1/3d/query",
        headers=HEADERS,
        json={"id": task_id},
        timeout=60,
    )
    response.raise_for_status()
    result = response.json()
    status = result["status"]
    print(task_id, status)
    if status == "completed":
        model_url = result["output"]["model_url"]
        suffix = Path(urlparse(model_url).path).suffix or ".glb"
        asset = requests.get(model_url, timeout=120)
        asset.raise_for_status()
        Path(f"model{suffix}").write_bytes(asset.content)
        print("目录金额:", result.get("amount_cny"))
        break
    if status in {"failed", "submission_unknown"}:
        raise RuntimeError(f"任务 {task_id}: {status}, {result.get('error')}")
    time.sleep(10)
else:
    raise TimeoutError(f"等待超时，请继续查询已有任务 {task_id}，不要重新提交")
```

提交成功响应示例：

```json theme={null}
{
  "id": "<平台任务ID>",
  "object": "3d_job",
  "model": "tripo-3d-3.1",
  "status": "pending"
}
```

## 输入示例

`prompt`、`input`、`inputs` 三选一。图片必须能被服务访问；格式和大小遵守厂商要求。

### 单图生成

```json theme={null}
{
  "model": "tokenhub/tripo-3d-p1",
  "input": "https://example.com/character.png",
  "texture": true,
  "pbr": true
}
```

### 多视图生成

必须包含 `front`，并至少再提供 `back`、`left`、`right` 中的一种视图，每个视角只能出现一次。

```json theme={null}
{
  "model": "tokenhub/tripo-3d-3.1",
  "inputs": {
    "front": "https://example.com/front.png",
    "back": "https://example.com/back.png"
  },
  "texture": false,
  "pbr": false
}
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 模型广场中的模型名称 |
| `prompt` | string | 条件必填 | 文本输入，最多 1024 个字符 |
| `input` | string | 条件必填 | 单张图片的 HTTP(S) URL |
| `inputs` | object / array | 条件必填 | 命名视图对象，或由命名视图对象组成的数组 |
| `negative_prompt` | string | 否 | 负面提示词，最多 255 个字符 |
| `texture` / `pbr` | boolean | 否 | 默认开启；开启 PBR 时会启用贴图 |
| `face_limit` | integer | 否 | 目标面数，范围见下表 |
| `texture_alignment` | string | 否 | `original_image`、`geometry` |
| `texture_quality` | string | 否 | `fast`、`standard`、`detailed`、`extreme` |
| `texture_version` | string | 否 | `v3.5-20260815`、`v3.0-20250812`、`v2.5-20250123`；`fast` 要求 `v3.5-20260815` |
| `geometry_quality` | string | 否 | 仅 3.1：`standard`、`detailed` |
| `quad` | boolean | 否 | 四边面，P1 不支持 |
| `smart_low_poly` | boolean | 否 | 智能低模，仅 3.1 |
| `generate_parts` | boolean | 否 | 分部件，仅 3.1；要求 `texture=false`、`pbr=false`、`quad=false` |
| `export_uv` | boolean | 否 | 是否导出 UV |
| `compress` | string | 否 | 仅 3.1，可设为 `geometry` |
| `orientation` | string | 否 | `default`、`align_image` |
| `image_seed` / `model_seed` / `texture_seed` | integer | 否 | 随机种子 |
| `enable_image_autofix` / `delight` / `auto_size` | boolean | 否 | 对应图片修正、去光照和尺寸处理选项 |
| `include_cost` | boolean | 否 | 设为 `true`，在查询结果的 `usage` 中查看销售费用 |

### 面数范围

| 配置 | `face_limit` |
| - | - |
| 3.1 默认 | 1–1,500,000 |
| 3.1 `geometry_quality=detailed` | 1–2,000,000 |
| 3.1 `quad=true` | 1–150,000 |
| 3.1 `smart_low_poly=true` | 500–20,000；同时开启 `quad` 时上限 10,000 |
| P1 | 50–20,000 |
| P2 | 48–50,000；开启 `quad` 时上限 25,000 |

不同版本的可用参数以平台校验和 [TokenHub Tripo 调用指南](https://cloud.tencent.com/document/product/1823/137074)为准。
HY-3D 的 `image_url`、`generate_type`、`enable_pbr` 等参数不用于 Tripo。

## 查询任务

使用提交响应中的平台任务 `id` 查询；查询时只需传 `id`：

```bash cURL theme={null}
curl --request POST \
  --url https://model-api.skyengine.com.cn/v1/3d/query \
  --header 'Authorization: Bearer <API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"id":"<平台任务ID>"}'
```

只能使用提交任务时的用户和 API Key 查询。建议每 10 秒查询一次。
客户端停止查询不会取消任务。任务记录保留 7 天。

### 任务状态

| 状态 | 含义 | 处理方式 |
| - | - | - |
| `pending` | 等待生成 | 继续查询 |
| `in_progress` | 生成或结果转存中 | 继续查询 |
| `completed` | 生成成功，结果文件已就绪 | 下载结果 |
| `failed` | 明确失败 | 查看 `error.message` |
| `submission_unknown` | 尚不能确认上游是否受理 | 保存任务 ID，联系平台核查，避免重新提交 |

响应头 `X-Task-ID` 也会提供平台任务 ID。请求超时或提交返回 5xx 时，
如已获取任务 ID，应先查询该任务，避免重复提交产生额外费用。

### 成功响应

```json theme={null}
{
  "id": "<平台任务ID>",
  "object": "3d_job",
  "status": "completed",
  "credits_consumed": 10,
  "amount_cny": "0.7",
  "output": {
    "type": "text_to_model",
    "model_url": "https://example.com/model.glb",
    "generated_image_url": "https://example.com/reference.png",
    "rendered_image_url": "https://example.com/preview.png"
  }
}
```

可用文件以实际返回为准，参考图与预览图字段可能为空。
下载链接有效期为 1 天，重新查询可获取新链接。

## 计费说明

按上游实际返回的 `credits_consumed` 换算人民币目录金额：**1 积分 = ¥0.07**。
`amount_cny` 是目录金额，最终销售费用还取决于模型价格倍率和用户折扣，
以调用时模型广场价格及结算结果为准。

预付费调用在提交时预扣、完成后多退少补；配置为后付费的调用在结束后结算。
明确无消耗的失败任务退款或不扣费；消耗缺失或提交结果未知时需要核查。
文件转存重试不会重新生成或重复扣费。

## 常见错误

| 场景 | 处理建议 |
| - | - |
| 参数校验失败 | 检查输入组合、模型版本与参数范围 |
| 生成失败 | 查看查询结果中的 `error.message`，保留任务 ID 供排查 |
| 已有任务执行中，无法提交 | 等待当前任务结束后再提交 |
| 余额不足或计费配置不可用 | 检查账户余额和模型价格配置 |
| 查询返回 404 | 核对平台任务 ID，并使用提交时的用户和 API Key |
| 提交超时或 `submission_unknown` | 先查询已有任务，避免立即重复提交 |
| 结果链接无法下载 | 重新查询任务获取下载地址；链接有效期为 1 天 |
| 长时间停留在 `in_progress` | 保留任务 ID 联系平台；单个文件转存上限为 64 MiB |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.