批量生成口播音频

将口播文案与数字人组合为一个异步音频任务，返回项目和任务 ID；完成后读取音频地址与时长。

v1异步任务 Bearer 鉴权

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

鉴权与请求头

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

AuthorizationBearer <POPTO_API_KEY>必填

Content-Typeapplication/json必填

请求参数 Body · JSON

tool_idstring可选

首次提交可省略或留空，自动创建工具箱项目；后续音频和视频提交复用同一 tool_id，项目须属于当前用户。

selected_aiactor_voiceoversobject[]必填

非空文案数组；与数字人数组做笛卡尔组合。

查看数组元素字段 6

topicstring可选

口播主题。

anglestring可选

内容角度。

draftstring必填

不能为空的口播正文。

expression_stylestring可选

表达风格。

source_idstring可选

可选的文案来源 ID。

versioninteger可选

可选的文案版本。

selected_aiactorsobject[]必填

非空数字人数组。

查看数组元素字段 3

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可选

外观生成错误信息。

with_subtitleboolean可选

默认 false。true 时为音频额外生成字幕时间线，不会直接生成视频。

selected_look_idsstring[]可选

选定外观 ID，仅保留为输入配置；音频仍按角色与文案组合生成。

say_paramsobject可选

展开查看对象字段。

查看子字段 6

auto_emotionboolean可选

是否自动表达情感；完全省略语音参数时默认 true。

speednumber可选

语速；省略或为 0 时使用服务端默认值 1.0。

stabilitynumber可选

声音稳定度；省略或为 0 时默认 0.5。

similaritynumber可选

声音相似度；省略或为 0 时默认 0.75。

stylenumber可选

风格强度，默认 0。

speaker_boostboolean可选

是否增强说话人特征，默认 false。

candidate_tagsstring[]可选

兼容的候选标签配置。

返回值与结构

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

tool_idstring

工具箱项目 ID，同时用作项目 ID 与任务 source_id。

task_idstring

异步任务 ID。

调用说明

M 段文案与 N 个数字人生成 M×N 条音频。每个数字人说不同文案时，每次只提交一段文案和一个数字人，首次取得 tool_id 后让后续请求复用它。
task/batch_get 或 toolbox/get_info 查询 task_type=aiactor_batch_say；成功时 outputs.items[] 包含 aiactor、voiceover、script、with_subtitle、audio_url、duration，以及可选 analysis。按 actor_id 与 script 匹配音频。
此接口的文案是直接数组，不接受执行器内部兼容的 {items:[...]} 包装。开放接口校验 draft 非空；网页端另外要求至少 20 个非空白字符，最多 5000 个 UTF-16 字符。
接口使用 Bearer API Key 识别当前注册用户，生成服务身份由服务端加载，不需要也不能通过请求体覆盖 uid、owner 或 h_m。
提交接口没有幂等保证；网络超时、5xx 或不完整回执时可能已经创建任务。先用已保存的 tool_id、task_id 或项目中心核对，不要自动重放生成请求。

处理业务响应

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

请求示例Request

bash

curl --request POST \
  'https://popto.cn/api/open/v1/toolbox/batch_say' \
  --header "Authorization: Bearer $POPTO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "selected_aiactor_voiceovers": [
    {
      "topic": "产品介绍",
      "draft": "大家好，今天为大家介绍如何把一段口播文案快速制作成数字人视频。"
    }
  ],
  "selected_aiactors": [
    {
      "aiactor": {
        "actor_id": "act_example",
        "name": "示例数字人"
      },
      "with_subtitle": false
    }
  ],
  "say_params": {
    "auto_emotion": true,
    "speed": 1.1,
    "stability": 0.5,
    "similarity": 0.75,
    "style": 0,
    "speaker_boost": false
  }
}'

成功响应200 OK

json

{
  "ret": 0,
  "msg": "success",
  "data": {
    "ent": {
      "tool_id": "tool_example",
      "task_id": "task_audio_example"
    }
  }
}

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