저장한 레시피, 워크플로, 스킬

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

항목 하나를 읽으면 저장된 파일을 기준으로 현재 견적을 확인할 수 있습니다.

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를 보내면 유효하지 않습니다. 금액이 0인 견적도 명시적인 승인이 필요합니다.

입력의 종류

파일에는 https URL, 이전 결과의 popnow://g/<job>/<n>, 업로드의 popnow://f/<file>, API 에셋의 popnow://a/<asset>를 사용할 수 있습니다. 생략한 입력은 저장된 파일을 재사용합니다. count는 레시피에서 1–4이며, 워크플로는 한 번만 실행됩니다. 잘못된 입력은 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가 있나요?

USD 금액을 문자열로 유지하면서 이 페이지의 HTTPS JSON 예제나 HTTP 클라이언트를 사용하세요. API 레시피 실행을 정수 크레딧으로 승인하는 예전 SDK 예제는 재사용하지 마세요.

관련 문서