# 创建 3D 生成任务 API > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 `POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks` 本文介绍创建 3D 生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片信息生成 3D，待生成完成后，您可以按条件查询任务并获取生成的 3D 文件。 **模型能力** * **doubao-seed3d** * `doubao-seed3d-2-0-260328`：图生 3D，根据您输入图片（1 张）+ 参数（可选）生成一个带纹理和 PBR 材质的 3D 文件。 **参数传入方式说明** > **说明** > > `subdivisionlevel` 和 `fileformat` 参数支持在文本提示词后追加 `--[parameters]` 的弱校验方式传入。若参数填写错误，该参数将被忽略。 **弱校验方式：在文本提示词后追加参数** ```JSON { "model": "doubao-seed3d-2-0-260328", "content": [ { "type": "text", "text": "--subdivisionlevel medium --fileformat obj" }, { "type": "image_url", "image_url": { "url": "" } } ] } ``` ## 鉴权 本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。 * API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。 --- ## 请求参数 ### Body 参数 **model** `string` `必选` | 模型 ID 您需要调用的模型的 ID（Model ID）。[开通模型服务](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false) 后可 [查询 Model ID](/docs/model-list)。 您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费 / 后付费）、运行状态查询、监控、安全等高级能力，可参考 [获取 Endpoint ID](https://ark.volcengine.com/region:cn-beijing/docs/create-standard-inference-endpoint)。 **content** `object[]` `必选` | 输入内容列表 输入给模型生成 3D 内容的信息，支持文本、图片等类型的元素。 支持以下几种组合： * 纯文本 * 文本（可选）+ 图片 文本信息 `object` 文本部分，作为生成内容的文本提示词。 **text** `string` `必选` | 文本提示词 `content.text` 输入给模型的文本提示词，描述期望生成的 3D 内容。 **type** `string` `必选` | 内容类型 `content.type` 输入内容的类型，此处固定为 `text`。 图片信息 `object` 输入给模型的图片信息。 **image_url** `object` `必选` | 图片对象 `content.image_url` 输入给模型的图片对象。 **url** `string` `必选` | 图片来源 `content.image_url.url` 图片 URL、图片 Base64 编码。 * **图片 URL**：填入图片的公网 URL。 * **Base64 编码**：将本地文件转换为 Base64 编码字符串后提交给大模型，遵循格式 `data:image/<图片格式>;base64,`，注意 `<图片格式>` 需小写，如 `data:image/png;base64,{base64_image}`。 > **说明：传入单张图片要求** > > * **格式**：`jpeg`、`png`、`webp`、`bmp`、`tiff`、`gif` > * **宽高比（宽/高）**：`[0.4, 2.5]` > * **宽高长度（px）**：`[300, 6000]` > * **大小**：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用 Base64 编码。 > * **图片数量**：1 张 **type** `string` `必选` | 内容类型 `content.type` 输入内容的类型，此处固定为 `image_url`。 **file_format** `string` `默认值 glb` | 输出文件格式 生成的 3D 文件格式。可选值：`glb`、`obj`、`usd`、`usdz`。 **subdivision_level** `string` `默认值 medium` | 多边形面数 3D 文件中多边形面的数量。可选值： * `high`：1000000 * `medium`：500000 * `low`：100000。 ## 响应参数 **id** `string` | 任务 ID 3D 生成任务 ID。仅保存 7 天（从 `created_at` 时间戳开始计算），超时后将自动清除。 创建 3D 生成任务为**异步接口**，获取 ID 后需要通过 [查询 3D 生成任务 API](/docs/get-3d-generation-task-api) 来查询任务状态。任务成功后会输出生成 3D 内容的 `file_url`。 ## 代码示例 ## 图生3D ### cURL #### Request ```bash 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" } } ] }' ``` #### Response ``` { "id": "cgt-2025******-****" } ``` ### Python #### Request ```python import os # 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) ``` #### Response ``` { "id": "cgt-2025******-****" } ``` ### Java #### Request ```java 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 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); service.shutdownExecutor(); } } ``` #### Response ``` { "id": "cgt-2025******-****" } ``` ### Go #### Request ```go package main import ( "context" "fmt" "os" "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 content generation task -----") // 创建3D生成任务 createReq := &model.CreateContentGenerationTaskRequest{ Model: modelEp, Content: []model.ContentItem{ { // 参数 Type: model.ContentTypeText, Text: model.NewOptString("--subdivisionlevel medium --fileformat glb"), }, { // 图片URL Type: model.ContentTypeImageURL, ImageURL: model.NewOptImageURL(model.ImageURL{ URL: "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/seed3d_imageTo3d.png", }), }, }, } createResponse, err := client.CreateContentGenerationTask(ctx, createReq) if err != nil { fmt.Printf("create content generation error: %v", err) return } fmt.Printf("Task Created with ID: %s", createResponse.ID) } ``` #### Response ``` { "id": "cgt-2025******-****" } ```