衣拍 AI API 文档 原型 · 示例

Base URL：https://api.yipai.example/v1（示例域名）。所有请求与响应均为 JSON。

认证

在请求头携带 API Key：

Authorization: Bearer yp_live_••••••••••••3f9a

POST/v1/videos

提交商品图与卖点，异步生成带货成片，立即返回视频 ID。

curl https://api.yipai.example/v1/videos \
  -H "Authorization: Bearer $YIPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "经典双排扣长款风衣（卡其）",
    "images": [
      "https://cdn.example.com/sku/1024/front.jpg",
      "https://cdn.example.com/sku/1024/detail.jpg"
    ],
    "selling_points": ["挺括斜纹面料", "收腰系带显高显瘦", "早秋通勤百搭"],
    "style": "gentle_commute",
    "voice": "female_intellectual",
    "music": "light_piano",
    "shots": 6,
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "cover_title": "秋天就靠这一件",
    "webhook_url": "https://shop.example.com/hooks/yipai"
  }'

响应 202 Accepted：

{
  "id": "vid_8Kq2mZ7xT1",
  "status": "queued",
  "estimated_seconds": 180,
  "created_at": "2026-09-29T08:30:12Z"
}

GET/v1/videos/{id}

查询进度、分镜与逐镜质检结果。

curl https://api.yipai.example/v1/videos/vid_8Kq2mZ7xT1 \
  -H "Authorization: Bearer $YIPAI_API_KEY"

{
  "id": "vid_8Kq2mZ7xT1",
  "status": "completed",            // queued | generating | qc | reshooting | completed | failed
  "progress": 100,
  "duration_s": 18.5,
  "video_url": "https://cdn.yipai.example/v/vid_8Kq2mZ7xT1_720.mp4",
  "cover_url": "https://cdn.yipai.example/v/vid_8Kq2mZ7xT1_cover.png",
  "shots": [
    {
      "index": 3,
      "desc": "特写：手抚过衣身，展示斜纹质感",
      "status": "passed",
      "attempts": 2,
      "qc": { "mouth_closed": true, "no_deformation": true,
              "hands": true, "garment_consistency": true }
    }
  ],
  "cost": { "units": 1, "amount_cny": 19.00 }
}

POST/v1/videos/{id}/revisions

用自然语言或结构化参数修改：重拍某镜、换音色、改标题。

{
  "instruction": "第3镜重拍，换成沉稳男声",
  "changes": [
    { "type": "reshoot", "shot": 3 },
    { "type": "voice", "value": "male_calm" }
  ]
}

HOOKWebhook

生成完成或失败时向 webhook_url 发送 POST，带 X-YiPai-Signature（HMAC-SHA256）签名头。

POST https://shop.example.com/hooks/yipai
X-YiPai-Signature: t=1790670000,v1=5b9c0e…
Content-Type: application/json

{
  "event": "video.completed",
  "data": {
    "id": "vid_8Kq2mZ7xT1",
    "status": "completed",
    "video_url": "https://cdn.yipai.example/v/vid_8Kq2mZ7xT1_720.mp4",
    "qc_summary": { "shots": 6, "passed_first_try": 5, "reshoots": 1 }
  }
}

// Node.js 校验签名示例
const crypto = require("crypto");
function verify(rawBody, header, secret) {
  const [t, v1] = header.split(",").map(s => s.split("=")[1]);
  const mac = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

错误码