Tus recetas, flujos de trabajo y habilidades

Reutiliza lo que guardaste en popnow.ai: una receta guardada desde Studio con su modelo, prompt, ajustes y archivos; un flujo de trabajo del lienzo cuyos pasos usan resultados anteriores; o una habilidad de Poppie con instrucciones que otro asistente puede seguir.

Los elementos son privados para ti y los equipos con los que los compartes. El prompt de la receta de un compañero no se devuelve; el servidor lo ensambla al ejecutarla. Las ejecuciones REST y MCP con clave de API usan tu saldo independiente de la API en USD. Las ejecuciones MCP con OAuth usan créditos de la web. Los saldos no se pueden transferir ni usar uno en lugar del otro. Los saldos nuevos de la API empiezan en $0; añade fondos en API billing.

De un vistazo

Encuentra lo que puedes ejecutar

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

Omite kind para listar recetas y flujos de trabajo. Primero aparecen tus elementos, seguidos de los compartidos con tus equipos (mine: false, con teamId). Cada elemento describe sus entradas:

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

Consulta un elemento para obtener su estimación actual con los archivos guardados:

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

Los metadatos de la API usan currency: "USD" y, opcionalmente, estimated_usd, sin estimatedCredits. Esta estimación no aprueba la ejecución: envía las entradas reales a POST /run para obtener un quote_id.

Ejecútala

Primero envía las entradas y la cantidad previstas sin campos de aprobación. Una cotización no crea ninguna ejecución ni retiene fondos; no necesita 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
  }
}

Tras revisar y aprobar el importe, repite las mismas entradas y cantidad con currency: "USD", un max_usd como cadena decimal y el quote_id recibido. La ejecución necesita un Idempotency-Key de 1–100 caracteres; reutiliza esa clave cuando reintentes el mismo envío.

# 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 inicio correcto devuelve needs_confirmation: false, run_id, state y el max_usd aprobado. Si el precio supera el límite o la cotización ya no coincide, la respuesta contiene needs_confirmation: true y una nueva cotización; no se inicia ninguna ejecución. Muestra el nuevo importe y vuelve a pedir aprobación. Un HTTP 200 por sí solo no significa que el trabajo haya empezado.

max_usd es una cadena decimal no negativa con hasta nueve decimales. Los números JSON, los valores negativos, la notación exponencial, los campos desconocidos y las aprobaciones antiguas con maxCredits / max_credits se rechazan en lugar de convertirse. Enviar max_usd sin quote_id no es válido. Incluso una cotización de precio cero necesita aprobación explícita.

Qué son las entradas

Los archivos pueden ser una URL https, popnow://g/<job>/<n> de un resultado anterior, popnow://f/<file> de una subida o popnow://a/<asset> de un recurso de la API. Las entradas omitidas reutilizan los archivos guardados. count admite 1–4 para recetas; los flujos de trabajo se ejecutan una vez. Las entradas no válidas devuelven 400 con param: inputs.<id>.

Un flujo de trabajo puede necesitar un resultado anterior para poder calcular el precio de un paso. En ese caso, su cotización incluye unpriced_steps: cost_usd cubre solo los pasos cuyo precio ya se ha calculado, no el flujo completo. Los pasos sin precio calculado no se pueden ejecutar. Cuando sus entradas estén listas, la ejecución se pausa para obtener una nueva cotización de reanudación y aprobación. Que un paso no tenga precio calculado no significa que sea gratis.

Sigue una ejecución

Usa la misma clave de API que inició la ejecución. Otra clave de la misma cuenta no puede consultar ni reanudar esa ejecución. Las consultas de estado con clave de API no reinterpretan como USD una ejecución OAuth en créditos.

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 es draft, running, paused, done, stopped o failed. Consulta periódicamente mientras sea draft o running. Si es paused, revisa pause_reason y obtén una cotización de reanudación cuando se haya resuelto el problema. items conserva stepId, state, jobId y uri; recordInfo devuelve los enlaces de descarga de cada tarea.

spent_usd es el cargo real neto del saldo de la API, teniendo en cuenta los fondos devueltos. cost_usd es una estimación, no el cargo liquidado. Las respuestas en USD no contienen créditos enteros. Las ejecuciones históricas con créditos de la web conservan su moneda original y siguen disponibles en su flujo compatible de la web u OAuth.

Reanuda una ejecución pausada

Envía {} para obtener una nueva cotización:

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

Tras revisarla, repite la llamada con currency: "USD", max_usd y el nuevo quote_id. Este es el presupuesto total de toda la ejecución, incluidos los fondos gastados y los compromisos en curso, no un importe adicional. Las entradas y la cantidad originales no se pueden cambiar.

Reanudar no necesita Idempotency-Key. Las solicitudes simultáneas no pueden reanudar el trabajo dos veces; una ejecución ya reanudada devuelve un conflicto. Se mantienen la clave original, la cuenta de pago y el contexto de origen. Si cambia la política de IP de la clave, inicia una nueva ejecución desde un origen permitido en lugar de eludir la pausa.

Habilidades

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

GET /api/v1/skills lista tus habilidades y las compartidas con tus equipos. GET /api/v1/skills/{id} añade su body en Markdown. Una habilidad de equipo compartida como solo uso (shareMode: "use") no tiene body: funciona en PopNow mientras sus instrucciones permanecen ocultas.

En ChatGPT y Claude

Conecta el servidor MCP y pide «ejecuta mi receta Weekly post con esta foto». El asistente usa la cuenta de pago conectada, sin elegir entre saldos.

MCP con clave de API sigue las reglas anteriores de cotización en USD, confirmación, presupuesto total y uso de la misma clave. Confirmar run_my_recipe también requiere una cadena idempotency_key de 1–100 caracteres; cotizar no. Si se pierde la respuesta, reintenta con la misma clave y todos los mismos parámetros para recuperar la ejecución aceptada, aunque la receta o el precio hayan cambiado desde entonces. Usa una clave nueva solo para una ejecución aprobada por separado. Cambiar los parámetros con la misma clave devuelve un conflicto. OAuth mantiene las aprobaciones con max_credits en créditos de la web y rechaza los campos en USD. La herramienta de reanudación es para ejecuciones en USD con clave de API y no necesita una nueva clave de idempotencia; usa el estado de la ejecución original para evitar trabajo duplicado.

Límites y errores

Cada paso en USD vuelve a comprobar el estado y la caducidad de la clave, los permisos de modelos, los límites de gasto y el saldo de la API. El presupuesto incluye los fondos gastados, las retenciones en curso y el trabajo reservado; los reintentos técnicos también cuentan. Un cambio de precio de apenas $0.000000001 pausa la ejecución para pedir aprobación. El presupuesto total tiene un límite de $10,000, con $1,000 por paso.

¿Otras personas pueden ver o ejecutar mis recetas?

Solo tú y los equipos con los que compartes pueden acceder a los elementos guardados. No hay catálogo público ni acceso adivinando un ID. El prompt de una receta compartida nunca se devuelve a un compañero de equipo.

¿Quién paga cuando ejecuto una receta que compartió mi equipo?

Tú. Las ejecuciones con clave de API usan tu saldo de la API en USD; OAuth usa créditos de la web. Primero revisa la cotización y aprueba el presupuesto.

¿Tengo que subir mis archivos otra vez en cada ejecución?

No. Usa una URL https o una referencia popnow:// de un resultado, una subida o un recurso de la API. Las entradas omitidas reutilizan los archivos guardados.

¿Qué pasa cuando se retira el modelo que usaba una receta?

La ejecución no puede empezar. Abre la receta en popnow.ai, elige un modelo disponible y guárdala de nuevo; después solicita una nueva cotización.

¿Hay un SDK para recetas?

Usa estos ejemplos de JSON sobre HTTPS o un cliente HTTP, manteniendo los importes en USD como cadenas. No reutilices ejemplos antiguos de SDK que aprueban ejecuciones de recetas de la API con créditos enteros.

Relacionado