鸿爪派·Agnes图像视频生成

概述

Agnes AI 图像与视频生成

通过 Agnes AI 统一 API 网关（OpenAI 兼容），一键生成图片或视频。覆盖文生图、图生图、文生视频、图生视频全场景。

API 凭证

若环境未设置 AGNES_API_KEY，向用户索取后在脚本 --api-key 参数中传入。

模型速查

限流约束

Phase 1：确定生成模式

根据用户需求判断走哪条路径：

关键参数确认：

• 图像：尺寸（默认 1024x1024，横版用 1536x864，竖版用 864x1536）
• 视频：分辨率（480p/720p/1080p）+ 比例（16:9/9:16/1:1/4:3/3:4）+ 时长（帧数 num_frames，须 8n+1，如 121≈5s@24fps）

Phase 2：生成图片

文生图

python3 scripts/generate_image.py 
  --prompt "A serene mountain landscape at golden hour, cinematic" 
  --size 1024x1024 
  --output-dir ./output

图生图（图像编辑）

python3 scripts/generate_image.py 
  --mode img2img 
  --prompt "Change the sky to a dramatic sunset" 
  --image "https://example.com/photo.jpg" 
  --output-dir ./output

参数说明

Prompt 编写要点

• 用英文：中文 prompt 可用但英文效果更好，建议先翻译
• 描述具体：主体 + 场景 + 光线 + 风格 + 构图（如 "flat illustration, soft pastel colors, no text"）
• 指定无文字：加 "no text, no words, no letters" 防止乱码
• 比例匹配：横幅图务必加 "wide banner composition, landscape format"

Phase 3：生成视频

文生视频

python3 scripts/generate_video.py 
  --prompt "A cat walking on the beach at sunset, cinematic" 
  --resolution 720p 
  --ratio 16:9 
  --output-dir ./output

图生视频

python3 scripts/generate_video.py 
  --mode img2video 
  --prompt "The character turns around slowly" 
  --image "https://example.com/character.jpg" 
  --resolution 720p 
  --ratio 9:16 
  --output-dir ./output

参数说明

视频生成约束（重要）

1. 限流严格：1 次/分钟，连续提交会返回 429
2. 审核严格：prompt ≤ 200 字符，简短陈述式，无破折号/无音频指令
3. 竖屏务必：用 --resolution 720p --ratio 9:16（实测映射为 704×1280）
4. 不要用 576x1024 等原始宽高 → 会报 400
5. 轮询地址：官方推荐 GET /agnesapi?video_id=<VIDEO_ID>，兼容旧端点 GET /v1/videos/{id}

Phase 4：验证与交付

1. 检查输出文件是否存在（图片 .png，视频 .mp4）
2. 图片：确认分辨率和比例正确
3. 视频：用 ffprobe 检查时长和分辨率
4. 将文件路径告知用户

多媒体工作流示例

示例 1：公众号文章配图

# 生成横版封面图（16:9）
python3 scripts/generate_image.py 
  --prompt "Modern AI technology concept, blue and white color scheme, flat illustration style, absolutely no text, no words, no letters" 
  --size 1536x864 
  --output-dir ./article-images 
  --filename cover

示例 2：产品展示视频

# 生成 5 秒横版产品展示视频
python3 scripts/generate_video.py 
  --prompt "A sleek smartphone rotating on a minimalist white podium, studio lighting" 
  --resolution 720p --ratio 16:9 
  --output-dir ./product-video

示例 3：竖屏社交媒体视频

# 生成竖版短视频
python3 scripts/generate_video.py 
  --prompt "A young woman smiling at camera, warm golden hour lighting, vertical format" 
  --resolution 720p --ratio 9:16 
  --num-frames 81 
  --output-dir ./social-video

X402 支付接入（Pay Skill 协议）

本 Skill 已接入 SkillHub X402 Agent Pay 协议（基于 wechatpay v3 Native 支付），调用前由服务端完成预下单与支付触发，用户授权支付后 Agent 继续获取付费能力。计费模式：按调用量计费（per_call），单次调用 0.5 元（= 50 分）。

商户与密钥（已配置）

计费边界

• 计费单位：每次成功调用计 1 次（一次成功的生成/处理调用（图像/视频生成））。
• 不计费场景：付费前置检查失败、参数校验未通过、签名错误导致的预下单失败、用户主动取消支付、上游 AI 服务生成失败（失败调用不计费）。
• 订单标识：out_trade_no 形如 agnes-media-gen-skill_<YYYYMMDDHHMMSS>_<6位随机>，幂等去重。

X402 4 步调用流程

Step 1 · 付费前置检查（precheck）

Agent 调用本 Skill 前，必须先做付费前置检查：

1. 检查 weixinpay 插件是否安装：Agent 侧调用 weixinpay_check_plugin()（或检查 weixinpay_pay 工具是否在可用工具列表）。若未安装，引导用户启用 weixinpay 插件后再调用本 Skill，否则无法完成支付触发。
2. 读取请求中的 skill_id、skill_version、调用参数；
3. 校验 pub_key_id 是否在本商户有效密钥列表内（最多 3 对，本 Skill 使用 PUB_KEY_7695C2E0CDCCE5E919DAD0E730C1B24A）；
4. 生成幂等 out_trade_no，落库待支付订单；
5. 进入 Step 2。

若 weixinpay 插件缺失，本次调用直接返回错误 "需先安装 weixinpay 插件才能完成付费调用"，不进入 Step 2。

Step 2 · 微信支付下单（WeixinPay Native）

服务端调用微信支付下单接口创建预付订单：

POST https://api.mch.weixin.qq.com/v3/pay/transactions/native
Content-Type: application/json

{
  "appid": "wx1234567890abcdef",
  "mchid": "1116760867",
  "description": "agnes-media-gen-skill - 单次调用",
  "out_trade_no": "agnes-media-gen-skill_20260925120000_834721",
  "notify_url": "https://api.hongzhaoai.com/pay/notify/agnes-media-gen-skill",
  "amount": { "total": 50, "currency": "CNY" }
}

返回 code_url（weixin://wxpay/bizpayurl?pr=...），用于 Step 3 的 pay_items[].pay_data.value。

Step 3 · X402 AI 预下单（payment_required 签名）

业务服务构造 payment_required 业务 JSON 并 Base64 编码：

{
  "skill_info": { "skill_id": "agnes-media-gen-skill", "skill_version": "1.0.0" },
  "pay_type": "SKILL_PAY",
  "pay_mode": "AUTH_AND_PAY",
  "pay_items": [
    {
      "product_id": "AGNESMEDIAGE20260925001",
      "pay_data": { "type": "code_url", "value": "weixin://wxpay/bizpayurl?pr=example" }
    }
  ],
  "expires_at": 1784649665
}

用 Step 1 的 RSA 2048 私钥对以下 5 行签名串（每行以 n 结尾，最后一行也保留换行）做 SHA256withRSA：

SKILLHUB-SHA256-RSA2048
sh-GvUzjdxZ
<32位随机 nonce_str>
<Unix秒 timestamp>
<base64(payment_required)>

组装请求体：

{
  "signature_type": "SKILLHUB-SHA256-RSA2048",
  "developer_platform": "SKILLHUB",
  "developer_id": "sh-GvUzjdxZ",
  "pub_key_id": "PUB_KEY_7695C2E0CDCCE5E919DAD0E730C1B24A",
  "nonce_str": "<32位随机>",
  "timestamp": 1784648765,
  "signature": "<base64-signature>",
  "payment_required": "<base64-payment-required>"
}

调用 X402 预下单接口换取 payment_code（有效期 15 分钟）。

Step 4 · 支付触发（返回 402 + payment_code）

服务端把 payment_code 同时写入 HTTP Header 和响应体，返回给 Agent：

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
Content-Type: application/json

{
  "message": "本次调用需要支付后继续",
  "WeixinPay": {
    "WeixinPay-Required": "<payment_code>",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  }
}

Agent 拿到 payment_code 后交给微信支付 Skill 发起用户授权；用户授权完成后，按本 Skill 业务协议继续调用获取结果。

支付后重试机制与异常处理

支付后重试机制（核心）：用户完成微信支付后，Agent 必须用相同的请求 body 重新调用本 Skill 接口（body 完全不变），并在 HTTP Header 中携带 WeixinPay-Required: <payment_code> 和 X-Pay-Token: <支付凭证>。服务端识别到支付已完成（通过 out_trade_no 查询微信支付结果），跳过 Step 1-4 的支付触发流程，直接返回业务结果。重试时 body 不能改、参数不能变，否则视为新调用需重新付费。

订单号传递与异常对账

订单号传递（核心）：每次付费调用生成的 out_trade_no 必须在支付完成后随重试请求一起传递——Agent 在重试时需在请求中携带 X-Out-Trade-No: <out_trade_no> 头部（或 body 中加 pay_trade_no 字段）。服务端按 out_trade_no 查询微信支付结果验证支付成功，然后返回业务结果。若重试时未携带订单号或支付凭证，服务端无法关联支付记录，将再次返回 402 触发新一轮付费。

• 传递链：服务端生成 out_trade_no → 微信下单 → payment_required.skill_info 关联 → payment_code 返回 Agent → 支付完成后 notify_url 回调 → 服务端按 out_trade_no 更新订单为已支付 → T+1 结算到绑定商户号。
• 对账依据：以微信支付回调或 out_trade_no 查询结果为准；SkillHub 商户中心提供调用与结算明细。

本 Skill 的 X402 接入遵循 SkillHub 官方《升级为 Pay Skill》规范（https://www.skillhub.cn/tutorials#agent-pay-upgrade）。

由 鸿爪派 出品。