接口概述
功能：將商品圖片與模特圖片智能融合，生成手持商品的數(shù)字人視頻/圖片
典型應(yīng)用場景：
電商產(chǎn)品展示視頻
虛擬模特手拿產(chǎn)品宣傳
產(chǎn)品植入數(shù)字人生成
短視頻內(nèi)容創(chuàng)作
基礎(chǔ)信息
項目? 說明
接口地址? /api/aiimage/humanhand
返回格式? JSON
請求方式? GET 或 POST
請求示例? /api/ai/humanhand?key=你的密鑰
請求頭設(shè)置
http
ContentType: application/xwwwformurlencoded;charset=utf8;
請求參數(shù)說明
1. 必需參數(shù)（創(chuàng)建任務(wù)時）
參數(shù)名? 必填? 類型? 說明? 示例值
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>描述期望的姿勢/場景? 模特手捧產(chǎn)品面向鏡頭微笑
ratio? 是? string? 畫面比例<br>可選：16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3<br>默認(rèn)：16:9? 16:9
callbackUrl? 是? string? 回調(diào)地址<br>任務(wù)完成后，結(jié)果將POST到此URL? /callback
type? 是? string? 操作類型<br>create? 創(chuàng)建新任務(wù)? create
2. 查詢?nèi)蝿?wù)狀態(tài)時
參數(shù)名? 必填? 類型? 說明
key? 是? string? 接口密鑰
type? 是? string? 必須為 query
task_id? 是? string? 要查詢的任務(wù)ID
返回參數(shù)說明
通用返回字段
字段? 類型? 說明
code? int? 狀態(tài)碼（200表示成功）
msg? string? 狀態(tài)信息
data? object? 結(jié)果數(shù)據(jù)
exec_time? float? 接口處理耗時（秒）
ip? string? 客戶端IP地址
data字段詳情（當(dāng)type=create時）
json
{
? "task_id": "任務(wù)唯一ID",
? "status": "pending", // 狀態(tài): pending, processing, completed, failed
? "progress": "0%"? ? // 處理進(jìn)度
}
data字段詳情（當(dāng)type=query時）
json
{
? "url": "/video.mp4", // 結(jié)果文件下載地址
? "tips": "鏈接有效期為24小時，請盡快下載！",
? "task_id": "任務(wù)ID",
? "status": "completed", // 任務(wù)狀態(tài)
? "progress": "100%"? ? // 完成進(jìn)度
}
快速開始示例
1. 創(chuàng)建任務(wù)
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=模特手捧產(chǎn)品面向鏡頭微笑" \
? d "ratio=16:9" \
? d "callbackUrl=/callback" \
? d "type=create"
成功響應(yīng)示例：
json
{
? "code": 200,
? "msg": "success",
? "data": {
? ? "task_id": "d036cf967bcc60b9352e41a11f053018",
? ? "status": "pending",
? ? "progress": "0%"
? },
? "exec_time": 0.105,
? "ip": "117.188.13.123"
}
2. 查詢?nèi)蝿?wù)狀態(tài)
bash
使用上一步獲取的task_id
curl "/api/aiimage/humanhand?key=YOUR_API_KEY&type=query&task_id=d036cf967bcc60b9352e41a11f053018"
查詢成功響應(yīng)：
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"
}
最佳實(shí)踐建議
圖片準(zhǔn)備技巧
1. 商品圖片：
? ? 純白色背景效果最佳
? ? 產(chǎn)品主體清晰，邊緣分明
? ? 避免反光或陰影
2. 模特圖片：
? ? 正面或3/4側(cè)面
? ? 手部位置清晰可見
? ? 光線均勻，無強(qiáng)烈陰影
提示詞編寫技巧
推薦示例? 效果說明
模特手捧產(chǎn)品面向鏡頭微笑? 標(biāo)準(zhǔn)產(chǎn)品展示
模特盤腿坐地，鏡頭俯拍? 特定場景姿勢
模特站立，單手展示產(chǎn)品? 指定手持方式
模特在室內(nèi)場景，自然光下? 添加環(huán)境描述
注意事項
1. 文件大小：單張圖片不超過10MB
2. 鏈接有效期：生成的視頻鏈接24小時后失效
3. 異步處理：創(chuàng)建任務(wù)后需輪詢或等待回調(diào)
4. 格式支持：圖片建議使用PNG或高質(zhì)量JPG
5. 回調(diào)機(jī)制：務(wù)必提供有效的callbackUrl接收結(jié)果
錯誤處理
狀態(tài)碼? 含義? 處理建議
200? 成功? 正常處理
400? 參數(shù)錯誤? 檢查必填參數(shù)和格式
401? 密鑰無效? 檢查API密鑰是否正確
500? 服務(wù)器錯誤? 稍后重試或聯(lián)系技術(shù)支持
其他? 參考msg字段? 根據(jù)提示信息處理
來源：酷虎云api開放平臺
