3D 生成模型具备出色的三维内容生成能力，能够根据用户输入的图像，快速生成具备多边形面片与 PBR 材质的高精度 3D 资产。通过这篇教程您可以学习到如何调用豆包 3D 生成模型 API 来生成 3D 文件。 :::tip 方舟平台的新用户？获取 API Key 及开通模型等准备工作，请参见 [快速入门](/docs/82379/1399008)。 ::: # 模型及API |**模型 ID（Model ID）** |**模型能力** |**产物规格** |**限流** |API | |---|---|---|---|---| |[doubao-seed3d-2-0-260328](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seed3d-2-0) |图生3D|**产物面数**|最大 RPM：300|[3D生成 API](https://www.volcengine.com/docs/82379/2353367) |\ | |||最大并发：5 | |\ | |* 生成带纹理和 PBR 材质的3D文件 |* 100000 面| | |\ | | |* 500000 面| | |\ | | |* 1000000面| | |\ | | || | |\ | | |**产物格式**| | |\ | | |glb 、obj、usd、usdz | | | |[hyper3d-gen2-260112](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=hyper3d-gen2) |文生3D、图生3D|**产物面数**|最大 RPM: 60|[影眸 API](https://www.volcengine.com/docs/82379/2279945) |\ | |||最大并发: 3 | |\ | |* 生成带纹理和 PBR 材质的 3D 文件 |* 三角面模型：[500, 1,000,000]| | |\ | | |* 四边面模型：[1,000, 200,000]| | |\ | | || | |\ | | |**产物格式**| | |\ | | || | |\ | | |* glb, obj, stl, fbx, usdz | | | |[hitem3d-2-0-251223](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=hitem3d-2-0) |图生3D|**产物面数**|最大 RPM: 600|[数美 API](https://www.volcengine.com/docs/82379/2307069) |\ | |||最大并发: 30 | |\ | |* 标准白膜|* [100000, 2000000]| | |\ | |* 标准纹理模型|| | |\ | |* 高精白膜|**产物格式**| | |\ | |* 高精纹理模型 || | |\ | | |* glb, obj, stl, fbx, usdz| | |\ | | || | |\ | | |**产物分辨率**| | |\ | | || | |\ | | |* 1536、1536 pro | | | # 模型价格请参见：[3D生成模型](/docs/82379/1544106#59e650ae) # 使用流程 3D 生成任务为异步任务。 1. 通过 **创建任务接口** 创建3D生成任务，获得 **任务 ID** 。 2. 通过 **任务查询接口** + **任务 ID** 查询任务状态，直到任务完成时，获取返回的 3D 产物下载链接，下载生成结果。 :::tip * 3D 生成过程耗时在分钟级别，通常在数分钟到十数分钟不等，具体受任务复杂度和平台负载影响。 * 返回的产物链接有效期为 24 小时，过时失效，请及时下载/转存产物。 ::: # 体验&调试可在 [API Explorer](https://api.volcengine.com/api-explorer/?action=Create3DGenerationsTasks&groupName=3D%E7%94%9F%E6%88%90API&serviceCode=ark&tab=2&tab_result=1&tab_sdk=CURL&version=2024-01-01)，0代码体验通过 API 调用 3D 模型。支持灵活调整参数（如控制输出产物格式等），方便您直观感受模型实际使用过程。 # 代码调用 ## 效果预览 |输入 |输出预览 | |---|---| |![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/078de189655e40c989543d829d421e2d~tplv-goo7wpa0wc-image.image =1024x) |![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2e27978997d04e52a51ccf27beb6c25e~tplv-goo7wpa0wc-image.image =1024x) |\ | |> 上图为效果展示。实际产物为3D文件，类似 [文件](https://ark-project.tos-cn-beijing.volces.com/doc_3D/seed3d_imageTo3d.glb)。 | ## 示例代码 ```mixin-react return ( 替换为你的任务 ID。 \`\`\`Bash curl -X GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/ \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer $ARK_API_KEY" \`\`\` `}> contents = new ArrayList<>(); // 参数 contents.add(Content.builder() .type("text") .text("--subdivisionlevel medium --fileformat glb") .build()); // 图片URL contents.add(Content.builder() .type("image_url") .imageUrl(CreateContentGenerationTaskRequest.ImageUrl.builder() .url("https://ark-project.tos-cn-beijing.volces.com/doc_image/seed3d_imageTo3d.png") .build()) .build()); // 创建3D生成任务 CreateContentGenerationTaskRequest createRequest = CreateContentGenerationTaskRequest.builder() .model(model) .content(contents) .build(); CreateContentGenerationTaskResult createResult = service.createContentGenerationTask(createRequest); System.out.println(createResult); System.out.println("----- GET Task Request -----"); // 获取任务详情 GetContentGenerationTaskRequest getRequest = GetContentGenerationTaskRequest.builder() .taskId(createResult.getId()) .build(); GetContentGenerationTaskResponse getResult = service.getContentGenerationTask(getRequest); System.out.println(getResult); System.out.println("----- LIST Task Request -----"); // 轮询查询部分 System.out.println("----- polling task status -----"); while (true) \{ try \{ GetContentGenerationTaskResponse getResponse = service.getContentGenerationTask(getRequest); String status = getResponse.getStatus(); if ("succeeded".equalsIgnoreCase(status)) \{ System.out.println("----- task succeeded -----"); System.out.println(getResponse); break; \} else if ("failed".equalsIgnoreCase(status)) \{ System.out.println("----- task failed -----"); System.out.println("Error: " + getResponse.getStatus()); break; \} else \{ System.out.printf("Current status: %s, Retrying in 60 seconds...", status); TimeUnit.SECONDS.sleep(60); \} \} catch (InterruptedException ie) \{ Thread.currentThread().interrupt(); System.err.println("Polling interrupted"); break; \} \} \} \} \`\`\` `}>); ``` # 其他说明 ## 控制产物参数通过`--[parameters]`的方式，控制3D文件输出的规格，包括产物面的数量、输出文格式等。 ```Bash # 指定生成的3D文件的多边形面的数量为 100000 面，生成的3D文件格式为 glb "content": [ { "type": "text", "text": "--subdivisionlevel medium --fileformat glb" } ] ``` ## 链接有效期任务数据（如任务状态、URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的文件。 ## 模型限流 * RPM 限流：账号下同模型（区分模型版本）每分钟允许创建的任务数量上限。若超过该限制，创建3D生成任务时会报错。 * 并发数限制：账号下同模型（区分模型版本）同一时刻在处理中的任务数量上限。超过此限制的任务将进入队列等待处理。 * 不同模型的限制值不同，详见[3D生成能力](/docs/82379/1330310#ddefa422)。

火山方舟