# 查询 3D 生成任务 API

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id}`

查询 3D 生成任务的状态。

> **说明**
>
> 仅支持查询最近 7 天的历史数据。时间计算统一采用 UTC 时间戳，返回的 7 天历史数据范围以用户实际发起查询请求的时刻为基准（精确到秒），时间戳区间为 `[T-7 天, T)`。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### Path 参数

**id** `string` `必选` | 任务 ID

您需要查询的 3D 生成任务的 ID

## 响应参数

**id** `string` | 任务 ID

3D 生成任务 ID

**model** `string` | 模型名称与版本

任务使用的模型名称和版本，格式为 `模型名称-版本`

**status** `string` | 任务状态

任务状态，以及相关的信息：

* `queued`：排队中。
* `running`：任务运行中。
* `cancelled`：取消任务，取消状态 24h 自动删除（只支持 `queued` 状态的任务被取消）。
* `succeeded`：任务成功。
* `failed`：任务失败。

**content** `object` | 输出内容

3D 生成任务的输出内容

**file_url** `string` | 文件 URL

`content.file_url`

生成的 3D 文件的 URL。为保障信息安全，生成的 3D 文件会在 24 小时后被清理，请及时转存。

> **说明**
>
> * 模型会自动将生成的 3D 文件打包为 .zip 格式以供下载，压缩包内文件的格式与您创建任务时所指定的格式一致。
> * 推荐配置火山引擎 TOS 提供的数据订阅功能，将您的模型推理产物自动转存到自己的 TOS 桶中，便于长期备份或二次加工。详细介绍请参见 [TOS 数据订阅](https://docs.volcengine.com/docs/6349/2280949?lang=zh)。

**created_at** `integer` | 创建时间

任务创建时间的 Unix 时间戳（秒）

**error** `object` | 错误信息

错误提示信息。任务成功时返回 `null`，任务失败时返回错误数据，错误信息具体参见 [错误处理](https://ark.volcengine.com/region:cn-beijing/docs/error-codes)

**code** `string` | 错误码

`error.code`

**message** `string` | 错误提示信息

`error.message`

**fileformat** `string` | 文件格式

生成的 3D 文件格式。

**subdivisionlevel** `string` | 多边形面数

3D 文件中多边形面的数量。

**updated_at** `integer` | 更新时间

任务当前状态更新时间的 Unix 时间戳（秒）

**usage** `object` | token 用量

本次请求的 token 用量

**completion_tokens** `integer` | 生成 3D 内容消耗的 token 数

`usage.completion_tokens`

模型生成 3D 内容消耗的 token 数量，可作为计费对账依据。

**total_tokens** `integer` | 总 token 数

`usage.total_tokens`

本次请求消耗的总 token 数量。3D 生成模型不统计输入 token，输入 token 为 0，故 `total_tokens` = `completion_tokens`


## 代码示例

## 默认

### cURL


#### Request

```bash
TASK_ID="your_task_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"
```
#### Response

```
{
    "id"："cgt-2025******-****",
    "model":"doubao-seed3d-2-0-260328",
    "status":"succeeded",
    "created_at":"1718049470",
    "updated_at":"1718049470",
    "content":{
        "file_url":"https://xxx"，
     }，
    "subdivisionlevel": "medium",
    "fileformat": "glb",
    "usage":{
        "total_tokens":30000，
        "completion_tokens":30000，
    }
}
```

### Python


#### Request

```python
import os
from arkruntime import Ark


client = Ark(
    api_key=os.environ.get("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

if __name__ == "__main__":
    resp = client.content_generation.tasks.get(
        task_id="cgt-2025****",
    )
    print(resp)
```
#### Response

```
{
    "id"："cgt-2025******-****",
    "model":"doubao-seed3d-2-0-260328",
    "status":"succeeded",
    "created_at":"1718049470",
    "updated_at":"1718049470",
    "content":{
        "file_url":"https://xxx"，
     }，
    "subdivisionlevel": "medium",
    "fileformat": "glb",
    "usage":{
        "total_tokens":30000，
        "completion_tokens":30000，
    }
}
```

### Java


#### Request

```java
package com.volcengine.sample;

import com.volcengine.ark.runtime.models.content_generation.*;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.concurrent.TimeUnit;
import okhttp3.ConnectionPool;
import okhttp3.Dispatcher;


public class Sample {

    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")
                    .build();

    public static void main(String[] args) throws JsonProcessingException {
        String taskId = "cgt-2025****";

        String req = taskId;

        service.getContentGenerationTask(req).toString();
        System.out.println(service.getContentGenerationTask(req));

        service.shutdownExecutor();
    }
}
```

#### Response

```
{
    "id"："cgt-2025******-****",
    "model":"doubao-seed3d-2-0-260328",
    "status":"succeeded",
    "created_at":"1718049470",
    "updated_at":"1718049470",
    "content":{
        "file_url":"https://xxx"，
     }，
    "subdivisionlevel": "medium",
    "fileformat": "glb",
    "usage":{
        "total_tokens":30000，
        "completion_tokens":30000，
    }
}
```

### Go


#### Request

```go
package main

import (
        "context"
        "fmt"
        "os"

        "github.com/volcengine/ark-runtime-go/arkruntime"
)


func main() {
        client := arkruntime.NewClientWithApiKey(
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
    )
        ctx := context.Background()

        req := "cgt-2026****"
        resp, err := client.GetContentGenerationTask(ctx, req)
        if err != nil {
                fmt.Printf("get content generation task error: %v\n", err)
                return
        }
        fmt.Printf("%+v\n", resp)
}
```

#### Response

```
{
    "id"："cgt-2025******-****",
    "model":"doubao-seed3d-2-0-260328",
    "status":"succeeded",
    "created_at":"1718049470",
    "updated_at":"1718049470",
    "content":{
        "file_url":"https://xxx"，
     }，
    "subdivisionlevel": "medium",
    "fileformat": "glb",
    "usage":{
        "total_tokens":30000，
        "completion_tokens":30000，
    }
}
```