影眸 API

查询3D生成任务列表

GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page_num={page_num}&page_size={page_size}&filter.status={filter.status}&filter.task_ids={filter.task_ids}&filter.model={filter.model}

当您要查询符合条件的任务，您可以传入条件筛选参数，返回符合要求的任务。

说明

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

快速入口

鉴权说明

体验中心

模型列表

模型计费

API Key

接口文档

常见问题

开通模型

请求参数

跳转响应参数

说明

该参数为 Path Parameter。您需要将待查询的 3D 生成任务的 ID，直接替换 URL 中的占位符。

page_num integer

返回结果的页码。数值大于 0。

page_size integer

返回结果的每页的结果数量。

取值范围：[1, 500]

filter object

过滤参数。

属性

filter. status string

过滤参数，查询某个任务状态。

queued：排队中的任务。

running：运行中任务。

cancelled：取消的任务，只能查询到 24h 内取消的任务。取消任务超出24h，会被删除。

succeeded：成功的任务。

failed：失败的任务。

filter. task_ids string[]

3D 生成任务 ID，精确搜索，支持同时搜索多个任务 ID。多个任务 ID 之间通过 &连接。

示例：同时搜索多个任务 ID

filter. model string

与返回参数不同，该字段为任务使用的推理接入点 ID，精确搜索。

响应参数

跳转请求参数

items object[]

查询到的 3D 生成任务列表。

属性

items. id string

3D 生成任务 ID 。

items. model string

任务实际使用的模型名称和版本，模型名称-版本。

items. status string

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

queued：排队中。

running：任务运行中。

cancelled：取消任务，取消状态24h自动删除（只支持排队中状态的任务被取消）。

succeeded：任务成功。

failed：任务失败。

items. error object

错误提示信息。任务失败时返回错误数据，具体参见错误处理。

属性

error. code string

错误码。

error. message string

错误提示信息。

items. created_at integer

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

items. updated_at integer

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

items. content object

3D 生成任务的输出内容。

属性

content. file_url string

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

说明

模型会自动将生成的 3D 文件打包为 .zip 格式以供下载，压缩包内文件的格式与您创建任务时所指定的格式一致。

推荐配置火山引擎 TOS 提供的数据订阅功能，将您的模型推理产物自动转存到自己的 TOS 桶中，便于长期备份或二次加工。详细介绍请参见 TOS 数据订阅。

items. usage object

本次请求的 token 用量。

属性

usage. completion_tokens integer

模型输出 3D 模型文件消耗的 token 数量。

usage. total_tokens integer

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

total integer

所有符合筛选条件的 item 数量。

默认

输入示例

curl -X GET "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page_num=2&filter.status=succeeded" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY"

输出示例

{
   "items": [
       {
          "id":"cgt-2026****-**",
          "model":"hyper3d-gen2-260112",
          "status":"succeeded",
          "content":{
            "file_url":"https://xxx",
          },
          "usage":{
               "completion_tokens":30000,
               "total_tokens":30000,
          } ,
          "created_at":1718049470,
          "updated_at":1718049470
        },
        {
          "id":"cgt-2026****-**",
          "model":"hyper3d-gen2-260112",
          "status":"succeeded",
          "content":{
            "file_url":"https://xxx",
          },
          "usage":{
               "completion_tokens":30000,
               "total_tokens":30000,
          },
          "created_at":1718049470,
          "updated_at":1718049470
        },
     ],
   "total":2
}

最近更新时间：2026.08.21 11:18:10

这个页面对您有帮助吗？

有用

无用

火山方舟