Le tue ricette, workflow e skill

Riutilizza ciò che hai salvato su popnow.ai: una ricetta di Studio con modello, prompt, impostazioni e file; un workflow del canvas i cui passaggi usano i risultati precedenti; oppure una skill Poppie con istruzioni che un altro assistente può seguire.

Gli elementi restano privati, accessibili solo a te e ai team con cui li condividi. Il prompt della ricetta di un collega non viene restituito: il server lo compone durante l’esecuzione. Le esecuzioni REST e MCP con chiave API usano il tuo saldo API separato in USD. Le esecuzioni MCP via OAuth usano i crediti del sito. I saldi non si possono trasferire né usare l’uno al posto dell’altro. Il saldo API iniziale è di $0; aggiungi fondi in Fatturazione API.

Vista d’insieme

Trova ciò che puoi eseguire

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

Ometti kind per elencare sia ricette sia workflow. Prima compaiono i tuoi elementi, poi quelli condivisi con i tuoi team (mine: false, con teamId). Ogni elemento descrive i propri input:

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

Leggi un elemento per ottenere la stima attuale con i file salvati:

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

I metadati API usano currency: "USD" e il campo facoltativo estimated_usd, senza estimatedCredits. Questa stima non autorizza l’esecuzione: invia gli input effettivi a POST /run per ottenere un quote_id.

Eseguila

Invia prima gli input e il numero di risultati desiderati senza campi di approvazione. Un preventivo non crea un’esecuzione e non blocca fondi; non richiede un 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
  }
}

Dopo aver verificato e approvato l’importo, ripeti gli stessi input e lo stesso numero di risultati con currency: "USD", max_usd come stringa decimale e il quote_id ricevuto. L’esecuzione richiede un Idempotency-Key da 1 a 100 caratteri; riutilizza quella chiave quando ritenti lo stesso invio.

# 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 avvio riuscito restituisce needs_confirmation: false, run_id, state e il max_usd approvato. Se il prezzo supera il limite o il preventivo non corrisponde più, la risposta contiene invece needs_confirmation: true e un nuovo preventivo; non viene avviata alcuna esecuzione. Mostra il nuovo importo e chiedi di nuovo l’approvazione. Il solo HTTP 200 non significa che il lavoro sia iniziato.

max_usd è una stringa decimale non negativa con un massimo di nove cifre decimali. Numeri JSON, valori negativi, notazione esponenziale, campi sconosciuti e vecchie approvazioni maxCredits / max_credits vengono rifiutati, non convertiti. Inviare max_usd senza quote_id non è valido. Anche un preventivo a prezzo zero richiede un’approvazione esplicita.

Cosa sono gli input

I file possono essere un URL https, un popnow://g/<job>/<n> da un risultato precedente, un popnow://f/<file> da un caricamento o un popnow://a/<asset> da un asset API. Gli input omessi riusano i file salvati. count va da 1 a 4 per le ricette; i workflow vengono eseguiti una volta. Gli input non validi restituiscono 400 con param: inputs.<id>.

Un workflow può aver bisogno di un risultato precedente prima di poter calcolare il prezzo di un passaggio. In tal caso il preventivo include unpriced_steps: cost_usd copre solo i passaggi con un prezzo già calcolato, non l’intero workflow. I passaggi senza prezzo non possono essere eseguiti. Quando i loro input sono pronti, l’esecuzione si mette in pausa in attesa di un nuovo preventivo di ripresa e della sua approvazione. Senza prezzo non significa gratuito.

Segui un’esecuzione

Usa la stessa chiave API che ha avviato l’esecuzione. Un’altra chiave dello stesso account non può leggere o riprendere l’esecuzione. Le richieste di stato con chiave API non reinterpretano in USD un’esecuzione OAuth in crediti.

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 o failed. Interroga lo stato finché è draft o running. Per paused, controlla pause_reason e richiedi un preventivo di ripresa dopo aver risolto il problema. items mantiene stepId, state, jobId e uri; recordInfo restituisce i link di download di ogni attività.

spent_usd è l’addebito netto effettivo sul portafoglio API, tenendo conto dei fondi restituiti. cost_usd è una stima, non l’addebito definitivo. Le risposte in USD non contengono crediti interi. Le esecuzioni storiche in crediti del sito mantengono la valuta originale e restano nel flusso supportato sul sito o via OAuth.

Riprendere un’esecuzione in pausa

Invia {} per ottenere un nuovo preventivo:

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

Dopo la verifica, ripeti la richiesta con currency: "USD", max_usd e il nuovo quote_id. È il budget totale dell’intera esecuzione, inclusi i fondi già spesi e gli impegni per le attività in corso, non un importo aggiuntivo. Gli input e il numero di risultati originali non possono cambiare.

La ripresa non richiede un Idempotency-Key. Richieste simultanee non possono riprendere il lavoro due volte; un’esecuzione già ripresa restituisce un conflitto. La chiave originale, il conto di pagamento e il contesto di origine restano associati. Se la policy IP della chiave cambia, avvia una nuova esecuzione da un’origine consentita anziché aggirare la pausa.

Skill

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

GET /api/v1/skills elenca le tue skill e quelle condivise con i tuoi team. GET /api/v1/skills/{id} aggiunge il loro body in Markdown. Una skill di team condivisa in modalità use only (shareMode: "use") non ha un body: funziona in PopNow, ma le sue istruzioni restano nascoste.

In ChatGPT e Claude

Collega il server MCP e chiedi «esegui la mia ricetta Weekly post con questa foto». L’assistente usa il conto di pagamento collegato, senza scegliere tra i portafogli.

MCP con chiave API segue le regole sopra per preventivi in USD, conferma, budget totale e uso della stessa chiave. La conferma di run_my_recipe richiede anche una stringa idempotency_key da 1 a 100 caratteri; la richiesta di preventivo non la richiede. Se la risposta viene persa, ritenta con la stessa chiave e tutti gli stessi parametri per recuperare l’esecuzione già accettata, anche se nel frattempo la ricetta o il prezzo sono cambiati. Usa una nuova chiave solo per un’esecuzione approvata separatamente. Cambiare i parametri mantenendo la stessa chiave restituisce un conflitto. OAuth mantiene le approvazioni max_credits in crediti del sito e rifiuta i campi USD. Lo strumento di ripresa è destinato alle esecuzioni USD con chiave API e non richiede una nuova chiave di idempotenza; usa lo stato dell’esecuzione originale per evitare di ripetere il lavoro.

Limiti ed errori

Ogni passaggio in USD ricontrolla stato e scadenza della chiave, permessi sui modelli, limiti di spesa e saldo API. Il budget include fondi spesi, importi bloccati per attività in corso e lavoro prenotato; contano anche i tentativi tecnici ripetuti. Una variazione di prezzo anche di soli $0.000000001 mette in pausa l’esecuzione per ottenere l’approvazione. Il budget totale è limitato a $10,000, con $1,000 per passaggio.

Altre persone possono vedere o eseguire le mie ricette?

Solo tu e i team con cui li condividi potete accedere agli elementi salvati. Non esiste un catalogo pubblico e non si può ottenere accesso indovinando un ID. Il prompt di una ricetta condivisa non viene mai restituito a un collega.

Chi paga quando eseguo una ricetta condivisa dal mio team?

Tu. Le esecuzioni con chiave API usano il tuo portafoglio API in USD; OAuth usa i crediti del sito. Prima verifica il preventivo e approva il budget.

Devo caricare di nuovo i miei file a ogni esecuzione?

No. Usa un URL https o un riferimento popnow:// a un risultato, un caricamento o un asset API. Gli input omessi riusano i file salvati.

Cosa succede quando il modello usato da una ricetta viene ritirato?

L’esecuzione non può iniziare. Apri la ricetta su popnow.ai, scegli un modello disponibile e salvala di nuovo, poi richiedi un nuovo preventivo.

Esiste un SDK per le ricette?

Usa questi esempi JSON su HTTPS o un client HTTP, mantenendo gli USD come stringhe. Non riutilizzare vecchi esempi SDK che approvano le esecuzioni delle ricette API con crediti interi.

Correlati