likeadmin-api 全驱动数字人参数避坑：file_url、ref_file

最近在做一条数字人口播链路时，我遇到的第一个问题不是模型效果，而是请求参数没有对齐：图片 URL 和音频 URL 的字段名容易写反，mode又同时影响生成模式和计费档位，任务提交成功后还要把返回的任务 ID 保存下来。为了让这类接入更容易落地，本文用 LikeAdmin API 的image_human/submit接口拆一遍完整请求。

一、这个接口解决什么问题

LikeAdmin API 的全驱动数字人能力接收一张人物图片和一段参考音频，生成数字人视频。图片负责人物外观，音频负责口播内容和时长，提示词可以补充人物状态、镜头和动作要求。

它适合产品介绍、课程片段、客服播报和短视频批量生产等场景。接口采用异步任务模式，提交接口返回平台任务 ID，后续通过查询接口取得状态和结果。

二、先把必填参数分清楚

POST /api/v1/apps/image_human/submit的核心参数如下：

参数	必填	作用
`file_url`	是	输入人物图片 URL
`ref_file_url`	是	驱动数字人的音频 URL
`prompt`	否	对人物表达、镜头和动作的补充描述
`mode`	否	`fast` 或 `standard`，默认 `standard`
`duration`	否	音频时长，未传时平台可从音频地址探测

这里最容易出错的是file_url与ref_file_url。前者应该是图片，后者应该是音频。建议在业务代码里把变量命名成avatar_image_url和driving_audio_url，在组装 JSON 时再映射到接口字段，避免把两个 URL 直接混用。

三、请求示例

curl --request POST \ --url https://api.likeadmin.cn/api/v1/apps/image_human/submit \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "file_url": "https://example.com/avatar.png", "ref_file_url": "https://example.com/voice.wav", "mode": "standard", "prompt": "人物面对镜头自然说话，表情稳定，肢体动作适度" }'

请求地址使用 LikeAdmin API 的开放 API 前缀/api/v1。API Key 只放在服务端，示例中的YOUR_API_KEY、图片地址和音频地址都需要替换为自己的占位值或配置项，不能写入前端代码。

四、mode 和成本怎么理解

资料库中给出的image_human价格摘要是快速模式 2 点/次、标准模式 3 点/次。实际使用时仍应以账户当前价格页和当前租户 SKU 为准。

接入初期建议先用fast做参数验证，确认图片、音频和业务流程都能跑通，再切换到standard进行效果测试。不要把模式选择写死在多个业务分支中，可以统一放在配置文件里：

const payload = { file_url: avatarImageUrl, ref_file_url: drivingAudioUrl, mode: process.env.LIKEADMIN_IMAGE_HUMAN_MODE || "standard", prompt: prompt || undefined };

如果任务按音频时长计费，建议在提交前记录音频时长、模式和业务订单号，提交后再把平台返回的task_id与这三项一起保存。这样出现重试或对账问题时，能知道一次任务到底用了哪组参数。

五、查询任务不能省略

查询接口为POST /api/v1/apps/image_human/query，参数只有一个必填字段task_id：

curl --request POST \ --url https://api.likeadmin.cn/api/v1/apps/image_human/query \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{"task_id":"YOUR_TASK_ID"}'

生产环境可以采用两种方式：有稳定公网服务时传入回调地址并由业务系统接收完成通知；没有回调服务时，按间隔轮询查询接口。无论采用哪种方式，都要把task_id当作幂等键，避免重复提交同一份输入。