upres-cli

upres-cli

如果 UpRes 对你有帮助，请为此仓库点个星。

upres.ai 的官方 CLI + SDK，用于图像、视频和语音修复。一个 API，提供 14 个公开别名，最高支持 8K 输出。

$ upres upscale photo.jpg --model flare --scale 4
Submitting job... model=flare
Job created: 550e8400-e29b-41d4-a716-446655440000 (status: pending)
Waiting for result.......
Downloading to photo_upscaled.jpg... done.

Result: photo_upscaled.jpg

---

我们为什么构建它

• Topaz 每年收费 200 美元，仅支持桌面端，没有 API，也无法自动化
• Upscayl 很适合处理零星任务，但无法处理批量导出或 CI 流水线
• 其他所有 SaaS 放大工具要么会给输出添加水印，要么将分辨率限制在 2K，要么按图收费且没有月度套餐

upres.ai 提供简洁的 REST API、14 个公开别名和批处理功能，Creator 上线优惠价格从每月 9 美元起，费用清晰可预测。

---

快速入门

Node.js

npx upres-cli upscale photo.jpg

也可以全局安装：

npm install -g upres-cli
upres upscale photo.jpg --model lumen --scale 8 --output photo_8k.jpg

Python

pip install upres-ai
upres upscale photo.jpg --model flare --scale 4

---

身份验证

1. 在 upres.ai 注册（免费，每月可放大 5 次）
2. 前往 upres.ai/account/api-keys
3. 生成密钥——它只会显示一次

export UPRES_API_KEY=upres_yourkey

也可以永久保存：

mkdir -p ~/.config/upres
echo '{"apiKey":"upres_yourkey"}' > ~/.config/upres/config.json

密钥的读取顺序：--api-key 标志 → UPRES_API_KEY 环境变量 → ~/.config/upres/config.json

---

命令

# Upscale a single image (local file or URL)
upres upscale photo.jpg --model flare --scale 4
upres upscale photo.jpg --model lumen --scale 8 --output out.jpg
upres upscale https://example.com/photo.jpg --model prism

# Upscale video (AI-generated video from Sora, Kling, Runway etc.)
upres upscale clip.mp4 --model motion --scale 4

# Batch upscale a folder
upres batch ./photos/ --model flare --output ./upscaled/ --concurrency 5

# List available models
upres models

# List recent jobs
upres jobs --limit 20 --status completed

# Account / quota info
upres account

---

Node.js SDK

import { UpresClient } from "upres-cli";

const client = new UpresClient(); // reads UPRES_API_KEY from env

// Upscale a local file
const job = await client.createJobFromFile("photo.jpg", {
  model: "flare",
  scale: 4,
});

// Wait for completion
const completed = await client.waitForJob(job.id);

// Download result
await client.downloadResult(completed, "photo_4k.jpg");
console.log("Done:", completed.result_url);

超过 50 MB 的文件会自动通过 TUS 可续传协议上传。

---

Python SDK

from upres import UpresClient

with UpresClient() as client:                        # reads UPRES_API_KEY from env
    job = client.create_job_from_file(
        "photo.jpg",
        model="flare",
        scale=4,
    )
    completed = client.wait_for_job(job["id"])
    client.download_result(completed, "photo_4k.jpg")
    print("Done:", completed["result_url"])

Python SDK 使用 httpx，支持异步且没有繁重的依赖。

---

示例

示例	功能
batch-upscale-folder.js	以可配置的并发数放大文件夹中的所有图像
restore-photo-folder.py	使用 Lumen 修复老照片或扫描照片
ecommerce-pipeline.js	产品图像工作流：原始照片 → 4K → 可发布成品
lightroom-export-hook.md	通过后处理钩子自动放大 Lightroom 导出内容
figma-plugin-stub.md	Figma 插件集成指南

---

模型

图像、视频和语音领域共提供 14 个公开别名。每个别名都会预先说明它是会生成新细节，还是保持文件原样。不放大图像的别名会忽略 --scale。

别名	类型	适用场景
flare	图像	日常照片，速度最快的默认选项
prism	图像	文字、徽标、产品照片——保持边缘准确
lumen	图像	最大程度恢复细节，适用于打印，最高支持 8 倍放大
mirage	图像	生成新细节——适用于艺术作品和主视觉图像
hush	图像	忠实降噪，尺寸与源文件相同
keen	图像	去模糊和锐化，尺寸不变
visage	图像	仅处理人脸，不放大
atelier	图像	先用 Hush；如果是肖像，再用 Visage；然后用 Lumen
motion	视频	为 AI 视频快速处理成 4K
motion-x	视频	影院级效果，适用于电影和广告
still	视频	时域降噪，分辨率保持不变
cadence	视频	帧插值，不放大
atelier-x	视频	先用 Still，再用 Motion X
voice	语音	语音降噪至 48 kHz，不适用于音乐

完整模型目录：upres.ai/models · 实时规格：api.upres.ai/v1/openapi.json

---

定价

套餐	价格	包含内容	API	水印
免费版	$0	每月 5 次放大	—	有
创作者版	$9/mo	每月 50 张静态图 + 20 分钟 4K 视频	—	无
工作室版	$39/mo	每月 250 张静态图 + 90 分钟 4K 视频	有	无

工作室版可解锁完整 API、批量处理功能，并且输出内容不带水印。

比较套餐 → · 与 Topaz 比较 → · 与 Upscayl 比较 →

---

MCP（Claude、Cursor、Hermes）

claude mcp add upres -- npx -y github:auroracapital/upres-cli mcp

或者在 claude_desktop_config.json / Cursor 中：

{
  "mcpServers": {
    "upres": {
      "command": "npx",
      "args": ["-y", "github:auroracapital/upres-cli", "mcp"],
      "env": { "UPRES_API_KEY": "upres_yourkey" }
    }
  }
}

工具：upres_list_models、upres_get_credits、upres_upscale_image、upres_upscale_video、upres_enhance_audio、upres_get_job。

---

面向开源项目的免费套餐

如果你正在基于 API 构建开源项目，请通过 [email protected] 发送邮件，并附上你的代码仓库链接。符合条件的开源软件项目每月可获得 500 次操作。

---

错误处理

SDK 会自动处理以下错误：

状态	行为
401	打印 API 密钥错误和密钥管理链接，然后退出
402	打印配额已用尽提示和定价链接，然后退出
429	打印速率限制提示（60 次请求/分钟），然后退出
5xx	抛出带有错误消息的 UpresError

在 Python 中：会抛出 AuthError、QuotaExceededError 或 UpresError。

---

贡献

请参阅 CONTRIBUTING.md。运行测试的命令：

# Node
npm test

# Python
pip install -e ".[dev]"
pytest tests/test_client.py -v

---

许可证

MIT — 请参阅 LICENSE