3D（3D Models）
Create 3D Generation Task
Submit a 3D generation or 3D post-processing task.
Select the model or capability via the model field, and pass additional 3D parameters in metadata. On success, returns a task_id which can be used to query status, result files, usage, and final billing.
Authorization
BearerAuth
AuthorizationBearer <token>
使用 Bearer Token 认证。
格式: Authorization: Bearer sk-xxxxxx
In: header
Request Body
application/json
model*string
模型 ID
metadata?
3D 模型参数。先根据 model 找到对应小节，再按该模型的输入组合传入 metadata。下面每个示例都是完整请求体，可以直接作为调试起点。
doubao-seed3d-2-0-260328
图生 3D，只需要一张图片。
| 字段 | 类型 | 说明 |
|---|---|---|
images | array | 必填，传 1 张图片：[{"url":"https://example.com/object.png"}]。支持 HTTP URL 或 data URI Base64。图片要求：像素 < 4096×4096，大小 ≤ 10MB，宽高比在 (0.4, 2.5) 之间，格式 jpg/jpeg/png/webp/bmp。 |
file_format | string | 输出格式：glb / obj / usd / usdz，默认 glb。 |
quality_level | string | 质量档位：high / medium / low；对应 high=1M、medium=500k（默认）、low=100k。 |
最小请求：
{
"model": "doubao-seed3d-2-0-260328",
"metadata": {
"images": [{"url": "https://example.com/object.png"}],
"file_format": "glb",
"quality_level": "medium"
}
}hyper3d-gen2-260112
支持文生 3D 和图生 3D。文生只传 prompt；图生传 images，也可以同时加英文 prompt 描述图片。
| 字段 | 类型 | 说明 |
|---|---|---|
prompt | string | 文生必填，图生可选。仅英文，最长 400 字符。 |
images | array | 图生必填，1-5 张图片：[{"url":"https://example.com/ref.png"}]。支持 HTTP URL 或 data URI Base64。图片格式 jpg/jpeg/png，像素 < 4096×4096，大小 ≤ 30MB。 |
file_format | string | 输出格式：glb / obj / usdz / fbx / stl，默认 glb。 |
material | string | 材质类型：pbr / shaded / all / none，默认 pbr。 |
mesh_mode | string | 网格类型：raw / quad，默认 quad。 |
face_count | integer | 精确面数。raw：[500,1000000]，默认 500000；quad：[1000,200000]，默认 18000。与 quality_level 同时传时，本字段优先。 |
quality_level | string | 质量档位：high / medium / low。Raw：high=500k（默认）/medium=150k/low=20k；Quad：high=50k/medium=18k（默认）/low=8k。 |
seed | integer | 随机种子，[0,65535]。 |
use_original_alpha | boolean | 是否保留图片透明轮廓，默认 false。 |
hd_texture | boolean | 是否启用 HD 纹理，默认 false。 |
addons | string | high_pack 表示 4K 纹理；不传为 2K 纹理。 |
ta_pose | boolean | 类人模型是否强制 T/A Pose，默认 false。 |
bbox_condition | array | 模型边界框尺寸 [宽,高,长]。 |
文生请求：
{
"model": "hyper3d-gen2-260112",
"metadata": {
"prompt": "A stylized treasure chest with gold metal details",
"file_format": "glb",
"material": "pbr",
"mesh_mode": "quad"
}
}图生请求：
{
"model": "hyper3d-gen2-260112",
"metadata": {
"images": [{"url": "https://example.com/object.png"}],
"prompt": "A clean hard-surface 3D asset",
"file_format": "glb",
"quality_level": "medium"
}
}hitem3d-2-0-251223
图生 3D，传 1-4 张图片。图片必须是 HTTP URL。多视角时给图片加 view。
| 字段 | 类型 | 说明 |
|---|---|---|
images | array | 必填，1-4 张图片。普通图生：[{"url":"https://example.com/object.jpg"}]。多视角：[{"url":"...front.jpg","view":"front"},{"url":"...left.jpg","view":"left"}]。格式 jpg/jpeg/png/webp，像素 < 4096×4096，大小 ≤ 10MB。 |
file_format | string | 输出格式：obj / glb / stl / fbx / usdz，默认 obj。 |
face_count | integer | 目标面数，[100000,2000000]，推荐 2000000。 |
geometry_only | boolean | 是否只生成白模 / 纯几何；true 表示纯几何，false 表示几何+纹理。 |
resolution | string | 分辨率：1536 / 1536pro，默认 1536。 |
多视角只使用 front / back / left / right。未传 view 时，图片按原数组顺序发送，不推断默认视角。
请求示例：
{
"model": "hitem3d-2-0-251223",
"metadata": {
"images": [
{"url": "https://example.com/front.jpg", "view": "front"},
{"url": "https://example.com/left.jpg", "view": "left"}
],
"file_format": "glb",
"face_count": 2000000,
"resolution": "1536"
}
}hunyuan-3d-rapid
文生 3D 和图生 3D 二选一：文生只传 prompt；图生只传 images[0]。不要同时传 prompt 和图片。
| 字段 | 类型 | 说明 |
|---|---|---|
prompt | string | 文生 3D 输入，最长 200 个 UTF-8 字符，支持中文。 |
images | array | 图生 3D 输入，只读取第一张：[{"url":"https://example.com/object.png"}]。支持 HTTP URL 或 data URI Base64。图片单边 128-5000px，URL≤8MB，Base64 原始数据≤6MB，格式 jpg/png/jpeg/webp。 |
file_format | string | 输出格式：obj / glb / stl / usdz / fbx / mp4，默认 obj。 |
enable_pbr | boolean | 是否启用 PBR。 |
geometry_only | boolean | 是否只生成白模 / 纯几何。开启后 PBR 不生效；若同时传入不兼容的 file_format，可能返回参数错误。 |
文生请求：
{
"model": "hunyuan-3d-rapid",
"metadata": {
"prompt": "一只卡通小猫",
"file_format": "glb",
"enable_pbr": true
}
}图生请求：
{
"model": "hunyuan-3d-rapid",
"metadata": {
"images": [{"url": "https://example.com/object.png"}],
"file_format": "glb",
"enable_pbr": true
}
}hunyuan-3d-pro-3.0 / hunyuan-3d-pro-3.1
文生、图生、多视角都走同一个模型 ID。文生只传 prompt；普通图生传 1 张不带 view 的主图；多视角图生必须先传主图，再追加带 view 的视角图。
| 字段 | 类型 | 说明 |
|---|---|---|
prompt | string | 文本提示词，最长 1024 个 UTF-8 字符，支持中文。Normal / LowPoly / Geometry 模式下不能和主图同时传；Sketch 模式下可以和主图同时传。 |
images | array | 图生 / 多视角输入。主图不要传 view：[{"url":"https://example.com/front.png"}]。多视角图追加在主图后，并必须传 view：{"url":"https://example.com/left.png","view":"left"}。主图支持 jpg/jpeg/png/webp；多视角图支持 jpg/png。 |
file_format | string | 显式输出格式。官方枚举为 STL/USDZ/FBX；不传时使用默认 obj+glb。显式传入其他值时可能返回参数错误。 |
enable_pbr | boolean | 是否启用 PBR。geometry_only=true 时不生效。 |
face_count | integer | 目标面数，[3000,1500000]，默认 500000。LowPoly / Geometry 模式下不生效，但用户显式传入时仍会发送。 |
generate_mode | string | 生成模式：normal / low_poly / sketch，默认 normal。low_poly 仅 3.0 支持；3.1 不建议传 low_poly，如传入可能返回参数错误。 |
geometry_only | boolean | 白模 / 纯几何模式。不要和显式 generate_mode 同时传。 |
polygon_type | string | LowPoly 模式下使用，triangle / quadrilateral，默认 triangle；quadrilateral 表示四边形与三角形混合。 |
文生请求：
{
"model": "hunyuan-3d-pro-3.1",
"metadata": {
"prompt": "一只写实风格的小猫",
"generate_mode": "normal",
"enable_pbr": true
}
}普通图生请求：
{
"model": "hunyuan-3d-pro-3.1",
"metadata": {
"images": [{"url": "https://example.com/front.png"}],
"generate_mode": "normal",
"enable_pbr": true
}
}多视角图生请求：
{
"model": "hunyuan-3d-pro-3.1",
"metadata": {
"images": [
{"url": "https://example.com/front.png"},
{"url": "https://example.com/left.png", "view": "left"},
{"url": "https://example.com/right.png", "view": "right"}
],
"generate_mode": "normal",
"enable_pbr": true
}
}视角支持：3.0 支持 left / right / back；3.1 支持 left / right / back / top / bottom / left_front / right_front。不要给主图传 view，否则它会被当作多视角图处理。
hunyuan-3d-reduce-face
智能拓扑 / 减面。传一个 OBJ 或 GLB 文件，按需要指定拓扑类型和面数级别。
| 字段 | 类型 | 说明 |
|---|---|---|
input_file | object | 必填，输入 3D 文件：{"url":"https://example.com/model.glb","type":"GLB"}。type 支持 OBJ / GLB。 |
polygon_type | string | 多边形类型：triangle / quadrilateral，默认 triangle；quadrilateral 表示四边形面。 |
face_level | string | 面数级别：high / medium / low。 |
请求示例：
{
"model": "hunyuan-3d-reduce-face",
"metadata": {
"input_file": {"url": "https://example.com/model.glb", "type": "GLB"},
"polygon_type": "quadrilateral",
"face_level": "medium"
}
}hunyuan-3d-texture-3.0 / hunyuan-3d-texture-3.1
纹理生成必须传源 3D 模型文件 input_file，并且还要在 prompt 和单张参考图之间二选一。3.1 可以再额外追加多视角参考图。
| 字段 | 类型 | 说明 |
|---|---|---|
input_file | object | 必填，源 3D 模型文件：{"url":"https://example.com/model.glb","type":"GLB"}。type 支持 OBJ / GLB。 |
prompt | string | 纹理提示词，最长 200 个 UTF-8 字符。和无 view 的单张参考图二选一，不能同时传。 |
images | array | 参考图。单张参考图不要传 view：[{"url":"https://example.com/ref.png"}]。3.1 多视角参考图需要传 view，例如 {"url":"https://example.com/left.png","view":"left"}。参考图支持 jpg/jpeg/png。 |
enable_pbr | boolean | 是否启用 PBR，默认 false。 |
enable_keep_uv | boolean | 是否保留 UV，默认 false。 |
texture_size | integer | 正方形贴图边长，[720,4096]，默认 4096。 |
Prompt 纹理请求：
{
"model": "hunyuan-3d-texture-3.1",
"metadata": {
"input_file": {"url": "https://example.com/model.glb", "type": "GLB"},
"prompt": "蓝白陶瓷纹理",
"enable_pbr": true,
"texture_size": 2048
}
}参考图纹理请求：
{
"model": "hunyuan-3d-texture-3.1",
"metadata": {
"input_file": {"url": "https://example.com/model.glb", "type": "GLB"},
"images": [
{"url": "https://example.com/ref.png"},
{"url": "https://example.com/left.png", "view": "left"}
],
"enable_pbr": true
}
}3.1 多视角支持 left / right / back / top / bottom / left_front / right_front，每个视角一张。多视角图是额外参考，不能替代必填的 prompt 或无 view 的单张参考图。
hunyuan-3d-profile
3D 人物生成。可传人物头像，也可传模板。官方将两者都标为可选，平台不额外增加必填校验。
| 字段 | 类型 | 说明 |
|---|---|---|
images | array | 人物头像，读取第一张：[{"url":"https://example.com/profile.png"}]。图片单边 >500 且 <4096，Base64 <10MB，支持 jpg/jpeg/png。 |
template | string | 人物模板枚举：basketball（动感球手）、badminton（羽扬中华）、pingpong（国球荣耀）、gymnastics（勇攀巅峰）、pilidance（舞动青春）、tennis（网球甜心）、athletics（东方疾风）、footballboykicking1（激情逐风）、footballboykicking2（绿茵之星）、guitar（甜酷弦音）、footballboy（足球小将）、skateboard（滑跃青春）、futuresoilder（未来战士）、explorer（逐梦旷野）、beardollgirl（可爱女孩）、bibpantsboy（都市白领）、womansitpose（职业丽影）、womanstandpose2（悠闲时光）、mysteriousprincess（海洋公主）、manstandpose2（演讲之星）。 |
请求示例：
{
"model": "hunyuan-3d-profile",
"metadata": {
"images": [{"url": "https://example.com/profile.png"}],
"template": "basketball"
}
}hunyuan-3d-auto-rigging
绑骨蒙皮。传一个 FBX 或 GLB 文件，可选动作模板编号。
| 字段 | 类型 | 说明 |
|---|---|---|
input_file | object | 必填，输入 3D 文件：{"url":"https://example.com/character.glb","type":"GLB"}。type 支持 FBX / GLB，文件不超过 60MB。 |
motion_type | integer | 动作模板编号 [1,48]；非人形角色不支持动作模板。 |
请求示例：
{
"model": "hunyuan-3d-auto-rigging",
"metadata": {
"input_file": {"url": "https://example.com/character.glb", "type": "GLB"},
"motion_type": 23
}
}hunyuan-3d-motion
文生动作。必须传动作描述 prompt，可选传一个重定向 3D 文件。
| 字段 | 类型 | 说明 |
|---|---|---|
prompt | string | 必填，动作描述，最多 128 字符。 |
input_file | object | 可选，重定向用 3D 文件：{"url":"https://example.com/character.glb","type":"GLB"}。传入时 url / type 均必填；官方未给 type 枚举。 |
duration | integer | 动作时长 [1,12] 秒，默认 5。 |
enable_mesh | boolean | 是否返回带蒙皮 mesh 的 FBX，默认 true。 |
enable_rewrite | boolean | 是否扩写提示词，默认 false。 |
enable_duration_est | boolean | 是否自动匹配动作时长，默认 false。 |
请求示例：
{
"model": "hunyuan-3d-motion",
"metadata": {
"prompt": "角色向前慢跑并挥手",
"duration": 5,
"enable_mesh": true,
"enable_rewrite": false,
"enable_duration_est": false
}
}images 与 input_file 结构
images 是图片数组，每项至少包含 url。普通单图不要传 view；多视角图片才传 view。
[{"url":"https://example.com/front.png"}][{"url":"https://example.com/front.png"},{"url":"https://example.com/left.png","view":"left"}]input_file 是 3D 文件对象：
{"url":"https://example.com/model.glb","type":"GLB"}Response Body
application/json
application/json
curl -X POST "https://loading/v1/3d/generations" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seed3d-2-0-260328", "metadata": { "images": [ { "url": "https://example.com/object.png" } ], "file_format": "glb", "quality_level": "medium" } }'{
"task_id": "task_aehCmxJ5YUNOIQGgkhvxaco4T9P2h3Dw",
"status": "QUEUED",
"object": "3d.generation",
"model": "hunyuan-3d-pro-3.1"
}{
"error": {
"message": "string",
"type": "string",
"param": "string",
"code": "string"
}
}Last updated on