fashn

FASHN API 与 SDK

FASHN 是一家以 AI 为先的公司，专注于面向时尚应用的人本生成式图像模型：虚拟试穿、AI 模型、产品摄影、编辑和图像转视频。所有操作都通过一个预测端点完成，该端点接收 model_name 和一个 inputs 对象。

此技能可帮助你完成两件事：

1. 将 FASHN 集成到项目中：针对 REST API、TypeScript SDK（npm 上的 fashn）或 Python SDK（PyPI 上的 fashn）编写生产代码。
2. 内联运行一次性生成：执行单次调用并将结果交给用户（参见内联快速入门）。

当用户要求将 FASHN 添加到其应用／代码库时，请进行集成（在其项目中编写代码）。当用户要求现在就试穿／生成图像时，请内联运行。

各端点的完整参数表、错误目录、Webhooks 和额度见 reference.md。需要获取特定 model_name 对应的准确 inputs 时，请加载该文件。

身份验证

• 从 Developer API 仪表板获取 API 密钥：https://app.fashn.ai/api
• 所有 FASHN 调用都在服务端进行：切勿将密钥硬编码或暴露在客户端。
• REST：发送 Authorization: Bearer $FASHN_API_KEY。默认情况下，两个 SDK 都会从环境中读取 FASHN_API_KEY。

查找密钥（按顺序检查；仅在全部失败时才询问用户）：

1. FASHN_API_KEY 环境变量（首选，集成代码、CI 和部署均使用此变量）。检查：echo "${FASHN_API_KEY:+set}"。
2. 缓存文件 ~/.fashn/.env。加载后重新检查：set -a; [ -f ~/.fashn/.env ] && . ~/.fashn/.env; set +a。
3. 否则，询问用户，然后缓存密钥（见下一条）。

缓存（仅用于内联调用）。 如果你必须向用户询问密钥，默认将其保存到 ~/.fashn/.env（收到后立即保存），以便后续内联运行时无需再次询问；然后告知用户密钥已缓存在此处，并说明可通过 rm ~/.fashn/.env 删除。用户拒绝时才跳过。运行：

umask 077; mkdir -p ~/.fashn; printf 'FASHN_API_KEY=%s\n' '<key>' > ~/.fashn/.env; chmod 600 ~/.fashn/.env

切勿回显密钥、将其写入 shell 配置文件或提交密钥。

**集成方式不同：**从项目自身的环境变量（已加入 gitignore 的 .env）或密钥管理器中读取密钥，切勿从 ~/.fashn/.env 或代码库中的任何位置读取。

核心概念（适用于所有路径）

一个端点，多种模型。 每个请求都是 { model_name, inputs }。可用的 model_name：

类别	model_name	必需输入
虚拟试穿（旗舰版）	tryon-max	model_image、product_image
虚拟试穿（旧版/快速）	tryon-v1.6	model_image、garment_image
商品 → 穿着商品的人像	product-to-model	product_image
根据提示词生成模特	model-create	prompt
更换模特身份	model-swap	model_image
头像 → 上半身虚拟形象	face-to-model	face_image
自由编辑	edit	image、prompt
更改纵横比（扩图/裁剪）	reframe	image、aspect_ratio
移除背景 → 透明 PNG	background-remove	image
图片 → 视频动画	image-to-video	image

预测生命周期。 有两种获取结果的方式：

• subscribe（推荐）：提交请求并自动轮询，直到进入终止状态，然后返回最终结果。两个 SDK 都提供此功能；使用原始 REST 时，需要自行实现轮询循环。
• 手动使用 run + status：run 会立即返回预测 id；轮询 status(id)，直到状态变为 completed/failed。适用于即发即弃、自建队列或配合网页钩子使用的场景。

响应封装。 终止状态下的预测结果如下：

{ "id": "...", "status": "completed", "output": ["https://cdn.fashn.ai/.../output_0.png"], "error": null }

• status：starting → in_queue → processing → completed | failed（SDK 的 subscribe 也可能返回 canceled / time_out）。
• output：CDN 图片 URL 数组（或 return_base64: true 时返回 base64）；image-to-video 返回 MP4 URL。
• error：成功时为 null，否则为 { name, message }。

积分。 消耗量会通过响应头 x-fashn-credits-used（REST）返回，也会作为结果中的 creditsUsed（TS）/ credits_used（Python）返回。失败的预测不会收费。 费用会随 generation_mode 和 resolution 变化；请参阅 reference.md。使用 GET /v1/credits 查看余额。

错误（两种类型）：

• API 错误（HTTP 4xx/5xx，在任务运行之前发生）：SDK 会抛出错误（APIError 子类）；REST 返回 { "error": "<Code>", "message": "..." }。
• 运行时错误（任务已运行但失败）：HTTP 200，且 status: "failed"，error: { name, message }，例如 ImageLoadError、ContentModerationError、PoseError。即使没有抛出异常，也始终要根据 status 分支处理。

限制： 批量处理时，遇到 429 响应应使用退避策略。

---

路径 A：TypeScript SDK（fashn）

在用户的项目中安装：npm install fashn

import Fashn from 'fashn';

const client = new Fashn(); // reads FASHN_API_KEY from env

// Recommended: submit + auto-poll to completion
const result = await client.predictions.subscribe({
  model_name: 'tryon-max',
  inputs: {
    model_image: 'https://example.com/person.jpg',
    product_image: 'https://example.com/garment.jpg',
  },
  // optional: pollInterval (ms, default 1000), timeout (ms, default 300000),
  onEnqueued: (id) => console.log('queued', id),
  onQueueUpdate: (s) => console.log('status', s.status),
});

if (result.status === 'completed') {
  console.log(result.output, 'credits:', result.creditsUsed);
} else {
  console.error('failed:', result.status, result.error?.name, result.error?.message);
}

手动生命周期：

const { id } = await client.predictions.run({ model_name: 'tryon-max', inputs: { /* ... */ } });
const status = await client.predictions.status(id); // poll until terminal

错误处理（API 错误与运行时错误）：

try {
  const r = await client.predictions.subscribe({ model_name: 'tryon-max', inputs: { /* ... */ } });
  if (r.status !== 'completed') console.error('runtime error:', r.error?.name, r.error?.message);
} catch (err) {
  if (err instanceof Fashn.APIError) console.error('API error:', err.status, err.message);
  else throw err;
}

路径 B：Python SDK（fashn）

在用户的项目中安装：pip install fashn

import fashn
from fashn import Fashn

client = Fashn()  # reads FASHN_API_KEY from env

result = client.predictions.subscribe(
    model_name="tryon-max",
    inputs={
        "model_image": "https://example.com/person.jpg",
        "product_image": "https://example.com/garment.jpg",
    },
)

if result.status == "completed":
    print(result.output, "credits:", result.credits_used)
else:
    print("failed:", result.status, result.error)

手动生命周期：client.predictions.run(...) → client.predictions.status(prediction_id)。 异步：使用 from fashn import AsyncFashn 和 await client.predictions.subscribe(...)。 API 错误会抛出 fashn.APIError（e.status_code、e.message）；运行时错误会以 result.status == "failed" 和 result.error 的形式返回。

路径 C：REST（任意语言）

基础 URL：https://api.fashn.ai/v1。提交请求，然后轮询。

# Submit → returns {"id": "...", "error": null}
curl -s -X POST https://api.fashn.ai/v1/run \
  -H "Authorization: Bearer $FASHN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_name":"tryon-max","inputs":{
        "model_image":"https://example.com/person.jpg",
        "product_image":"https://example.com/garment.jpg"}}'

# Poll → repeat until status is "completed" or "failed"
curl -s https://api.fashn.ai/v1/status/<id> -H "Authorization: Bearer $FASHN_API_KEY" -i
#   read x-fashn-credits-used from the response headers

# Balance
curl -s https://api.fashn.ai/v1/credits -H "Authorization: Bearer $FASHN_API_KEY"

网页钩子（跳过轮询）：在 /run 后追加 ?webhook_url=。FASHN 会将终止状态的负载（completed/failed）POST 到该 URL，约 5 分钟内最多重试 5 次。没有签名请求头，因此请确保处理程序具备幂等性，并快速返回 2xx。详情请参阅 reference.md。

---

内联快速入门

对于一次性生成（而非集成），请在 ~/.fashn 中运行 TS SDK，以免改动用户的项目：

1. 如有需要，请安装：ls ~/.fashn/node_modules/fashn 2>/dev/null || npm install --prefix ~/.fashn fashn
2. 获取密钥：[ -z "$FASHN_API_KEY" ] && { set -a; . ~/.fashn/.env 2>/dev/null; set +a; }。如果仍未设置，请参阅身份验证。
3. 运行代码。通过单引号 heredoc 管道传入脚本，这样 shell 就不会处理反引号、$ 和引号；并先执行 cd ~/.fashn，以便 ESM 解析 fashn 导入（它会忽略 NODE_PATH）：

[ -z "$FASHN_API_KEY" ] && { set -a; . ~/.fashn/.env 2>/dev/null; set +a; }
cd ~/.fashn && node --input-type=module <<'NODE'
import Fashn from 'fashn';
const r = await new Fashn().predictions.subscribe({
  model_name: 'tryon-max',
  inputs: {
    model_image: 'https://example.com/person.jpg',
    product_image: 'https://example.com/garment.jpg',
  },
  timeout: 120000, // ms
});
if (r.status !== 'completed') { console.error('Failed:', r.status, r.error); process.exit(1); }
console.log(JSON.stringify({ output: r.output, creditsUsed: r.creditsUsed }, null, 2));
NODE

• 本地图片输入：将文件读取为 base64（使用 node:fs/promises 中的 readFile(path, { encoding: 'base64' })），并将其作为 product_image: 'data:image/jpeg;base64,' + b64 传入。使用 fetch(r.output[0]) 保存结果。
• 不要创建脚本文件，也不要将密钥放在命令行中（使用步骤 2 的缓存）；批量处理时遇到 429 请退避。

参考

请参阅 reference.md，了解每个端点的完整 inputs（类型、允许值、默认值）、完整错误目录、额度和定价说明、webhook 负载以及速率限制。

用户的请求

$ARGUMENTS