火山方舟
火山方舟
文档指南
请输入
调用
视频生成
工具调用
使用 Responses API
推理
训练
模型精调
Managed Agents
配置 Agent 环境
管理 Agent 上下文
高级能力
- 文档首页
火山方舟调用领域模型3D 生成
复制全文
下载 pdf3D 生成
文档反馈
问问助手3D 生成模型具备出色的三维内容生成能力，能够根据用户输入的图像，快速生成具备多边形面片与 PBR 材质的高精度 3D 资产。通过这篇教程您可以学习到如何调用豆包 3D 生成模型 API 来生成 3D 文件。
说明
模型及API
模型 ID（Model ID） | 模型能力 | 产物规格 | 限流 | API |
模型 ID（Model ID） | 模型能力 | 产物规格 | 限流 | API |
图生3D
| 产物面数
产物格式
| 最大 RPM：300 最大并发：5 | ||
文生3D、图生3D
| 产物面数
产物格式
| 最大 RPM: 60 最大并发: 3 | ||
图生3D
| 产物面数
产物格式
产物分辨率
| 最大 RPM: 600 最大并发: 30 |
模型价格
使用流程
3D 生成任务为异步任务。
- 通过 创建任务接口 创建3D生成任务，获得 任务 ID 。
- 通过 任务查询接口 + 任务 ID 查询任务状态，直到任务完成时，获取返回的 3D 产物下载链接，下载生成结果。
说明
- 3D 生成过程耗时在分钟级别，通常在数分钟到十数分钟不等，具体受任务复杂度和平台负载影响。
- 返回的产物链接有效期为 24 小时，过时失效，请及时下载/转存产物。
体验&调试
代码调用
效果预览
输入 | 输出预览 |
输入 | 输出预览 |
| |
示例代码
Python
Curl
Go
Java
import os
import time
# Install SDK: python -m pip install --upgrade arkruntime
from arkruntime import Ark
# 初始化Ark客户端
client = Ark(
# The base URL for model invocation .
base_url="https://ark.cn-beijing.volces.com/api/v3",
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key=os.getenv('ARK_API_KEY'),
)
print("----- create request -----")
# 创建3D生成任务
create_result = client.content_generation.tasks.create(
# Replace with Model ID .
model="doubao-seed3d-2-0-260328",
content=[
{
# 参数
"type": "text",
"text": "--subdivisionlevel medium --fileformat glb"
},
{
# 图片URL
"type": "image_url",
"image_url": {
"url": "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/seed3d_imageTo3d.png"
}
}
]
)
print(create_result)
# 轮询查询部分
print("----- polling task status -----")
task_id = create_result.id
max_attempts = 60
for attempt in range(1, max_attempts + 1):
get_result = client.content_generation.tasks.get(task_id=task_id)
status = get_result.status
if status == "succeeded":
print("----- task succeeded -----")
print(get_result)
break
elif status == "failed":
print("----- task failed -----")
print(f"Error: {get_result.error}")
break
if attempt == max_attempts:
raise TimeoutError(f"Task {task_id} did not finish after {max_attempts} attempts")
print(f"Current status: {status}, retrying after 60 seconds...")
time.sleep(60)
- 创建3D生成任务，获取 3D 生成任务 ID。
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": "doubao-seed3d-2-0-260328",
"content": [
{
"type": "text",
"text": "--subdivisionlevel medium --fileformat glb"
},
{
"type": "image_url",
"image_url": {
"url": "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/seed3d_imageTo3d.png"
}
}
]
}'
- 查询 3D 生成任务状态，直至任务状态为Success，返回产物下载链接。
替换 <TASK_ID> 为你的任务 ID。
curl -X GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/<TASK_ID> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY"
package main
import (
"context"
"fmt"
"os"
"time"
"github.com/volcengine/ark-runtime-go/arkruntime"
model "github.com/volcengine/ark-runtime-go/arkruntime/model/contentgeneration"
)
func main() {
// 请确保您已将 API Key 存储在环境变量 ARK_API_KEY 中
// 初始化Ark客户端，从环境变量中读取您的API Key
client := arkruntime.NewClientWithApiKey(
// 从环境变量中获取您的 API Key。此为默认方式，您可根据需要进行修改
os.Getenv("ARK_API_KEY"),
// The base URL for model invocation .
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
// Replace with Model ID .
modelEp := "doubao-seed3d-2-0-260328"
// 创建任务
fmt.Println("----- create request -----")
createReq := &model.CreateContentGenerationTaskRequest{
Model: modelEp,
Content: []model.ContentItem{
{
Type: model.ContentTypeText,
Text: model.NewOptString("--subdivisionlevel medium --fileformat glb"),
},
{
Type: model.ContentTypeImageURL,
ImageURL: model.NewOptImageURL(model.ImageURL{
URL: "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/seed3d_imageTo3d.png",
}),
},
},
}
createResp, err := client.CreateContentGenerationTask(ctx, createReq)
if err != nil {
fmt.Printf("create content generation error: %v", err)
return
}
taskID := createResp.ID
fmt.Printf("Task Created with ID: %s", taskID)
// 轮询查询部分
fmt.Println("----- polling task status -----")
const maxAttempts = 60
for attempt := 1; attempt <= maxAttempts; attempt++ {
getReq := taskID
getResp, err := client.GetContentGenerationTask(ctx, getReq)
if err != nil {
fmt.Printf("get content generation task error: %v", err)
return
}
status := getResp.Status
if status == "succeeded" {
fmt.Println("----- task succeeded -----")
fmt.Printf("Task ID: %s", getResp.ID)
fmt.Printf("Model: %s", getResp.Model)
fmt.Printf("File URL: %s", getResp.Content.Or(model.TaskContent{}).FileURL.Or(""))
fmt.Printf("Completion Tokens: %d", getResp.Usage.Or(model.TaskUsage{}).CompletionTokens)
fmt.Printf("Created At: %d, Updated At: %d", getResp.CreatedAt.Or(0), getResp.UpdatedAt.Or(0))
return
} else if status == "failed" {
fmt.Println("----- task failed -----")
if getResp.Error.IsSet() {
fmt.Printf("Error Code: %s, Message: %s", getResp.Error.Value.Code, getResp.Error.Value.Message)
}
return
} else if attempt == maxAttempts {
fmt.Printf("Task %s did not finish after %d attempts", taskID, maxAttempts)
return
} else {
fmt.Printf("Current status: %s, retrying in 60 seconds...", status)
time.Sleep(60 * time.Second)
}
}
}
package com.volcengine.ark.runtime;
import com.volcengine.ark.runtime.models.content_generation.*;
import com.volcengine.ark.runtime.service.ArkService;
import okhttp3.ConnectionPool;
import okhttp3.Dispatcher;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.TimeUnit;
public class ContentGenerationTaskExample {
// 请确保您已将 API Key 存储在环境变量 ARK_API_KEY 中
// 初始化Ark客户端，从环境变量中读取您的API Key
static String apiKey = System.getenv("ARK_API_KEY");
static ConnectionPool connectionPool = new ConnectionPool(5, 1, TimeUnit.SECONDS);
static Dispatcher dispatcher = new Dispatcher();
static ArkService service = ArkService.builder()
.dispatcher(dispatcher)
.connectionPool(connectionPool)
.apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
// The base URL for model invocation .
.build();
public static void main(String[] args) {
//Replace with Model ID .
String model = "doubao-seed3d-2-0-260328";
System.out.println("----- CREATE Task Request -----");
List<ContentItem> contents = new ArrayList<>();
// 参数
contents.add(ContentItem.builder()
.type(ContentType.TEXT)
.text("--subdivisionlevel medium --fileformat glb")
.build());
// 图片URL
contents.add(ContentItem.builder()
.type(ContentType.IMAGE_URL)
.imageUrl(ImageURL.builder()
.url("https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/seed3d_imageTo3d.png")
.build())
.build());
// 创建3D生成任务
CreateContentGenerationTaskRequest createRequest = CreateContentGenerationTaskRequest.builder()
.model(model)
.content(contents)
.build();
CreateContentGenerationTaskResponse createResult = service.createContentGenerationTask(createRequest);
System.out.println(createResult);
System.out.println("----- GET Task Request -----");
// 获取任务详情
String getRequest = createResult.getId();
ContentGenerationTask getResult = service.getContentGenerationTask(getRequest);
System.out.println(getResult);
System.out.println("----- LIST Task Request -----");
// 轮询查询部分
System.out.println("----- polling task status -----");
final int maxAttempts = 60;
for (int attempt = 1; attempt <= maxAttempts; attempt++) {
try {
ContentGenerationTask getResponse = service.getContentGenerationTask(getRequest);
String status = getResponse.getStatus().toString();
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 if (attempt == maxAttempts) {
throw new IllegalStateException(
"Task " + getRequest + " did not finish after " + maxAttempts + " attempts");
} 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文件输出的规格，包括产物面的数量、输出文格式等。
# 指定生成的3D文件的多边形面的数量为 100000 面，生成的3D文件格式为 glb
"content": [
{
"type": "text",
"text": "--subdivisionlevel medium --fileformat glb"
}
]
链接有效期
任务数据（如任务状态、URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的文件。
限流说明
同一主账号下，使用同一模型（不区分版本）的请求受到以下限制。超过对应限制会返回 “429: 'Too Many Requests'” 错误。
模型维度的限流
- RPM（Requests Per Minute）：每分钟允许创建的 3D 生成任务数上限。超过上限时，创建任务请求将因触发限流而失败。
- 最大并发任务数：同一时刻可处于处理状态的任务数上限。达到上限后，新创建的任务将进入队列等待处理。
非推理 API 请求频率限制
- QPS（Queries Per Second）：每秒允许的请求数上限。超过上限时，任务请求将因触发限流而失败。
接口名称 | 账号维度的 QPS 上限 |
接口名称 | 账号维度的 QPS 上限 |
查询 3D 生成任务 | 20 |
查询 3D 生成任务列表 | 1 |
取消或删除 3D 生成任务 | 20 |
反馈生成效果问题
Seed3D 2.0 任务成功生成模型后，如果出现几何缺失、破面、贴图错位或与参考图不符等问题，可以使用任务 ID 上报效果问题。请准备问题描述和截图，并使用任务所属账号的方舟 API Key 调用接口。
最近更新时间：2026.10.28 16:13:28
这个页面对您有帮助吗？
有用
有用
无用
无用