likeadmin-api 全驱动数字人参数避坑：file_url、ref_file_url 和 mode 怎么传
最近在做一条数字人口播链路时，我遇到的第一个问题不是模型效果，而是请求参数没有对齐：图片 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当作幂等键，避免重复提交同一份输入。
六、素材和异常处理
- 图片和音频必须是平台能够访问的公网地址。内网地址、临时失效地址和需要登录才能访问的地址，都会导致上游无法拉取素材。
- 图片尽量使用主体清晰、脸部无遮挡的素材，音频尽量避免过强噪声和过长静音段。
- 提交成功不等于生成成功。业务状态应至少区分提交成功、处理中、完成和失败，并在失败时保存原始错误信息。
- 重试前先查询原任务，只有确认任务失败或超时，才重新创建任务。不要因为客户端请求超时就立即重复扣费提交。
- 价格、开放范围和当前模式以 LikeAdmin API 当前页面为准，资料库只作为本文写作时的接口参考。
七、总结
全驱动数字人的接入重点可以归纳为三点：图片和音频字段不要混淆，模式和计费要可追踪，提交后的任务查询要做成完整闭环。LikeAdmin API 将应用编码、鉴权、任务 ID 和查询接口统一起来，适合把一次效果验证继续扩展成批量口播服务。
封面使用本次接口资料库中的image_human参数截图，发布时会作为 CSDN 封面上传，不依赖本地相对路径。