📢 【模型上新】现支持MiniMax-H3、Hi3D模型，可前往 模型广场 查看调用~
HY-3D 混元生3D（Maas测试指引）
接口文档
接口地址
| 功能 | 请求方式 | 地址 |
|---|---|---|
| 基础BaseURL | POST | https://vg-api.aig-ai.com/v2/8sdf2/hy-3d/ |
| 创建任务（官方原生路由） | POST | /v1/api/3d/submit |
| 查询任务（官方原生路由） | POST | /v1/api/3d/query |
提交混元生3D任务
generate_type 为 Sketch 模式时除外，该模式下 prompt 和 image_url/image_base64 可一起输入）。输入参数
| 参数名称 | 必选 | 类型 | 适用版本 | 描述 |
|---|---|---|---|---|
model | 否 | String | hy-3d-3.1 | 混元生3D生成模型版本，默认为 3.0，可选项：hy-3d-3.1、hy-3d-3.0。选择 hy-3d-3.1版本时，LowPoly 参数不可用。Express 版本固定为 hy-3d-express。 |
prompt | 否 | String | 全部 | 文生3D，3D内容的描述，中文正向提示词。Express 版最多支持 200 个 UTF-8 字符；3.1 版最多支持 1024 个 UTF-8 字符。示例值：一只小猫 |
image_base64 | 否 | String | 全部 | 输入图 Base64 数据。大小：单边分辨率不小于 128，不大于 5000，大小 ≤ 6M（因 Base64 编码后会大 30% 左右）。格式：jpg、png、jpeg、webp。示例值：/9j/4QlQaHR0c...N6a2M5ZCI |
image_url | 否 | String | 全部 | 输入图 URL。大小：单边分辨率不小于 128，不大于 5000，大小 ≤ 8M。格式：jpg、png、jpeg、webp。示例值：https://cos\.ap\-guangzhou\.myqcloud\.com/image\.jpg |
multi_view_images | 否 | Array of ViewImage | hy-3d-3.1 | 多视角模型图片，视角参考值：left（左视图）、right（右视图）、back（后视图）、top（顶视图，仅 3.1 版本支持）、bottom（底视图，仅 3.1 版本支持）、left_front（左前45°视图，仅 3.1 版本支持）、right_front（右前45°视图，仅 3.1 版本支持）。每个视角仅限一张图片。所有图片编码后总大小不可超过 8M（Base64 编码下不超过 6M）。单边分辨率 128~5000。支持格式：jpg 或 png。 |
enable_pbr | 否 | Boolean | 全部 | 是否开启 PBR 材质生成，默认 false。 |
enable_geometry | 否 | Boolean | Express | 是否开启单几何生成选项，开启后会生成不带纹理的 3D 模型（白模）。开启时，生成模型文件不支持 OBJ 格式，默认生成模型文件为 GLB 格式。 |
face_count | 否 | Integer | hy-3d-3.1 | 生成3D模型的面数，默认值为 500000。取值范围：[3000, 1500000]。generate_type 中选择 LowPoly 时，此参数不生效。示例值：100000 |
generate_type | 否 | String | hy-3d-3.1 | 生成任务类型，默认 Normal。枚举值：Normal（带纹理的几何模型）、LowPoly（智能拓扑后的模型，face_count 不生效）、Geometry（不带纹理的几何模型/白模，enable_pbr 不生效）、Sketch（输入草图或线稿图生成模型，此模式下 prompt 和 image 可一起输入）。 |
polygon_type | 否 | String | hy-3d-3.1 | 仅在 generate_type 为 LowPoly 时生效。多边形类型，默认 triangle。可选：triangle（三角形面）、quadrilateral（四边形面与三角形面混合）。 |
result_format | 否 | String | 全部 | 生成模型的格式，仅限一种。Express 版默认返回 OBJ 格式，可选值：OBJ、GLB、STL、USDZ、FBX、MP4。3.1 版默认返回 obj + glb 格式（开启 Geometry 时默认为 glb），可选值：STL、USDZ、FBX。 |
输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
id | String | 任务ID（有效期 24 小时）。示例值：1315932989749215232 |
request_id | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
object | — | — |
created_at | — | — |
status | — | — |
查询混元生3D任务
输入参数
| 参数名称 | 必选 | 描述 |
|---|---|---|
id | 是 | 任务ID。示例值：1357237233311637504 |
输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
status | String | 任务状态。可选值：completed（任务成功）、failed（任务失败）、in_progress（执行中）、queued（等待中） |
request_id | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
object | — | — |
created_at | — | — |
completed_at | — | — |
data | — | — |
示例
HY-3D-Express：提交文生3D任务
{
"id": "14721*****320",
"request_id": "11f64379-bb0b-46b2-b89f-17d75fc12365",
"object": "3d_job",
"created_at": 1784885898,
"status": "queued"
}HY-3D-3.0：提交文生3D任务
{
"id": "14721*****320",
"request_id": "11f64379-bb0b-46b2-b89f-17d75fc12365",
"object": "3d_job",
"created_at": 1784885898,
"status": "queued"
}HY-3D-3.1：提交文生3D任务
{
"id": "14721*****320",
"request_id": "11f64379-bb0b-46b2-b89f-17d75fc12365",
"object": "3d_job",
"created_at": 1784885898,
"status": "queued"
}查询任务结果
{
"request_id": "ab3beaeb-b4aa-4387-b5aa-e2ec1bba4ef0",
"object": "3d_job",
"created_at": 1784884760,
"completed_at": 1784884760,
"status": "completed",
"data": [
{
"type": "obj",
"url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/.../xxx.obj?q-sign-algorithm=sha1&...",
"preview_image_url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/.../preview_xxx.png?q-sign-algorithm=sha1&..."
},
{
"type": "glb",
"url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/.../xxx.glb?q-sign-algorithm=sha1&...",
"preview_image_url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/.../preview_xxx.png?q-sign-algorithm=sha1&..."
}
]
}data 数组包含生成的 3D 模型文件及预览图。每个对象包含 type（模型格式）、url（模型文件下载地址）和 preview_image_url（预览图地址），URL 带有签名且有时效性，需及时下载。