PopNow API 동작 방식
API로 만들 수 있는 것, 모든 페이지의 바탕이 되는 다섯 가지 개념, 그리고 읽는 순서.
PopNow API를 쓰면 popnow.ai에서 쓰던 이미지·영상·오디오 모델을 내 소프트웨어에서도 쓸 수 있습니다. 모델도, 가격도, 크레딧도 같고, 브라우저에서 클릭하는 대신 코드로 호출할 뿐입니다.
만들 수 있는 것
| 결과물 | 예 |
|---|---|
| 이미지 | 텍스트로 이미지 만들기, 참조 이미지 하나 이상으로 편집, 업스케일, 배경 제거, 레이어 분리 |
| 영상 | 텍스트로 영상, 이미지로 영상, 첫·마지막 프레임 지정 영상, 참조 영상, 클립 이어 만들기와 편집, 립싱크, 말하는 아바타 |
| 오디오 | 음악, 효과음, 텍스트 음성 변환, 기존 영상에 사운드 입히기, 음성 텍스트 변환 |
전체 목록과 모델별 ID, 가격은 모델에 있습니다. API는 이미지·영상·오디오 생성만 다루며 채팅·텍스트 모델은 포함하지 않습니다.
어디서나 만나는 다섯 가지 개념
모델 ID
호출할 수 있는 것마다 <maker>/<model>/<task> 형태의 ID가 있습니다. 예: alibaba/wan-3.0/image-to-video, google/nano-banana-2.1/edit. 모든 요청의 model 필드에 넣습니다. 이미지 편집은 항상 /edit로 끝나며, 배경 제거처럼 PopNow가 직접 만든 도구는 maker가 popnow입니다.
작업
생성에는 몇 초에서 몇 분이 걸리므로 요청마다 작업이 만들어집니다. taskId는 바로 받고, 결과는 준비되면 읽습니다. 작업은 queued → running → 종료 상태(succeeded, failed, expired 중 하나)로 진행합니다. 자세한 내용은 작업을 보세요.
크레딧
API는 웹사이트와 같은 크레딧을 씁니다. 기준 요율로 1크레딧 = $0.01입니다. 작업이 접수되면 가능한 최고 금액을 잡아 두고, 끝나면 실제 금액(홀드 금액 이내)을 내고 나머지는 돌려받습니다. 실패한 작업은 무료입니다. 자세한 내용은 크레딧과 결제를 보세요.
멱등 키
네트워크 타임아웃만으로는 서버가 요청을 받았는지 알 수 없습니다. 작업을 만들 때마다 Idempotency-Key 헤더를 보내면, 같은 키로 재시도해도 두 번 만들고 두 번 과금하는 대신 원래 작업을 돌려받습니다. 자세한 내용은 멱등성을 보세요.
웹훅
작업을 계속 조회하는 대신 callBackUrl을 넘기세요. 작업이 끝나면 PopNow가 그 URL로 전체 결과를 보내며, 서명이 있어 PopNow에서 온 것인지 확인할 수 있습니다. 자세한 내용은 웹훅을 보세요.
요청의 모양
POST https://api.popnow.ai/api/v1/jobs/createTask
Authorization: Bearer sk-popnow-...
Idempotency-Key: 7d0c9a52-...
{ "model": "alibaba/wan-3.0/image-to-video",
"input": { "image_url": "https://…/photo.jpg", "prompt": "The waves roll in slowly" },
"callBackUrl": "https://your-app.example.com/hooks/popnow" }모든 응답은 { "code", "msg", "data", "request_id" }라는 하나의 형식을 쓰며 code: 200이 성공입니다.
읽는 순서
- 빠른 시작: 5분 만에 첫 결과.
- 인증: 키를 안전하게 지키고 할 수 있는 일을 제한하기.
- 모델: 모델을 고르고 파라미터 읽기.
- 작업과 웹훅: 전체 흐름.
- 미디어: 내 이미지·영상·오디오 보내기.
- 오류와 요청 제한: 출시 전에 꼭.
코드를 쓰기 전에 모델을 써 보고 싶다면, popnow.ai의 모델별 API 페이지에 있는 Playground를 쓰세요. 내 계정으로 바로 실행되며 키가 필요 없습니다.