你的配方、工作流和技能

复用你在 popnow.ai 上保存的内容：从 Studio 保存的配方，包含模型、提示词、设置和文件；后续步骤可使用前序结果的画布工作流；或包含其他助手可遵循说明的泡皮技能。

这些内容只有你和获分享的团队能访问。团队成员的配方提示词不会返回，服务器会在运行时组装。API-key REST 和 MCP 运行使用你的独立 API 美元余额，OAuth MCP 运行使用网站积分。两份余额不能互转，也不能相互抵用。新 API 余额初始为 $0，请在 API 账单充值。

概览

列出可运行的内容

curl "https://api.popnow.ai/api/v1/recipes?kind=recipe" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

省略 kind 会同时返回配方和工作流。你自己的条目排在前面，随后是与你所在团队分享的条目（mine: false，并附带 teamId）。每个条目都会列出所需的输入：

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [{
      "id": "svd_01jbq8x4m2c7d9f3h5k6n8p0rt",
      "kind": "recipe",
      "name": "Weekly post",
      "mine": true,
      "media": "image",
      "currency": "USD",
      "inputs": [
        { "id": "image_urls", "label": "Product", "media": "image", "multiple": false, "required": false },
        { "id": "prompt", "label": "Prompt", "media": "text", "multiple": false, "required": false }
      ],
      "steps": 1,
      "updatedAt": "2026-10-23T09:12:00Z"
    }]
  }
}

读取单个条目，查看使用已保存文件时的当前预估费用：

curl https://api.popnow.ai/api/v1/recipes/svd_01jbq8x4m2c7d9f3h5k6n8p0rt \
  -H "Authorization: Bearer $POPNOW_API_KEY"

API 元数据使用 currency: "USD" 和可选的 estimated_usd，不包含 estimatedCredits。这项预估不代表已获准执行：请将实际输入发送到 POST /run，获取 quote_id。

运行

先发送计划使用的输入和数量，不带确认字段。报价不会创建运行，也不会冻结资金；无需 Idempotency-Key。

curl https://api.popnow.ai/api/v1/recipes/svd_01jbq8x4m2c7d9f3h5k6n8p0rt/run \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{},"count":1}'

{
  "code": 200,
  "msg": "success",
  "data": {
    "currency": "USD",
    "cost_usd": "0.048",
    "available_usd": "5",
    "spent_usd": "0",
    "quote_id": "quote_from_server",
    "needs_confirmation": true
  }
}

查看并确认金额后，使用相同的输入和数量再次提交，带上 currency: "USD"、十进制字符串 max_usd 及返回的 quote_id。执行时需要长度为 1–100 个字符的 Idempotency-Key；重试同一次提交时，请复用这个键。

# Set QUOTE_ID to the quote_id returned above, after reviewing the quote.
curl https://api.popnow.ai/api/v1/recipes/svd_01jbq8x4m2c7d9f3h5k6n8p0rt/run \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"inputs\":{},\"count\":1,\"currency\":\"USD\",\"max_usd\":\"0.048\",\"quote_id\":\"$QUOTE_ID\"}"

成功启动后会返回 needs_confirmation: false、run_id、state 和已批准的 max_usd。如果价格超过上限或报价不再匹配，响应会改为返回 needs_confirmation: true 和新报价，不会启动运行。请展示新金额并再次征求确认。仅凭 HTTP 200 不能判断任务已经开始。

max_usd 是非负的十进制字符串，最多 9 位小数。JSON 数字、负数、指数记法、未知字段以及旧的 maxCredits / max_credits 确认参数都会被拒绝，不会自动转换。提供 max_usd 却不带 quote_id 属于无效请求。零价报价也需要明确确认。

输入是什么

文件可以使用 https 链接、早先结果的 popnow://g/<job>/<n>、上传文件的 popnow://f/<file>，或 API 素材的 popnow://a/<asset>。省略的输入会复用已保存的文件。配方的 count 为 1–4；工作流只运行一次。无效输入返回 400，并附带 param: inputs.<id>。

工作流中的某个步骤可能要等前序结果生成后才能计价，此时报价会包含 unpriced_steps：cost_usd 只覆盖当前已计价的步骤，不是完整工作流的费用。 未计价步骤不能执行。等输入准备就绪后，运行会暂停，等待新的恢复报价和确认。未计价不代表免费。

跟踪运行

请使用启动时的同一把 API 密钥。同账户下的其他密钥不能读取或恢复这次运行。使用 API 密钥查询状态，不会把 OAuth 积分运行记录重新解释为美元记录。

curl https://api.popnow.ai/api/v1/recipes/runs/sfg_01jbq9a3d5f7g9h2k4m6n8p0qs \
  -H "Authorization: Bearer $POPNOW_API_KEY"

{
  "code": 200,
  "msg": "success",
  "data": {
    "currency": "USD",
    "run_id": "sfg_01jbq9a3d5f7g9h2k4m6n8p0qs",
    "state": "done",
    "cost_usd": "0.048",
    "available_usd": "4.952",
    "spent_usd": "0.048",
    "max_usd": "0.048",
    "needs_confirmation": false,
    "items": [
      { "stepId": "r1", "state": "succeeded", "jobId": "job_01jbq9a6v8w0x2y4z6a8b0c2d4", "uri": "popnow://g/job_01jbq9a6v8w0x2y4z6a8b0c2d4/0" }
    ]
  }
}

state 为 draft、running、paused、done、stopped 或 failed。处于 draft 或 running 时可继续轮询。处于 paused 时，查看 pause_reason，解决问题后再获取恢复报价。items 保留 stepId、state、jobId 和 uri；recordInfo 返回每个任务的下载链接。

spent_usd 是 API 钱包的实际净扣款，已计入返还的资金。cost_usd 是预估费用，不是结算费用。美元响应不包含整数积分。历史网站积分运行保留原币种，仍需通过支持它们的网站或 OAuth 流程访问。

恢复暂停的运行

发送 {} 获取新报价：

curl https://api.popnow.ai/api/v1/recipes/runs/sfg_01jbq9a3d5f7g9h2k4m6n8p0qs/resume \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

查看报价后，带上 currency: "USD"、max_usd 和新的 quote_id 再次提交。这是整次运行的总预算，包含已花费金额及执行中已承诺的费用，不是额外增加的额度。 原始输入和数量不能更改。

恢复无需 Idempotency-Key。并发请求不会重复恢复运行；已经恢复的运行会返回冲突。运行仍关联原密钥、付款账户和来源上下文。如果密钥的 IP 策略发生变化，请从允许的来源启动新的运行，不要绕过暂停限制。

技能

curl https://api.popnow.ai/api/v1/skills/skl_01jbpz7c9e1g3j5m7q9s1v3x5z \
  -H "Authorization: Bearer $POPNOW_API_KEY"

GET /api/v1/skills 列出你的技能，以及与你所在团队分享的技能。GET /api/v1/skills/{id} 会额外返回 Markdown 格式的 body。以仅使用（shareMode: "use"）方式分享的团队技能没有 body：它可以在 PopNow 中使用，但说明内容保持隐藏。

在 ChatGPT 和 Claude 中

连接 MCP 服务器，然后说「用这张照片运行我的 Weekly post 配方」。助手会使用连接对应的付款账户，不会在两份钱包之间选择。

API-key MCP 遵循上述美元报价、确认、总预算及同密钥规则。确认 run_my_recipe 时还需要提供长度为 1–100 个字符的 idempotency_key 字符串；仅报价时不需要。如果响应丢失，请使用同一个幂等键和全部相同的参数重试，以取回原先已受理的运行，即使配方或价格后来已变化也一样。只有另一次经过单独批准的运行才使用新的幂等键。使用同一个幂等键更改参数会返回冲突。OAuth 保留以网站积分为单位的 max_credits 确认方式，并拒绝美元字段。恢复工具适用于 API-key 美元运行，无需新的幂等键；它根据原运行的状态防止重复执行。

限制与错误

每个美元步骤都会重新检查密钥状态、有效期、模型权限、消费上限和 API 余额。预算包含已花费资金、执行中的冻结金额及已预留的工作，技术性重试也计入其中。价格即使只变化 $0.000000001，也会暂停执行并等待确认。整次运行的总预算上限为 $10,000，每步上限为 $1,000。

别人能看到或运行我的配方吗？

只有你和获分享的团队可以访问已保存的内容。没有公开目录，也不能通过猜测 ID 获取访问权限。共享配方的提示词不会返回给团队成员。

我运行团队分享的配方，谁来付费？

由你支付。API 密钥运行使用你的 API 美元钱包；OAuth 使用网站积分。请先查看报价并确认预算。

每次运行都要重新上传文件吗？

不用。使用 https 链接，或结果、上传文件、API 素材的 popnow:// 引用即可。省略的输入会复用已保存的文件。

配方用的模型下线了会怎样？

运行无法启动。请在 popnow.ai 上打开配方，选择可用模型并重新保存，然后获取新报价。

配方有 SDK 吗？

可以使用这些通过 HTTPS 传输 JSON 的示例或 HTTP 客户端，美元金额始终保留为字符串。不要复用通过整数积分批准 API 配方运行的旧 SDK 示例。

相关