개발자 · API v1

하나의 API.
모든 모델.

이미지, 영상, 오디오, 3D를 하나의 API로, 스튜디오와 같은 잔액으로 결제합니다. 키는 설정에서 만들 수 있고, CLI는 npm으로 설치할 수 있습니다.

API 키 받기 빠른 시작

CLI 설치

$ npm i -g pufy-io

모델: 721
엔드포인트: 9
최소 충전액: €3

예제

같은 호출, 어떤 결과든

모델 ID만 바꾸면 이미지, 동영상, 음성 사이를 전환할 수 있습니다. 필드는 모델에 따라 달라집니다.

1# 1. Generate an image2curl -X POST https://pufy.io/api/v1/api/catalog/generations \3  -H "Authorization: Bearer $PUFY_API_KEY" \4  -H 'Content-Type: application/json' \5  -H "Idempotency-Key: $(uuidgen)" \6  -d '{7  "modelId": "luma/uni-v1/text-to-image",8  "inputs": {9    "prompt": "Neon city street after rain, cinematic night",10    "size": "16:9"11  }12}'13 14# 2. Poll with the generation id from step 1 until its status is succeeded15curl https://pufy.io/api/v1/api/catalog/generations/$ID \16  -H "Authorization: Bearer $PUFY_API_KEY"17 18# 3. Download the file19curl https://pufy.io/api/v1/api/catalog/generations/$ID/content \20  -H "Authorization: Bearer $PUFY_API_KEY" \21  -o result.jpeg

빠른 시작

세 단계로 첫 렌더

1API 키 만들기설정 > API 키에서 키 이름을 짓고 한 번 복사하세요. 결제에서 €3부터 충전하세요.export PUFY_API_KEY="YOUR_API_KEY"
2CLI를 설치하세요명령줄 도구 pufy는 npm, pnpm, bun으로 설치할 수 있습니다.npm i -g pufy-io
3첫 렌더 실행카탈로그에서 모델 ID를 고르고 프롬프트를 보내세요. --dry-run을 붙이면 비용 없이 가격만 확인합니다.pufy run luma/uni-v1/text-to-image -p "violet neon fox" -o ./out/

CLI

터미널에서 렌더

셸, CI 작업, 코딩 에이전트에서 어떤 모델이든 실행하세요. 모든 렌더는 시작 전에 가격이 정해지고 같은 잔액에서 차감됩니다.

스크립트와 CI모델의 모든 필드가 플래그가 되고, 로컬 파일은 자동으로 업로드됩니다.

stdout으로 JSON실행마다 JSON 문서 하나, 진행 상황과 오류는 stderr로, 실패 시 0이 아닌 종료 코드.

코딩 에이전트스킬 파일이 에이전트에게 먼저 가격을 확인하고 상한을 두도록 알려 줍니다.

CLI 전체 가이드 →

명령어기능

pufy loginAPI 키를 한 번만 붙여 넣으면 확인 후 저장됩니다

pufy whoami키 이름과 내 잔액

pufy models --type video모든 동영상 모델과 시작 가격

pufy run <model> -h실시간으로 가져온 모델 필드: 타입, 기본값, 허용 값

pufy run <model> -p "<prompt>" -o ./out/렌더하고 결과를 폴더에 저장

pufy run <model> -p "..." --dry-run비용 없이 정확한 가격 확인

pufy run <model> -p "..." --max-price 0.50가격이 더 높으면 실행 거부

pufy run <model> -p "..." --json -o ./out/다음 단계에 바로 쓸 수 있는 JSON 결과

pufy skill install코딩 에이전트에게 CLI 사용법 가르치기

API 핵심

프로덕션을 위한 설계

인증

Authorization 헤더의 Bearer 토큰입니다. 키는 설정에서 만드세요.

Authorization: Bearer YOUR_API_KEY

백그라운드 렌더

렌더를 시작하면 즉시 queued 상태로 응답합니다. 성공, 실패 또는 환불될 때까지 렌더를 폴링하세요.

{ "status": "queued" }

가격 먼저

아무것도 시작하지 않고 입력값의 정확한 가격을 조회하세요. 모든 금액은 유로 센트 단위입니다.

POST /api/v1/api/catalog/quote

안전한 재시도

Idempotency-Key 헤더를 보내면 재시도한 요청이 두 번 청구되지 않습니다.

Idempotency-Key: render-042

한도

키마다 분당 한도와 선택적인 일일 상한이 있습니다. 한도를 넘으면 API가 429로 응답합니다.

429 Too Many Requests

오류와 환불

코드와 메시지가 담긴 JSON 오류. 실패한 렌더는 자동으로 잔액에 환불됩니다.

{ "status": "refunded" }

레퍼런스

엔드포인트

기본 URL https://pufy.io/api/v1

전체 API 레퍼런스 →

GET/api/catalog/me내 키와 잔액

GET/api/catalog/models전체 모델

GET/api/catalog/models/detail?id=MODEL_ID모델 하나와 해당 필드

POST/api/catalog/quote정확한 입력값의 가격

POST/api/catalog/generations렌더링 시작

GET/api/catalog/generations최근 렌더링 목록

GET/api/catalog/generations/ID렌더링 하나의 상태

GET/api/catalog/generations/ID/content결과 파일

DELETE/api/catalog/generations/ID렌더링 삭제

€3 충전하고 스튜디오에서 시작하세요

설정에서 API 키를 만들고 어떤 모델이든 호출하세요. CLI는 npm으로 설치할 수 있습니다. 실패한 렌더는 환불됩니다.

API 키 받기 가격 보기

하나의 API. 모든 모델.