接口概述
功能：将商品图片与模特图片智能融合，生成手持商品的数字人视频/图片
典型应用场景：
电商产品展示视频
虚拟模特手拿产品宣传
产品植入数字人生成
短视频内容创作
基础信息
项目 说明
接口地址 /api/aiimage/humanhand
返回格式 JSON
请求方式 GET 或 POST
请求示例 /api/ai/humanhand?key=你的密钥
请求头设置
http
ContentType: application/xwwwformurlencoded;charset=utf8;
请求参数说明
1. 必需参数（创建任务时）
参数名 必填 类型 说明 示例值
key 是 string 接口密钥，在平台控制台获取 35kj5jnlj53453kl5j43nj5
prdImageUrl 是 string 商品图片URL<br>• 白色背景为佳<br>• 文件≤10MB<br>• 支持png/jpg格式 /product.png
modelImageUrl 是 string 模特图片URL<br>• 人物清晰，正面为佳<br>• 文件≤10MB<br>• 支持png/jpg格式 /model.jpg
prompt 是 string AI提示词<br>描述期望的姿势/场景 模特手捧产品面向镜头微笑
ratio 是 string 画面比例<br>可选：16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3<br>默认：16:9 16:9
callbackUrl 是 string 回调地址<br>任务完成后，结果将POST到此URL /callback
type 是 string 操作类型<br>create 创建新任务 create
2. 查询任务状态时
参数名 必填 类型 说明
key 是 string 接口密钥
type 是 string 必须为 query
task_id 是 string 要查询的任务ID
返回参数说明
通用返回字段
字段 类型 说明
code int 状态码（200表示成功）
msg string 状态信息
data object 结果数据
exec_time float 接口处理耗时（秒）
ip string 客户端IP地址
data字段详情（当type=create时）
json
{
"task_id": "任务唯一ID",
"status": "pending", // 状态: pending, processing, completed, failed
"progress": "0%" // 处理进度
}
data字段详情（当type=query时）
json
{
"url": "/video.mp4", // 结果文件下载地址
"tips": "链接有效期为24小时，请尽快下载！",
"task_id": "任务ID",
"status": "completed", // 任务状态
"progress": "100%" // 完成进度
}
快速开始示例
1. 创建任务
bash
使用curl示例
curl X POST "/api/aiimage/humanhand" \
H "ContentType: application/xwwwformurlencoded" \
d "key=YOUR_API_KEY" \
d "prdImageUrl=/product.jpg" \
d "modelImageUrl=/model.jpg" \
d "prompt=模特手捧产品面向镜头微笑" \
d "ratio=16:9" \
d "callbackUrl=/callback" \
d "type=create"
成功响应示例：
json
{
"code": 200,
"msg": "success",
"data": {
"task_id": "d036cf967bcc60b9352e41a11f053018",
"status": "pending",
"progress": "0%"
},
"exec_time": 0.105,
"ip": "117.188.13.123"
}
2. 查询任务状态
bash
使用上一步获取的task_id
curl "/api/aiimage/humanhand?key=YOUR_API_KEY&type=query&task_id=d036cf967bcc60b9352e41a11f053018"
查询成功响应：
json
{
"code": 200,
"msg": "success",
"data": {
"url": "/result.mp4",
"tips": "链接有效期为24小时，请尽快下载！",
"task_id": "d036cf967bcc60b9352e41a11f053018",
"status": "completed",
"progress": "100%"
},
"exec_time": 0.108,
"ip": "117.188.13.123"
}
最佳实践建议
图片准备技巧
1. 商品图片：
纯白色背景效果最佳
产品主体清晰，边缘分明
避免反光或阴影
2. 模特图片：
正面或3/4侧面
手部位置清晰可见
光线均匀，无强烈阴影
提示词编写技巧
推荐示例 效果说明
模特手捧产品面向镜头微笑 标准产品展示
模特盘腿坐地，镜头俯拍 特定场景姿势
模特站立，单手展示产品 指定手持方式
模特在室内场景，自然光下 添加环境描述
注意事项
1. 文件大小：单张图片不超过10MB
2. 链接有效期：生成的视频链接24小时后失效
3. 异步处理：创建任务后需轮询或等待回调
4. 格式支持：图片建议使用PNG或高质量JPG
5. 回调机制：务必提供有效的callbackUrl接收结果
错误处理
状态码 含义 处理建议
200 成功 正常处理
400 参数错误 检查必填参数和格式
401 密钥无效 检查API密钥是否正确
500 服务器错误 稍后重试或联系技术支持
其他 参考msg字段 根据提示信息处理
来源：酷虎云api开放平台
