Developers · API v1

One API.
Every model.

Images, video, audio and 3D behind one API, paid from the same balance as the studio. Create a key in Settings and install the CLI with npm.

Get an API keyQuickstart
Install the CLI
$ npm i -g pufy-io
Models
721
Endpoints
9
Minimum top-up
€3
Examples

Same call, any output

Swap the model ID to switch between image, video and speech. The fields follow the model.

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
Example renderluma/uni-v1/text-to-image
Quickstart

First render in three steps

  1. 1Create an API keyIn Settings > API keys, name a key and copy it once. Top up from €3 in Billing.export PUFY_API_KEY="YOUR_API_KEY"
  2. 2Install the CLIThe pufy command-line tool installs with npm, pnpm or bun.npm i -g pufy-io
  3. 3Make your first renderPick a model ID from the catalog and send a prompt. Add --dry-run to see the price without spending anything.pufy run luma/uni-v1/text-to-image -p "violet neon fox" -o ./out/
CLI

Render from the terminal

Run any model from a shell, a CI job or a coding agent. Every render is priced before it starts and drawn from the same balance.

Scripts and CIEvery field of a model is a flag; a local file is uploaded for you.
JSON on stdoutOne JSON document per run, progress and errors on stderr, a non-zero exit on failure.
Coding agentsA skill file teaches your agent to check the price first and cap it.
Full CLI guide →
CommandWhat it does
pufy loginPaste your API key once; it is checked and saved
pufy whoamiThe key's name and your balance
pufy models --type videoEvery video model with its starting price
pufy run <model> -hA model's fields, fetched live: type, default, allowed values
pufy run <model> -p "<prompt>" -o ./out/Render and save the result in a folder
pufy run <model> -p "..." --dry-runThe exact price, without spending anything
pufy run <model> -p "..." --max-price 0.50Refuse to run if the price is higher
pufy run <model> -p "..." --json -o ./out/One JSON result, ready for the next step
pufy skill installTeach your coding agent to use the CLI
API essentials

Built for production

Authentication

A Bearer token in the Authorization header. Create keys in Settings.

Authorization: Bearer YOUR_API_KEY

Background renders

Starting a render answers at once with status queued. Poll the render until it has succeeded, failed or been refunded.

{ "status": "queued" }

Price first

Ask for the exact price of your inputs without starting anything. Every amount is in euro cents.

POST /api/v1/api/catalog/quote

Safe retries

Send an Idempotency-Key header and a retried request never charges twice.

Idempotency-Key: render-042

Limits

Each key has a per-minute limit and an optional daily cap. Past the limit the API answers 429.

429 Too Many Requests

Errors and refunds

JSON errors with a code and a message. A render that fails is refunded to your balance automatically.

{ "status": "refunded" }
Reference

Endpoints

Base URL https://pufy.io/api/v1

Full API reference →
GET/api/catalog/meYour key and balance
GET/api/catalog/modelsEvery model
GET/api/catalog/models/detail?id=MODEL_IDOne model and its fields
POST/api/catalog/quotePrice for exact inputs
POST/api/catalog/generationsStart a render
GET/api/catalog/generationsYour recent renders
GET/api/catalog/generations/IDOne render's status
GET/api/catalog/generations/ID/contentThe result file
DELETE/api/catalog/generations/IDDelete a render

Top up €3 and start in the studio

Create an API key in Settings and call any model. Install the CLI with npm. Failed renders are refunded.

Get an API keySee pricing