星元Firefly Image2生图

为什么需要这个技能

在 Agent 工作流里生成一张可用图片，看起来只是调个模型，实际接入时往往要自己拼支付、轮询、错误处理等一堆胶水代码。这个技能把「整理输入 → 发起生成 → 支付授权 → 轮询结果 → 返回图片」整条链路封装成一次调用。每次成功生成固定收费 0.20 元，生成失败自动原路退款，开发者不需要关心背后的收单细节。

核心能力与调用流程

输入字段固定为三个：

• prompt（必填）：描述主体、场景、风格、光线、构图和需要保留的文字
• aspect_ratio（可选）：只接受 1:1、16:9、9:16、4:3、3:4、3:2、2:3 七种取值，未指定时默认 1:1
• reference_images（可选）：可填入 1–14 个可公开访问的 http/https 图片地址

用户用自然语言表达画幅意图时需要做归一化：「方形商品主图」转成 1:1，「竖版手机海报」转成 9:16，「摄影横幅」转成 3:2，其余依表映射。

调用步骤如下：

1. 先检查当前 Agent 能否调用 weixinpay 扩展；不可用时直接告知环境暂不支持微信支付，不要发起生图请求
2. 向服务地址发起 POST 请求
3. 收到 HTTP 402 时，保存响应头 WeixinPay-Required 与 X-Out-Trade-No，通过 weixinpay 扩展申请本次 0.20 元 支付授权，再用完全相同的请求体和响应头重试原地址
4. 支付成功后的重试通常返回 HTTP 202，从中拿到 status_url、task_token 与 out_trade_no
5. 每 3 秒轮询一次 status_url，最多等待 5 分钟

状态处理

轮询返回的 code 决定下一步动作：

• PROCESSING：继续轮询等待
• SUCCESS：从 content.output[0].url 取出图片地址，直接展示给用户
• NOT_PAID：等待 2 秒后用同一订单重试，不要再次付款
• REFUND_PENDING / REFUNDED：生成失败，退款处理中或已退款，停止重试
• FULFILL_AND_REFUND_FAILED：生成与自动退款均失败，保留订单号并联系 Firefly

生成成功后直接展示图片并提醒用户及时下载，图片链接保存 7 天。

适用边界

• 固定使用 Image 2 · 1K 模型，不接受 2K、4K 或其他模型要求
• 一次调用只生成一张图片；文生图、单参考图与多参考图价格相同
• 不支持直接上传本地文件，需要用户提供可公开访问的图片地址
• 不承诺复刻受版权保护的作品，不生成违法、欺诈、色情或伤害性内容
• 不得绕过支付步骤，同一订单不得重复付款