Vos recettes, workflows et compétences

Réutilisez ce que vous avez enregistré sur popnow.ai : une recette du Studio avec son modèle, son prompt, ses réglages et ses fichiers ; un workflow du canevas dont les étapes utilisent les résultats précédents ; ou une compétence Poppie contenant des instructions qu’un autre assistant peut suivre.

Les éléments restent accessibles uniquement à vous et aux équipes avec lesquelles vous les partagez. Le prompt de la recette d’un coéquipier n’est pas renvoyé ; le serveur l’assemble à l’exécution. Les exécutions REST et MCP avec clé API utilisent votre solde API séparé en USD. Les exécutions OAuth MCP utilisent les crédits du site. Les soldes ne peuvent être ni transférés ni utilisés l’un à la place de l’autre. Les nouveaux soldes API commencent à $0 ; approvisionnez-les dans Facturation API.

En bref

Trouver ce que vous pouvez lancer

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

Omettez kind pour lister à la fois les recettes et les workflows. Vos propres éléments apparaissent en premier, suivis de ceux partagés avec vos équipes (mine: false, avec teamId). Chaque élément décrit ses entrées :

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

Consultez un élément pour obtenir son estimation actuelle avec les fichiers enregistrés :

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

Les métadonnées API utilisent currency: "USD" et, éventuellement, estimated_usd, sans estimatedCredits. Cette estimation n’autorise pas l’exécution : envoyez les entrées réelles à POST /run pour obtenir un quote_id.

Lancer

Envoyez d’abord les entrées et le nombre souhaités sans champs d’approbation. Un devis ne crée aucune exécution et ne réserve pas de fonds ; il ne nécessite pas d’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
  }
}

Après avoir vérifié et approuvé le montant, renvoyez les mêmes entrées et le même nombre avec currency: "USD", max_usd sous forme de chaîne décimale et le quote_id reçu. L’exécution exige un Idempotency-Key de 1 à 100 caractères ; réutilisez cette clé lorsque vous réessayez la même soumission.

# 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\"}"

Un démarrage réussi renvoie needs_confirmation: false, run_id, state et le max_usd approuvé. Si le prix dépasse le plafond ou si le devis ne correspond plus, la réponse contient à la place needs_confirmation: true et un nouveau devis ; aucune exécution ne démarre. Affichez le nouveau montant et demandez à nouveau l’accord. HTTP 200 ne signifie pas à lui seul que le travail a commencé.

max_usd est une chaîne décimale non négative acceptant jusqu’à neuf décimales. Les nombres JSON, les valeurs négatives, la notation exponentielle, les champs inconnus et les anciennes approbations maxCredits / max_credits sont rejetés, pas convertis. Fournir max_usd sans quote_id est invalide. Même un devis à prix nul exige un accord explicite.

Ce que sont les entrées

Les fichiers peuvent être une URL https, un popnow://g/<job>/<n> issu d’un résultat antérieur, un popnow://f/<file> issu d’un envoi ou un popnow://a/<asset> issu d’un asset API. Les entrées omises réutilisent les fichiers enregistrés. count va de 1 à 4 pour les recettes ; les workflows s’exécutent une seule fois. Les entrées invalides renvoient 400 avec param: inputs.<id>.

Un workflow peut avoir besoin d’un résultat précédent avant de pouvoir chiffrer une étape. Son devis inclut alors unpriced_steps : cost_usd couvre uniquement les étapes actuellement chiffrées, pas le workflow complet. Les étapes non chiffrées ne peuvent pas s’exécuter. Une fois leurs entrées disponibles, l’exécution se met en pause pour obtenir un nouveau devis de reprise et son approbation. Non chiffré ne signifie pas gratuit.

Suivre une exécution

Utilisez la même clé API que celle qui a lancé l’exécution. Une autre clé du même compte ne peut ni la consulter ni la reprendre. Les requêtes de statut avec clé API ne réinterprètent pas une exécution OAuth en crédits comme une exécution en 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 vaut draft, running, paused, done, stopped ou failed. Interrogez le statut tant qu’il vaut draft ou running. Pour paused, consultez pause_reason et demandez un devis de reprise une fois le problème résolu. items conserve stepId, state, jobId et uri ; recordInfo renvoie les liens de téléchargement de chaque tâche.

spent_usd est le débit net réel du portefeuille API, après prise en compte des fonds restitués. cost_usd est une estimation, pas le montant facturé après règlement. Les réponses USD ne contiennent pas de crédits entiers. Les exécutions historiques en crédits du site conservent leur devise d’origine et restent accessibles par le parcours pris en charge sur le site ou par OAuth.

Reprendre une exécution en pause

Envoyez {} pour obtenir un nouveau devis :

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

Après vérification, renvoyez la requête avec currency: "USD", max_usd et le nouveau quote_id. Il s’agit du budget total de toute l’exécution, y compris les fonds dépensés et les coûts engagés pour les tâches en cours, pas d’une enveloppe supplémentaire. Les entrées et le nombre d’origine ne peuvent pas changer.

La reprise ne nécessite pas d’Idempotency-Key. Des requêtes simultanées ne peuvent pas reprendre le travail deux fois ; une exécution déjà reprise renvoie un conflit. La clé, le compte de paiement et le contexte d’origine restent associés à l’exécution. Si la politique IP de la clé change, démarrez une nouvelle exécution depuis une source autorisée au lieu de contourner la pause.

Compétences

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

GET /api/v1/skills liste vos compétences et celles partagées avec vos équipes. GET /api/v1/skills/{id} ajoute leur body en Markdown. Une compétence d’équipe partagée en mode use only (shareMode: "use") n’a pas de body : elle fonctionne dans PopNow, mais ses instructions restent masquées.

Dans ChatGPT et Claude

Connectez le serveur MCP et demandez « lance ma recette Weekly post avec cette photo ». L’assistant utilise le compte de paiement connecté, sans choisir entre les portefeuilles.

MCP avec clé API suit les règles ci-dessus concernant le devis USD, la confirmation, le budget total et l’utilisation de la même clé. Confirmer run_my_recipe exige aussi une chaîne idempotency_key de 1 à 100 caractères ; demander un devis n’en nécessite pas. Si la réponse est perdue, réessayez avec la même clé d’idempotence et tous les mêmes paramètres pour retrouver l’exécution acceptée, même si la recette ou le prix a changé depuis. Utilisez une nouvelle clé uniquement pour une exécution approuvée séparément. Modifier les paramètres sous la même clé renvoie un conflit. OAuth conserve les approbations max_credits en crédits du site et rejette les champs USD. L’outil de reprise concerne les exécutions USD avec clé API et ne nécessite pas de nouvelle clé d’idempotence ; il s’appuie sur l’état de l’exécution d’origine pour éviter de refaire le travail.

Limites et erreurs

Chaque étape USD vérifie à nouveau le statut de la clé, son expiration, les autorisations de modèles, les plafonds de dépense et le solde API. Le budget inclut les fonds dépensés, les réservations pour les tâches en cours et le travail réservé ; les nouvelles tentatives techniques comptent aussi. Une variation de prix de seulement 0,000000001 USD met l’exécution en pause pour approbation. Les budgets totaux sont limités à 10 000 USD, avec 1 000 USD par étape.

D’autres personnes peuvent-elles voir ou lancer mes recettes ?

Seuls vous et les équipes avec lesquelles vous les partagez pouvez accéder aux éléments enregistrés. Il n’existe ni catalogue public ni accès en devinant un identifiant. Le prompt d’une recette partagée n’est jamais renvoyé à un coéquipier.

Qui paie quand je lance une recette partagée par mon équipe ?

Vous. Les exécutions avec clé API utilisent votre portefeuille API en USD ; OAuth utilise les crédits du site. Vérifiez d’abord le devis et approuvez le budget.

Dois-je renvoyer mes fichiers à chaque exécution ?

Non. Utilisez une URL https ou une référence popnow:// issue d’un résultat, d’un envoi ou d’un asset API. Les entrées omises réutilisent les fichiers enregistrés.

Que se passe-t-il quand le modèle utilisé par une recette est retiré ?

L’exécution ne peut pas démarrer. Ouvrez la recette sur popnow.ai, choisissez un modèle disponible et enregistrez-la à nouveau, puis demandez un nouveau devis.

Existe-t-il un SDK pour les recettes ?

Utilisez ces exemples JSON sur HTTPS ou un client HTTP, en conservant les USD sous forme de chaînes. Ne réutilisez pas d’anciens exemples SDK qui approuvent les exécutions de recettes API avec des crédits entiers.

Liens connexes