开发者 · 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

快速开始

三步完成首次生成

1创建 API 密钥在设置 > API 密钥中为密钥命名并复制一次。在账单中充值 €3 起。export PUFY_API_KEY="YOUR_API_KEY"
2安装 CLI命令行工具 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

在终端中生成

从 shell、CI 任务或编程智能体运行任意模型。每次生成在开始前都会报价,并从同一个余额中扣除。

脚本与 CI模型的每个字段都是一个参数;本地文件会自动为你上传。

stdout 输出 JSON每次运行输出一个 JSON 文档,进度和错误写入 stderr,失败时返回非零退出码。

编程智能体一个技能文件教你的智能体先查价格,并设定上限。

完整 CLI 指南 →

命令作用

pufy login粘贴一次 API 密钥,验证后即保存

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。 所有模型。