查询数字人与外观

查询平台数字人、当前用户自建数字人或收藏，取得批量口播使用的 actor_id、声音和外观信息。

v1查询接口 Bearer 鉴权

POSThttps://popto.cn/api/open/v1/aiactor/list

鉴权与请求头

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

AuthorizationBearer <POPTO_API_KEY>必填

Content-Typeapplication/json必填

请求参数 Body · JSON

favouriteinteger可选

大于 0 时查询当前用户收藏，优先于 user_exclusive；默认 0。

user_exclusiveinteger可选

大于 0 时只查询本人自建角色；默认 0，查询平台角色。

querystring可选

角色名称关键词。

sort_bystring可选

平台角色排序字段。

genderstring[]可选

性别筛选： female（女性）、male（男性）。

数组元素可选值 femalemale

agestring[]可选

年龄筛选： senior（老年）、adult（成年）、young_adult（青年）、kid（儿童）。

数组元素可选值 senioradultyoung_adultkid

situationstring[]可选

适用场景筛选： bedroom（卧室）、kitchen（厨房）、living_room（客厅）、office（办公室）、studio（工作室）、coffee_shop（咖啡馆）、balcony（阳台）、beach（海滩）、snow（雪景）、street（街道）、car（车内）。

数组元素可选值 bedroomkitchenliving_roomofficestudiocoffee_shopbalconybeachsnowstreetcar

posestring[]可选

姿势筛选： standing（站立）、sitting（坐姿）、lying（躺卧）、walking（行走）、running（奔跑）、leaning（倚靠）、kneeling（跪姿）。

数组元素可选值 standingsittinglyingwalkingrunningleaningkneeling

shot_typestring[]可选

景别筛选： close_up（特写）、medium_close_up（中近景）、medium_shot（中景）、medium_full_shot（中全景）、full_shot（全景）。

数组元素可选值 close_upmedium_close_upmedium_shotmedium_full_shotfull_shot

skin_tonestring[]可选

肤色筛选： skin-001（肤色 1）、skin-002（肤色 2）、skin-003（肤色 3）、skin-004（肤色 4）、skin-005（肤色 5）、skin-006（肤色 6）。

数组元素可选值 skin-001skin-002skin-003skin-004skin-005skin-006

ethnicitystring[]可选

族裔筛选： caucasian（欧美）、black（黑色人种）、east_asian（东亚）、south_asian（南亚）、hispanic（拉美）、middle_eastern（中东）。

数组元素可选值 caucasianblackeast_asiansouth_asianhispanicmiddle_eastern

industrystring[]可选

行业筛选： e-commerce（电商）、beauty_&_skincare（美妆护肤）、health_&_fitness（健康健身）、food_&_beverage（餐饮食品）、tech_&_saas（科技/SaaS）、finance_&_insurance（金融保险）、education（教育）、real_estate（房地产）、travel_&_hospitality（旅游酒店）、fashion_&_apparel（时尚服饰）、automotive（汽车）、entertainment_&_media（娱乐传媒）。

数组元素可选值 e-commercebeauty_&_skincarehealth_&_fitnessfood_&_beveragetech_&_saasfinance_&_insuranceeducationreal_estatetravel_&_hospitalityfashion_&_apparelautomotiveentertainment_&_media

offsetinteger可选

分页偏移量，首次传 0；后续使用响应 offset。

limitinteger可选

本页数量；建议明确填写，如 20。

返回值与结构

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

infosobject[]

数字人列表。

查看数组元素字段 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

外观生成错误信息。

offsetinteger

下一页偏移量。

moreboolean

是否还有后续数据。

totalinteger

匹配总数，部分上游结果可能省略。

调用说明

自建或收藏列表按当前用户身份查询，不能通过请求体指定其他用户。人物属性筛选与 sort_by 作用于平台列表；自建列表按 query 查询，收藏列表在当前分页内按名称筛选。
使用真实 actor_id 和 looks[].look_id。列表中的自建角色可能未就绪，提交前确认声音可用；本接口不创建角色或克隆声音。

处理业务响应

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

请求示例Request

bash

curl --request POST \
  'https://popto.cn/api/open/v1/aiactor/list' \
  --header "Authorization: Bearer $POPTO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "",
  "offset": 0,
  "limit": 20,
  "favourite": 0,
  "user_exclusive": 0
}'

成功响应200 OK

json

{
  "ret": 0,
  "msg": "success",
  "data": {
    "ent": {
      "infos": [
        {
          "actor_id": "act_example",
          "name": "示例数字人",
          "voice_id": "voice_example",
          "status": "active",
          "looks": [
            {
              "look_id": "look_example",
              "name": "日常外观"
            }
          ]
        }
      ],
      "offset": 1,
      "more": false,
      "total": 1
    }
  }
}

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