レシピ、ワークフロー、スキル

popnow.ai で保存したものを再利用できます。Studio からモデル、プロンプト、設定、ファイルとともに保存したレシピ、前のステップの結果を使うキャンバスのワークフロー、別のアシスタントが従える手順をまとめた Poppie のスキルが対象です。

これらはあなたと共有先のチームだけのものです。チームメンバーのレシピのプロンプトは返されず、サーバーが実行時に組み立てます。API キーによる REST・MCP の実行には、独立した API USD 残高を使います。OAuth MCP の実行にはウェブサイトのクレジットを使います。残高を相互に移行したり、代わりに使ったりすることはできません。新しい API 残高は $0 から始まります。API billing で入金してください。

概要

実行できるものを探す

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"
    }]
  }
}

項目を 1 件読み取ると、保存されたファイルでの現在の見積もりを確認できます。

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 による承認は、変換されずに拒否されます。quote_id なしで max_usd を指定することはできません。金額がゼロの見積もりでも、明示的な承認が必要です。

入力の内容

ファイルには https の URL、以前の結果の popnow://g/<job>/<n>、アップロードの popnow://f/<file>、API アセットの popnow://a/<asset> を使えます。省略した入力は保存済みのファイルを再利用します。count はレシピでは 1〜4、ワークフローは 1 回だけ実行されます。無効な入力には、param: inputs.<id> を含む 400 が返ります。

ワークフローでは、前のステップの出力が揃うまで料金を計算できないステップがあります。その場合、見積もりには unpriced_steps が含まれます。cost_usd は現時点で料金を計算できたステップ分のみで、ワークフロー全体の金額ではありません。 未見積もりのステップは実行できません。入力が揃うと、新しい再開の見積もりと承認を待つために実行が一時停止します。未見積もりは無料という意味ではありません。

実行を追う

開始に使った同じ API キーを使用してください。同じアカウントでも、別のキーではその実行を読み取ったり再開したりできません。API キーで状態を取得しても、OAuth のクレジットによる実行が USD の実行として扱われることはありません。

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 は見積もり額で、精算済みの金額ではありません。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 を加えます。チームのスキルが use only（shareMode: "use"）で共有されている場合、body はありません。PopNow 上では使えますが、その手順は非公開のままです。

ChatGPT と Claude で

MCP サーバーに接続し、「この写真で Weekly post のレシピを実行して」と頼んでください。アシスタントはウォレットを選び分けず、接続に紐づく支払い元アカウントを使います。

API キーの MCP には、上記の USD の見積もり、承認、総予算、同一キーのルールが適用されます。run_my_recipe の実行を承認する際は、1〜100 文字の idempotency_key 文字列も必要です。見積もりだけなら不要です。レスポンスを受け取れなかった場合は、同じ冪等キーとすべて同じパラメーターで再試行すると、その後レシピや料金が変わっていても、受理済みの実行を取得できます。新しい冪等キーを使うのは、別途承認した新しい実行の場合だけです。同じ冪等キーでパラメーターを変更すると、競合エラーが返ります。OAuth は引き続きウェブサイトのクレジットによる max_credits の承認を使い、USD のフィールドを拒否します。再開ツールは API キーの USD 実行用で、新しい冪等キーは不要です。元の実行の状態を使って処理の重複を防ぎます。

上限とエラー

USD の各ステップで、キーの状態、有効期限、モデルの利用権限、支出上限、API 残高が再確認されます。予算には支出済みの金額、処理中の確保額、予約済みの処理が含まれ、技術的な再試行も計上されます。わずか $0.000000001 の価格変更でも、承認を待つために実行が一時停止します。総予算の上限は $10,000、ステップごとの上限は $1,000 です。

ほかの人が私のレシピを見たり実行したりできますか？

保存した項目にアクセスできるのは、あなたと共有先のチームだけです。公開カタログはなく、ID を推測してアクセスすることもできません。共有したレシピのプロンプトがチームメンバーに返されることはありません。

私のチームが共有したレシピを実行すると、誰が支払いますか？

あなたです。API キーによる実行はあなたの API USD ウォレット、OAuth はウェブサイトのクレジットを使います。まず見積もりを確認し、予算を承認してください。

実行のたびにファイルをアップロードし直す必要がありますか？

いいえ。https の URL、または結果、アップロード、API アセットの popnow:// 参照を使ってください。省略した入力には保存済みのファイルが使われます。

レシピが使ったモデルが廃止されたらどうなりますか？

実行を開始できません。popnow.ai でレシピを開き、利用可能なモデルを選んで保存し直してから、新しい見積もりを取得してください。

レシピ用の SDK はありますか？

このページの HTTPS で JSON を送受信する例か、HTTP クライアントを使い、USD の金額は文字列のまま扱ってください。API のレシピ実行を整数のクレジットで承認する古い SDK の例は再利用しないでください。

関連ページ