# loom

一个账号，无需 API Key。视频生成、图片生成、LLM 对话，一条命令全搞定。

loom 是一个多模态 AI 生成聚合平台。用户只需邮箱验证码登录，即可调用多个供应商的模型能力，按点数计费。不需要向任何供应商注册账号，也不需要创建和管理 API Key。

## 快速开始

### 安装

```bash
npm install -g loomgen
```

### 登录

```bash
loom login
```

终端显示 6 位授权码，自动打开浏览器。输入邮箱，收验证码，点击授权。回到终端自动拿到 token。

### 验证

```bash
loom whoami       # 查看身份和余额
loom balance      # 查看余额和已用
loom model list   # 查看可用模型和价格
```

## 全量功能

### 文本对话

```bash
# 默认模型
loom chat "用一句话介绍你自己"

# 指定模型
loom chat "写首诗" -m claude-sonnet-4-6
loom chat "分析数据" -m deepseek-v4-pro

# 流式输出
loom chat "写代码" --stream

# 带系统提示
loom chat "翻译" --system "你是翻译助手"

# 管道输入
echo "总结这段话" | loom chat

# 多轮对话
loom chat --message "user: 推荐三本书" --message "assistant: ..." --message "user: 为什么"
```

可用 Chat 模型：`doubao-seed-1-6`、`claude-fable-5`、`claude-opus-4-8`、`claude-sonnet-4-6`、`claude-haiku-4-5`、`deepseek-v4-pro`、`deepseek-v4-flash`、`glm-5.2`、`kimi-k3`、`qwen3.8-max`、`qwen3.8-flash`

### 视频生成

```bash
# 异步提交，立即返回 task_id
loom gen video --async "一只金色的猫在夕阳下的屋顶上行走"

# 同步等待完成
loom gen video "夕阳下的海浪" --output-path output.mp4

# 指定参数
loom gen video --async "prompt" -m doubao-seedance-2-0 --ratio 16:9 --duration 5

# 费用估算
loom gen video "prompt" --dry-run
```

可用 Video 模型：`doubao-seedance-1-5-pro`、`doubao-seedance-2-5`、`doubao-seedance-2-0`、`doubao-seedance-2-0-fast`

### 图片生成

```bash
# 异步提交
loom gen image --async "一只金色的猫"

# 同步生成并下载
loom gen image "prompt" --output-path output.png

# 指定尺寸和数量
loom gen image "prompt" --size 1024x1024 --count 2

# 费用估算
loom gen image "prompt" --dry-run
```

可用 Image 模型：`doubao-seedream-4-0`、`doubao-seedream-5-0-pro`、`doubao-seedream-5-0-pro-layer`、`wan2.7-image-pro`、`z-image-turbo`

### 任务状态查询

```bash
loom gen status <task_id>
```

返回状态：`QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。成功时返回 `video_url` 或 `result_url`，失败时返回 `fail_reason`。

### 下载

```bash
loom download <url> <output_path>
```

### 账户管理

```bash
loom login                  # 登录
loom logout                 # 登出
loom whoami                 # 身份和余额
loom balance                # 余额详情
loom billing topup          # 打开充值页
loom billing history        # 充值和消费记录
```

### 配置

```bash
# 多环境 profile
loom config profile add <name> --api https://loom.firstapi.ai
loom config profile list
loom config profile use <name>
loom config profile delete <name>

# 全局设置
loom config get
loom config set timeout 60000
```

环境变量：

```bash
LOOM_API=https://loom.firstapi.ai   # 自定义 API 地址
LOOM_PROFILE=work                   # 默认 profile
```

### BYOK 模式

用自己的 key 直连供应商，不扣 loom credits：

```bash
loom chat "hello" --api-key sk-xxx --base-url https://api.openai.com
loom gen image "prompt" --api-key sk-xxx --base-url https://api.openai.com
```

### Agent 模式

```bash
# JSON 输出，方便 Agent 解析
loom --output json chat "hello"
loom --output json gen video --async "prompt"
loom --output json gen status <task_id>
loom --output json balance

# 安装 Codex / Claude 技能包
loom skill install
loom skill path
```

网络诊断（代理 / fake-ip 问题排查）：

```bash
loom doctor
```

## 模型价格

以点数展示，1 元人民币 = 1 点。文本模型按 token 计费，生成模型按次计费。

### Claude 系列

| 模型 | 输入（点/MTok） | 输出（点/MTok） |
|------|----------------:|----------------:|
| claude-fable-5 | 580 | 2900 |
| claude-opus-4-8 | 290 | 1450 |
| claude-opus-4-7 | 290 | 1450 |
| claude-opus-4-6 | 290 | 1450 |
| claude-sonnet-4-6 | 174 | 870 |
| claude-haiku-4-5 | 58 | 290 |

### 其他 Chat 模型

| 模型 | 输入（点/MTok） | 输出（点/MTok） |
|------|----------------:|----------------:|
| deepseek-v4-pro | 696 | 1392 |
| deepseek-v4-flash | 58 | 116 |
| glm-5.2 | 464 | 1624 |
| kimi-k3 | 171 | 853 |
| qwen3.8-max | 116 | 348 |
| qwen3.8-flash | 9 | 27 |
| doubao-seed-1-6 | 按次 | 5 点/次 |

### 视频模型（按次）

| 模型 | 价格 |
|------|------|
| doubao-seedance-2-5 | 33.6 点起 |
| doubao-seedance-2-0 | 23.1 点起 |
| doubao-seedance-2-0-fast | 18.6 点起 |
| doubao-seedance-1-5-pro | 19.25 点起 |

### 图片模型（按次）

| 模型 | 价格 |
|------|------|
| doubao-seedream-5-0-pro | 3 点起 |
| doubao-seedream-5-0-pro-layer | 1.5 点起 |
| wan2.7-image-pro | 4.35 点 |
| z-image-turbo | 1.74 点 |

实时价格请查看：

```bash
loom model list
```

或访问网页 [https://loom.firstapi.ai/pricing](https://loom.firstapi.ai/pricing)

## 网页 Dashboard

地址：[https://loom.firstapi.ai](https://loom.firstapi.ai)

功能：

| 页面 | 说明 |
|------|------|
| 登录 | 邮箱验证码，无需密码 |
| 概览 | 余额、最近生成、快捷入口 |
| 生成工作台 | 网页提交视频/图片生成 |
| 钱包 | 充值（微信/支付宝）、余额 |
| 账单流水 | 按时间筛选消费和充值记录 |
| 模型价格 | 所有模型点数价格 |
| 个人中心 | 邮箱、登录设备、退出 |

## 计费体系

- 1 元人民币 = 1 点 = 500,000 quota
- 文本模型按 token 计费，展示输入/输出单价
- 生成模型按次计费，失败自动全额退款
- 所有扣费有 append-only 账本记录，可对账
- 余额不足时提示充值

## 技术架构摘要

```text
CLI (TypeScript / npm loomgen)
  ↕ HTTPS + JWT
Nginx (TLS)
  ↕
loom-api (Go / port 3000)
  ↕
PostgreSQL + Redis
  ↕
上游供应商（火山引擎 / ClaudeCC 聚合器）
```

认证流程：

1. CLI 生成 PKCE code_verifier + code_challenge
2. 打开浏览器 `/sign-in?user_code=xxx`
3. 用户输入邮箱 → 收验证码 → 授权
4. CLI 轮询拿到 access_token（JWT，1h）+ refresh_token（7d）
5. 后续请求用 `Authorization: Bearer <JWT>`

## 常见问题

### 登录后一直等待

先在浏览器打开 [https://loom.firstapi.ai](https://loom.firstapi.ai) 登录，再运行 `loom login`。已登录时会自动完成授权。

### 网络错误 / fetch failed

运行 `loom doctor` 检查。常见原因：代理工具 fake-ip 模式劫持 DNS。参考 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)。

### 图片/视频生成返回 FAILURE

运行 `loom gen status <task_id>` 查看 `fail_reason`。如果提示余额不足，上游供应商额度耗尽，充值后重试。loom 侧失败会自动退款。

### 如何更新

```bash
loom update
# 或
npm install -g loomgen@latest
```

## 相关文档

| 文件 | 说明 |
|------|------|
| [LOOM_GUIDE.md](./LOOM_GUIDE.md) | 完整功能全景和用户历程 |
| [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) | 网络问题排查 |
| [TODO.md](./TODO.md) | 待办事项 |
| [skills/loom-cli/SKILL.md](./skills/loom-cli/SKILL.md) | AI Agent 技能包 |