数字人接口接入后，很多项目会卡在"请求已经返回了，视频在哪里"这一步。LikeAdmin API 的全驱动数字人接口采用异步任务模型，提交接口返回任务 ID，生成结果需要通过查询接口获取。本文只讨论任务状态处理，不重复介绍素材生成效果，重点放在可重试、可追踪和不重复扣费的工程实现上。
一、提交接口和查询接口是两个动作
提交任务使用：
POST /api/v1/apps/image_human/submit查询任务使用：
POST /api/v1/apps/image_human/query查询接口的必填参数是平台返回的 task_id，查询本身按资料库记录不重复计费。也就是说，业务系统可以把查询设计成独立的状态机，而不是把生成请求一直阻塞到视频返回。
二、推荐的数据表字段
实际项目中，我建议至少保存以下字段：
| 字段 | 用途 |
| --- | --- |
| `biz_id` | 自己系统的订单或内容 ID |
| `task_id` | LikeAdmin API 返回的平台任务 ID |
| `status` | 本地状态，例如 submitted、processing、completed、failed |
| `request_hash` | 图片、音频、模式等输入的摘要，用于幂等判断 |
| `result_url` | 任务完成后的结果地址 |
| `error_message` | 失败时保留平台错误信息 |
| `last_polled_at` | 最近一次查询时间 |不要只保存一个 task_id 字符串。没有业务 ID 和请求摘要时，用户重复点击提交、网络超时重试和后台补偿都可能生成重复任务，后续很难判断哪一个结果属于哪一笔业务。
三、查询请求示例
async function queryImageHuman(taskId) {
const response = await fetch(
"https://api.likeadmin.cn/api/v1/apps/image_human/query",
{
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({ task_id: taskId })
}
);if (!response.ok) {
throw new Error(query failed: ${response.status});
}
return response.json();
}
```
示例只展示调用结构，不写入真实密钥。生产代码还应设置超时、记录响应摘要，并对 HTTP 错误和业务错误分别处理。
四、用状态机控制轮询
可以把平台返回结果归一为四类：
- `submitted`：已经拿到任务 ID，等待第一次查询。
- `processing`：平台仍在排队或生成，按退避间隔继续查询。
- `completed`：结果地址可用，写入 `result_url`，通知前端或下游流程。
- `failed`：保存错误信息，根据错误类型决定是否重新提交。
伪代码如下：
async function pollUntilDone(task) {
let delayMs = 5000;for (let attempt = 0; attempt < 30; attempt += 1) {
const result = await queryImageHuman(task.task_id);
const status = normalizeStatus(result);
if (status === "completed") {
return { status, resultUrl: extractResultUrl(result) };
}
if (status === "failed") {
throw new Error(extractError(result));
}
await sleep(delayMs);
delayMs = Math.min(Math.round(delayMs * 1.5), 60000);
}
return { status: "timeout", taskId: task.task_id };
}
```
normalizeStatus 和 extractResultUrl 应按当前接口真实响应字段实现，不能直接假设所有应用都返回同一层级。LikeAdmin API 的通用任务接口也提供 GET /api/v1/tasks/{task_id}，但应用专用 query 的响应应优先以对应开发者文档为准。
五、超时和重试怎么做
客户端超时不等于平台任务失败。提交请求如果在网络层超时，第一步应根据业务请求摘要查询是否已经写入任务记录；只有确认没有成功创建，才允许重新提交。
查询超时则可以把任务标记为 unknown，由后台补偿任务继续检查，不要立刻当成失败。真正失败时，建议按以下顺序判断：
- 素材地址不可访问：修复 URL 后重新提交。
- 参数校验失败：修正字段后重新提交，不能原样重试。
- 平台暂时性错误：使用有限次数和递增间隔重试。
- 余额、权限或能力未开放：停止自动重试，提示运营处理。
六、生产接入的几个细节
- API Key 放在服务端环境变量中，前端只拿业务系统的任务 ID。
- 轮询任务要设置最大次数和最大时长，避免异常任务无限占用队列。
- 完成后的结果地址建议复制到自己的对象存储或媒体服务，再给前端使用，具体做法取决于结果 URL 的有效期。
- 记录请求参数的非敏感摘要，方便复现问题，但不要把密钥写入日志。
- 接口开放状态、计费和返回字段可能调整，发布前应重新核对 LikeAdmin API 当前文档。
七、总结
image_human/query 的价值不只是"查结果"，而是把异步生成接入成可恢复的业务流程。保存 task_id、建立状态机、区分超时和失败，再配合幂等键，才能把一次数字人演示变成稳定的生产能力。
本文封面使用 LikeAdmin API 的 image_human/query 真实接口截图，发布流程会把它上传到 CSDN 的封面字段后再提交文章。