火山方舟
火山方舟
文档指南
请输入
调用
视频生成
工具调用
进阶使用
使用 Responses API
- 火山方舟
调用领域模型3D 生成
复制全文
下载 pdf领域模型
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: pip install 'volcengine-python-sdk[ark]' .
from volcenginesdkarkruntime 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://console.volcengine.com/ark/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://ark-project.tos-cn-beijing.volces.com/doc_image/seed3d_imageTo3d.png"
}
}
]
)
print(create_result)
# 轮询查询部分
print("----- polling task status -----")
task_id = create_result.id
while True:
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
else:
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://ark-project.tos-cn-beijing.volces.com/doc_image/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/volcengine-go-sdk/service/arkruntime"
"github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
"github.com/volcengine/volcengine-go-sdk/volcengine"
)
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.CreateContentGenerationContentItem{
{
Type: model.ContentGenerationContentItemTypeText,
Text: volcengine.String("--subdivisionlevel medium --fileformat glb"),
},
{
Type: model.ContentGenerationContentItemTypeImage,
ImageURL: &model.ImageURL{
URL: "https://ark-project.tos-cn-beijing.volces.com/doc_image/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 -----")
for {
getReq := model.GetContentGenerationTaskRequest{ID: 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("Video URL: %s", getResp.Content.VideoURL)
fmt.Printf("Completion Tokens: %d", getResp.Usage.CompletionTokens)
fmt.Printf("Created At: %d, Updated At: %d", getResp.CreatedAt, getResp.UpdatedAt)
return
} else if status == "failed" {
fmt.Println("----- task failed -----")
if getResp.Error != nil {
fmt.Printf("Error Code: %s, Message: %s", getResp.Error.Code, getResp.Error.Message)
}
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.model.content.generation.DeleteContentGenerationTaskResponse;
import com.volcengine.ark.runtime.model.content.generation.*;
import com.volcengine.ark.runtime.model.content.generation.CreateContentGenerationTaskRequest.Content;
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<Content> 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文件输出的规格，包括产物面的数量、输出文格式等。
# 指定生成的3D文件的多边形面的数量为 100000 面，生成的3D文件格式为 glb
"content": [
{
"type": "text",
"text": "--subdivisionlevel medium --fileformat glb"
}
]
链接有效期
任务数据（如任务状态、URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的文件。
模型限流
- RPM 限流：账号下同模型（区分模型版本）每分钟允许创建的任务数量上限。若超过该限制，创建3D生成任务时会报错。
- 并发数限制：账号下同模型（区分模型版本）同一时刻在处理中的任务数量上限。超过此限制的任务将进入队列等待处理。
- 不同模型的限制值不同，详见3D生成能力。
最近更新时间：2026.08.21 11:18:07
这个页面对您有帮助吗？
有用
有用
无用
无用