NPPU 文生图(按次付费)
一次任务、一口价、一个结果。不订阅、不充值、不留余额。
什么时候用这个 skill
用户想要一张新生成的图片时用它:「生成一张…」「画一个…」「做张图片」。
不要用它做:修改已有图片、放大、去水印 —— 那些是别的能力。
计费
每次调用 ¥0.01,通过微信支付结算。付款由你(Agent)发起、用户在微信里确认。
执行失败或质检不通过不交付,服务端会标记退款。
调用方式
端点(POST,无需 API Key):
https://test.ipalfish.com/klian/palhubapi/palhub/v1/nppu/skill/image_generate
请求体:
{ "prompt": "a red panda drinking coffee, studio lighting" }
完整流程
这是一个 HTTP 402 付费接口,必须走四步,第 4 步不能省:
1. 首次请求(不带任何额外 Header)
服务端返回 402 Payment Required,并在响应头里给出两个值:
WeixinPay-Required: <支付码>
X-Out-Trade-No: <订单号>
2. 两个值都要保存下来。 后面每一次请求都要原样带回。
3. 用支付码发起收款:把 WeixinPay-Required 的值作为 paymentCode 调用 weixinpay_pay,用户在微信里确认付款。
4. 带上两个 Header 重新 POST 同一个端点,取回结果。请求体可以为空。
X-Out-Trade-No: <第1步拿到的订单号>
WeixinPay-Required: <第1步拿到的支付码>
第 4 步的四种响应
全部是 HTTP 200,看 body 里的 status 字段:
| status | 含义 | 你该做什么 |
|---|---|---|
succeeded |
已完成 | 取 result 里的图片地址给用户 |
running |
还在生成 | 等几秒,带同样两个 Header 再调一次 |
awaiting_payment |
付款还没到账 | 等几秒重试;一直如此说明第 3 步没成功 |
failed |
生成失败或质检不通过 | 告诉用户失败原因,refund 字段标记了退款状态 |
succeeded 示例:
{
"status": "succeeded",
"out_trade_no": "WX402_...",
"already_fulfilled": false,
"result": { "images": ["https://..."] }
}
重要
- 同一个订单只会执行一次、只收一次费。 重复调用第 4 步是安全的,拿到的是同一份结果(
already_fulfilled: true)。 - 生成通常十几秒内完成。若返回
running,隔 3-5 秒重试即可,不要重新走第 1 步 —— 那会开一笔新订单、重复收费。 - 账单有效期 15 分钟,超时未付款需要从第 1 步重新开始。
出错时
| HTTP | 含义 |
|---|---|
| 403 | 支付码与订单号对不上,从第 1 步重来 |
| 404 | 订单不存在或已过期,从第 1 步重来 |
| 503 | 服务未开启,稍后再试 |