fashn

FASHN API および SDK

FASHN は、バーチャルトライオン、AI モデル、商品写真、画像編集、画像から動画への変換といったファッション用途に特化した、人間中心の生成画像モデルを提供する AI ファーストの企業です。すべての処理は、model_name と inputs オブジェクトを受け取る単一の予測エンドポイントを通じて実行されます。

このスキルでは、次の 2 つを行えます。

1. プロジェクトに FASHN を統合する：REST API、TypeScript SDK（npm の fashn）、または Python SDK（PyPI の fashn）を使用する本番コードを記述します。
2. 単発の生成をその場で実行する：1 回だけ呼び出しを実行し、結果をユーザーに返します（インラインクイックスタートを参照）。

ユーザーが FASHN をアプリ／リポジトリに追加してほしい と依頼した場合は、統合します（プロジェクトにコードを書き込みます）。トライオンだけしたい／今すぐ画像を生成したい と依頼した場合は、その場で実行します。

エンドポイントごとの詳細なパラメーター表、エラーカタログ、ウェブフック、クレジットについては 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

キーを表示したり、シェルプロファイルに書き込んだり、コミットしたりしないでください。

統合では扱いが異なります：キーはプロジェクト固有の環境変数（Git の追跡対象外である .env）またはシークレットマネージャーから取得してください。~/.fashn/.env やリポジトリ内のどこからも取得しないでください。

コアコンセプト（すべてのパスに適用）

1 つのエンドポイントで複数のモデルを利用できます。 すべてのリクエストは { 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

予測のライフサイクル。 結果を取得する方法は 2 つあります。

• subscribe（推奨）：リクエストを送信し、終端状態になるまで自動でポーリングしてから、最終結果を返します。どちらの SDK でも利用できます。REST を直接使用する場合は、自分でポーリングループを実装します。
• 手動の run + status：run は予測 id をすぐに返します。completed／failed になるまで status(id) をポーリングします。通知を待たずに処理する場合、独自のキューを使用する場合、または webhooks と組み合わせる場合に使用します。

レスポンスのエンベロープ。 終端状態の予測は次のようになります。

{ "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 で残高を確認できます。

エラー（2 種類）：

• 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"

Webhooks（ポーリングを省略）：/run に ?webhook_url= を追加します。FASHN は終端ペイロード（completed／failed）をその URL に POST し、約 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. 実行します。スクリプトはシングルクォートのヒアドキュメント経由でパイプしてください。そうするとシェルがバッククォート／$／引用符をそのまま扱います。また、ESM が fashn のインポートを解決できるよう、最初に cd ~/.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 が発生した場合は、処理を控えめにしてください。

リファレンス

各エンドポイントの完全な inputs（型、許可される値、デフォルト）、エラーの全カタログ、クレジット／料金に関する注意事項、Webhook ペイロード、レート制限については、reference.md を参照してください。

ユーザーのリクエスト

$ARGUMENTS