接口概述
功能：将商品图片与模特图片智能融合，生成手持商品的数字人视频/图片
典型应用场景：
 电商产品展示视频
 虚拟模特手拿产品宣传
 产品植入数字人生成
 短视频内容创作
 基础信息
 项目  说明 
 接口地址  /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开放平台