火山方舟
火山方舟
API参考
请输入
- 文档首页
火山方舟3D生成 API影眸 API创建3D生成任务
复制全文
下载 pdf创建3D生成任务
文档反馈
问问助手POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
本文介绍创建影眸 3D 生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片信息生成 3D，待生成完成后，您可以按条件查询任务并获取生成的 3D 文件。
计费说明
模型能力
- Hyper3d-Gen2
- 文生 3D：输入文本提示词 + 参数（可选），生成一个 3D 模型文件。
- 图生 3D：输入图片（1-5张）+文本提示词（可选）+ 参数（可选）生成一个 3D 模型文件。
鉴权
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数
Body 参数
model string 必选 | 模型 ID
content object[] 必选 | 输入内容列表
输入给模型生成 3D 内容的信息，支持文本、图片等类型的元素。
支持以下几种组合：
文生 3D
- 纯文本
- 文本 + 参数（可选）
图生 3D
- 图片
- 图片 + 文本（可选）
- 图片 + 参数（可选）
- 图片 + 文本（可选）+ 参数（可选）
文本信息 object
文本部分，作为生成内容的文本提示词。
type string 必选 | 内容类型
content.type
输入内容的类型，此处固定为 text。
text string 必选 | 文本提示词
content.text
输入给模型的文本内容，包括：
- 文本提示词：仅支持英文，长度不超过 400 字符，超过后将截断。
- 参数（选填）：通过 --[parameters] 的方式，控制 3D 文件输出的规格，详情见 模型文本命令（选填）。
图片信息 object
输入给模型的图片信息。
type string 必选 | 内容类型
content.type
输入内容的类型，此处固定为 image_url。
image_url object 必选 | 图片对象
content.image_url
输入给模型的图片对象。
url string 必选 | 图片来源
content.image_url.url
图片 URL 或图片 Base64 编码。
- 图片 URL：需确保图片 URL 可被访问。
- Base64 编码：需遵循此格式data:image/<图片格式>;base64,<Base64编码>，注意 <图片格式> 需小写，如 data:image/png;base64,{base64_image}。
传入图片要求
- 格式：jpg、jpeg、png
- 总像素：小于 4096 × 4096 px
- 大小：单张图片不超过 30 MB
- 数量：最多上传 5 张图片
seed integer | 随机种子
种子整数，用于控制生成内容的随机性。
取值范围：[0, 65535]
注意
- 相同的请求下，模型收到不同的 seed 值，将生成不同的结果。
- 相同的请求下，模型收到相同的 seed 值，会生成类似的结果，但不保证完全一致。
callback_url string | 回调地址
回调返回的 status 包括以下状态：
- queued：排队中
- running：任务运行中
- succeeded： 任务成功（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）
- failed：任务失败（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）
模型文本命令参数（选填）
以下参数通过 content.text ，以 --<参数名> <参数值> 形式传入。
参数传入方式示例
material string 默认值 PBR | 材质类型
控制 3D 模型的材质类型。可选值：
- PBR：物理基础材质，包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理，提供高真实感并在动态光照下具有物理准确性。
- Shaded：风格化材质，包括基础颜色纹理和烘焙光照。
- All：同时生成 PBR 和 Shaded 材质。
- None：无纹理，即生成白模。
mesh_mode string 默认值 Quad | 网格形状
控制生成模型的网格形状。可选值：
- Raw：生成三角面模型。
- Quad：生成四边面模型。
quality_override number | 多边形面数
自定义 3D 模型的多边形面数。不同网格形状对应的取值存在差异：
- 当 mesh_mode=Raw 时：取值范围为 [500, 1000000]，默认值为 500000。
- 当 mesh_mode=Quad时：取值范围为 [1000, 200000]，默认值为 18000。
说明
- quality_override 与 subdivisionlevel 同时设置时，subdivisionlevel 不生效。
- 建议取值 ≥150000。
addons string | 纹理增强
增强纹理贴图分辨率。可选值：
- HighPack：提供 4K 分辨率的纹理贴图。
说明
不配置该参数时，默认生成 2K 分辨率的纹理贴图。
use_original_alpha boolean 默认值 false | 透明区域处理
是否保留输入图片的透明区域。
- true：保留透明区域，生成的 3D 模型或贴图按原图透明轮廓处理。
- false：自动填充透明区域，可能丢失原始透明效果。
bbox_condition integer[] | 模型边界
指定模型边界的宽度、高度和长度，例如 [100, 100, 100]。
说明
如无特殊需求，建议不设置，由模型自动判断边界。
TAPose boolean 默认值 false | 标准绑定姿态
生成类人模型时，是否强制使用 T-Pose 或 A-Pose 标准绑定姿态。
- true：强制使用标准绑定姿态，由模型判断使用 T-Pose 或 A-Pose。
- false：不强制使用标准绑定姿态，由模型自行决定。
subdivisionlevel string 简写 sl | 多边形面数等级
控制 3D 模型的多边形面数。不同网格形状对应的取值存在差异：
- 当mesh_mode=Raw时，可选值：
- high（默认值）：500k
- medium：150k
- low：20k
- 当mesh_mode=Quad时，可选值：
- high：50k
- medium（默认值）：18k
- low：8k
fileformat string 默认值 glb 简写 ff | 文件格式
生成的有纹理 3D 模型文件格式，可选值：
- glb
- obj
- usdz
- fbx
- stl
hd_texture boolean 默认值 false | HD 纹理
是否启用 HD 纹理。
- true：启用 HD 纹理。
- false：不启用 HD 纹理。
响应参数
id string | 任务 ID
3D 生成任务 ID。仅保存 7 天（从 created_at 时间戳开始计算），超时后将自动清除。
文生3D
图生3D
发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！
Request
cURL
curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY" \
-d '{
"model": "hyper3d-gen2-260112",
"content": [
{
"type": "text",
"text": "Full-body quadrupedal mech robot with orange-black armor, a rounded head, blue sensors, four articulated legs, detailed sci-fi joints, fully assembled. --mesh_mode Raw --hd_texture true --material PBR --addons HighPack --quality_override 1000000 --use_original_alpha false --bbox_condition [100,100,100] --TAPose false"
}
],
"seed": 8648
}'Response
{
"id": "cgt-2026******-****",
}最近更新时间：2026.10.23 14:13:41
这个页面对您有帮助吗？
有用
有用
无用
无用