Suas receitas, fluxos e skills

Reutilize o que você salvou no popnow.ai: uma receita salva no Studio com modelo, prompt, configurações e arquivos; um fluxo do canvas cujas etapas usam resultados anteriores; ou uma skill Poppie com instruções que outro assistente pode seguir.

Os itens são privados para você e as equipes com quem você os compartilha. O prompt da receita de um colega não é devolvido; o servidor o monta na hora da execução. Execuções REST e MCP com chave de API usam seu saldo separado da API em USD. Execuções MCP com OAuth usam créditos do site. Os saldos não podem ser transferidos nem usados um no lugar do outro. Novos saldos da API começam em $0; adicione fundos em API billing.

Visão geral

Encontre o que você pode executar

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

Omita kind para listar receitas e fluxos. Seus itens aparecem primeiro, seguidos dos compartilhados com suas equipes (mine: false, com teamId). Cada item descreve suas 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"
    }]
  }
}

Leia um item para obter a estimativa atual com os arquivos salvos:

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

Os metadados da API usam currency: "USD" e, opcionalmente, estimated_usd, sem estimatedCredits. Essa estimativa não aprova a execução: envie as entradas reais para POST /run para obter um quote_id.

Execute

Primeiro envie as entradas e a quantidade pretendidas sem campos de aprovação. Uma cotação não cria execução nem reserva fundos; ela não precisa de 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
  }
}

Depois de revisar e aprovar o valor, repita as mesmas entradas e quantidade com currency: "USD", max_usd como string decimal e o quote_id recebido. A execução exige um Idempotency-Key de 1–100 caracteres; reutilize essa chave ao repetir o mesmo envio.

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

Um início bem-sucedido retorna needs_confirmation: false, run_id, state e o max_usd aprovado. Se o preço ultrapassar o limite ou a cotação não corresponder mais, a resposta traz needs_confirmation: true e uma nova cotação; nenhuma execução é iniciada. Mostre o novo valor e peça aprovação novamente. HTTP 200 por si só não significa que o trabalho começou.

max_usd é uma string decimal não negativa com até nove casas decimais. Números JSON, valores negativos, notação exponencial, campos desconhecidos e aprovações antigas com maxCredits / max_credits são rejeitados, não convertidos. Enviar max_usd sem quote_id é inválido. Mesmo uma cotação de preço zero exige aprovação explícita.

Quais são as entradas

Os arquivos podem ser uma URL https, popnow://g/<job>/<n> de um resultado anterior, popnow://f/<file> de um upload ou popnow://a/<asset> de um asset da API. Entradas omitidas reutilizam os arquivos salvos. count aceita 1–4 para receitas; fluxos rodam uma vez. Entradas inválidas retornam 400 com param: inputs.<id>.

Um fluxo pode precisar de um resultado anterior para que o preço de uma etapa seja calculado. Nesse caso, a cotação inclui unpriced_steps: cost_usd cobre apenas as etapas com preço já calculado, não o fluxo completo. Etapas sem preço calculado não podem ser executadas. Quando suas entradas estiverem prontas, a execução pausa para obter uma nova cotação de retomada e aprovação. Não ter preço calculado não significa ser grátis.

Acompanhe uma execução

Use a mesma chave de API que iniciou a execução. Outra chave da mesma conta não pode ler nem retomar essa execução. Consultas de status com chave de API não reinterpretam como USD uma execução OAuth em 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 é draft, running, paused, done, stopped ou failed. Consulte periodicamente enquanto for draft ou running. Para paused, examine pause_reason e obtenha uma cotação de retomada quando o problema estiver resolvido. items mantém stepId, state, jobId e uri; recordInfo retorna os links de download de cada tarefa.

spent_usd é a cobrança real líquida da carteira da API, considerando os fundos devolvidos. cost_usd é uma estimativa, não a cobrança liquidada. Respostas em USD não contêm créditos inteiros. Execuções históricas com créditos do site mantêm a moeda original e continuam no fluxo compatível do site ou do OAuth.

Retome uma execução pausada

Envie {} para obter uma nova cotação:

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

Depois de revisar, repita com currency: "USD", max_usd e o novo quote_id. Esse é o orçamento total da execução inteira, incluindo fundos gastos e compromissos em andamento, não um valor adicional. As entradas e a quantidade originais não podem mudar.

A retomada não exige Idempotency-Key. Requisições simultâneas não podem retomar o trabalho duas vezes; uma execução já retomada retorna um conflito. A chave original, a conta de pagamento e o contexto de origem continuam vinculados. Se a política de IP da chave mudar, inicie uma nova execução de uma origem permitida em vez de contornar a pausa.

Skills

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

GET /api/v1/skills lista suas skills e as compartilhadas com suas equipes. GET /api/v1/skills/{id} acrescenta o body delas em Markdown. Uma skill de equipe compartilhada como somente uso (shareMode: "use") não tem body: ela funciona no PopNow enquanto suas instruções ficam ocultas.

No ChatGPT e no Claude

Conecte o servidor MCP e peça “execute minha receita Weekly post com esta foto”. O assistente usa a conta de pagamento conectada, sem escolher entre carteiras.

O MCP com chave de API segue as regras acima de cotação em USD, confirmação, orçamento total e uso da mesma chave. Confirmar run_my_recipe também exige uma string idempotency_key de 1–100 caracteres; cotar não. Se a resposta se perder, tente novamente com a mesma chave e todos os mesmos parâmetros para recuperar a execução aceita, mesmo que a receita ou o preço tenham mudado desde então. Use uma chave nova apenas para uma execução aprovada separadamente. Alterar os parâmetros com a mesma chave retorna um conflito. OAuth mantém aprovações com max_credits em créditos do site e rejeita campos em USD. A ferramenta de retomada é para execuções em USD com chave de API e não exige uma nova chave de idempotência; ela usa o estado da execução original para evitar trabalho duplicado.

Limites e erros

Cada etapa em USD verifica novamente o status e a validade da chave, as permissões de modelos, os limites de gasto e o saldo da API. O orçamento inclui fundos gastos, reservas em andamento e trabalho reservado; novas tentativas técnicas também contam. Uma mudança de preço de apenas $0.000000001 pausa a execução para aprovação. O orçamento total é limitado a $10,000, com $1,000 por etapa.

Outras pessoas podem ver ou executar minhas receitas?

Só você e as equipes com quem você compartilha podem acessar os itens salvos. Não há catálogo público nem acesso por adivinhação de ID. O prompt de uma receita compartilhada nunca é devolvido a um colega de equipe.

Quem paga quando eu executo uma receita que minha equipe compartilhou?

Você. Execuções com chave de API usam sua carteira da API em USD; OAuth usa créditos do site. Primeiro revise a cotação e aprove o orçamento.

Preciso enviar meus arquivos de novo a cada execução?

Não. Use uma URL https ou uma referência popnow:// de um resultado, upload ou asset da API. Entradas omitidas reutilizam os arquivos salvos.

O que acontece quando o modelo usado por uma receita é desativado?

A execução não pode começar. Abra a receita no popnow.ai, escolha um modelo disponível e salve de novo; depois solicite uma nova cotação.

Existe um SDK para receitas?

Use estes exemplos de JSON sobre HTTPS ou um cliente HTTP, mantendo USD como strings. Não reutilize exemplos antigos de SDK que aprovam execuções de receitas da API com créditos inteiros.

Relacionados