查询口播项目任务

按工具箱项目 tool_id 查询当前用户的关联任务，查看口播音频和视频的状态、原始输入与生成结果。

v1查询接口 Bearer 鉴权

POSThttps://popto.cn/api/open/v1/toolbox/get_info

鉴权与请求头

在 API 密钥管理 ↗ 创建密钥，每次请求在 HTTP Header 中携带。

AuthorizationBearer <POPTO_API_KEY>必填

Content-Typeapplication/json必填

请求参数 Body · JSON

tool_idstring必填

工具箱项目 ID，同时是关联任务的 source_id。

返回值与结构

成功时 ret = 0，业务数据位于 data.ent。以下为 data.ent 中的字段。

tool_idstring

查询的工具箱项目 ID。

listobject[]

当前用户拥有的项目任务，按记录 ID 倒序，最多 50 条。

查看数组元素字段 19

idinteger

任务记录 ID。

task_idstring

任务 ID。

task_typestring

任务类型。

task_scenestring

任务场景。

source_idstring

关联的工具或工作流 ID。

statusstring

任务状态。

可选值 pendingrunningsuccessfailedcancelled

priorityinteger

任务优先级，数字越小优先级越高。

timeout_secondsinteger

任务超时时间，秒。

ownerstring

任务所属用户标识；只能查询当前用户的任务。

project_idstring

关联项目 ID。

inputsJSON

任务输入，JSON 对象、数组或 null。

outputsobject

任务成功时的口播结果；音频与视频返回不同字段，不能把提交回执当作生成结果。

查看子字段 2

itemsobject[]

按 task_type 读取：aiactor_batch_say 返回 aiactor、script、audio_url 等；aiactor_perform_render_avatar 返回 workspace_id、output_video_url 等。

查看数组元素字段 11

aiactorobject

数字人对象，可直接保留列表返回的完整对象。提交时至少包含 actor_id。

查看子字段 35

actor_idstring

从数字人列表取得的真实角色 ID，不能为空。

namestring

数字人名称，建议保留以便项目展示。

idinteger

角色记录 ID。

ctinteger

创建时间，Unix 秒。

utinteger

更新时间，Unix 秒。

hired_bystring

角色租用信息。

hired_atinteger

角色租用时间。

agestring

年龄分类。

genderstring

性别。

situationstring[]

适用场景。

posestring

姿势。

shot_typestring

景别。

skin_tonestring

肤色。

accessoriesJSON

配饰信息，JSON 值。

voice_idstring

声音 ID；使用角色已配置的声音。

special_forJSON

角色适用信息，JSON 值。

preview_urlstring

预览地址。

photo_urlstring

角色照片地址。

original_show_off_urlstring

原始展示视频地址。

show_off_urlstring

展示视频地址。

lightstring

光照描述。

audition_audio_urlstring

声音试听地址。

scoreinteger

角色评分。

favouriteboolean

当前用户是否收藏。

statusstring

角色状态；自建角色可能仍在生成中。

voicesJSON

角色声音信息，JSON 值。

voice_vendorstring

声音服务商。

voice_account_idinteger

声音账号标识。

ethnicitystring

族裔。

posesstring[]

姿势标签。

shot_typesstring[]

景别标签。

industriesstring[]

行业标签。

subregionstring

地区。

professionsstring[]

职业标签。

looksobject[]

可选外观；使用其中的 look_id，不要根据名称猜测 ID。

查看数组元素字段 10

look_idstring

外观 ID。

namestring

外观名称。

background_image_urlstring

背景图地址。

clothes_image_urlstring

服装图地址。

result_image_urlstring

外观结果图地址。

promptstring

外观描述。

statusinteger

外观状态码。

ctinteger

创建时间，Unix 秒。

preview_urlstring

外观预览图片或视频地址。

error_msgstring

外观生成错误信息。

voiceoverobject

展开查看对象字段。

查看子字段 6

topicstring

口播主题。

anglestring

内容角度。

draftstring

口播正文，使用时须为非空文本。

expression_stylestring

表达风格。

source_idstring

可选的文案来源 ID。

versioninteger

可选的文案版本。

scriptstring

音频对应的口播正文。

with_subtitleboolean

是否包含字幕或字幕时间线。

audio_urlstring

音频任务的可播放音频 URL。

durationinteger

音频时长，秒。

analysisJSON

按需生成的时间线或分析数据。

workspace_idstring

视频合成工作区 ID。

workspaceobject

视频合成工作区信息。

output_video_urlstring

视频任务的最终成片 URL。

output_mime_typestring

成片 MIME 类型。

workspace_idsstring[]

仅视频任务返回的工作区 ID 数组。

error_msgJSON

任务错误详情，JSON 值或 null。

retry_countinteger

已重试次数。

max_retryinteger

最大重试次数。

start_timeinteger

开始时间，Unix 秒。

finish_timeinteger

结束时间，Unix 秒。

ctinteger

创建时间，Unix 秒。

utinteger

更新时间，Unix 秒。

调用说明

只返回当前 API Key 用户的任务；未知项目或无可见任务时 list 为空，不代表全部任务成功。接口不返回 scene 字段，任务场景位于 list[].task_scene。
超过 50 条、需要完整跟踪或已保存全部任务 ID 时，使用 task/batch_get 按最多 50 个 ID 分组查询，不能用项目列表的最近 50 条推断整批完成。
HTTP 200 和 ret=0 仅表示查询成功。等待每条任务 status=success 且输出实际音频或视频 URL 后再报告生成完成；failed、cancelled 为终态，读取 error_msg。

处理业务响应

HTTP 200 仍可能返回业务错误，请同时检查 ret、code 和 msg。查看响应与错误码

请求示例Request

bash

curl --request POST \
  'https://popto.cn/api/open/v1/toolbox/get_info' \
  --header "Authorization: Bearer $POPTO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "tool_id": "tool_example"
}'

成功响应200 OK

json

{
  "ret": 0,
  "msg": "success",
  "data": {
    "ent": {
      "tool_id": "tool_example",
      "list": [
        {
          "task_id": "task_video_example",
          "task_type": "aiactor_perform_render_avatar",
          "task_scene": "toolbox_batch_say_render_avatar",
          "source_id": "tool_example",
          "status": "success",
          "inputs": {
            "render_item": {
              "aiactor": {
                "actor_id": "act_example",
                "name": "示例数字人"
              },
              "script": "大家好，今天为大家介绍如何把一段口播文案快速制作成数字人视频。",
              "with_subtitle": true
            }
          },
          "outputs": {
            "workspace_ids": [
              "workspace_example"
            ],
            "items": [
              {
                "workspace_id": "workspace_example",
                "with_subtitle": true,
                "output_video_url": "https://cdn.example.com/talking-video.mp4",
                "output_mime_type": "video/mp4"
              }
            ]
          },
          "error_msg": null
        },
        {
          "task_id": "task_audio_example",
          "task_type": "aiactor_batch_say",
          "source_id": "tool_example",
          "status": "success",
          "outputs": {
            "items": [
              {
                "aiactor": {
                  "actor_id": "act_example",
                  "name": "示例数字人"
                },
                "script": "大家好，今天为大家介绍如何把一段口播文案快速制作成数字人视频。",
                "voiceover": {
                  "draft": "大家好，今天为大家介绍如何把一段口播文案快速制作成数字人视频。"
                },
                "audio_url": "https://cdn.example.com/talking-audio.mp3",
                "duration": 6,
                "with_subtitle": false
              }
            ]
          },
          "error_msg": null
        }
      ]
    }
  }
}

示例内容用于说明结构。任务 ID、积分和执行结果以实际响应为准。