FASHN

https://docs.fashn.ai
Admin
FASHN is an AI-powered platform providing fashion-focused image generation, virtual try-on, model...
Tokens:62,700
Snippets:523
Trust Score:7.9
Update:4 days ago
Show doc for...
Tokens:
Raw
### Python Quickstart

Source: https://docs.fashn.ai/llms-full.txt

A quick guide to using the FASHN try-on API with Python.

```APIDOC
## Python Quickstart

### Description
A quick guide to using the FASHN try-on API with Python.

### Usage
Refer to the official FASHN documentation for the complete Python quickstart guide.
```

--------------------------------

### Install FASHN SDK with pnpm

Source: https://docs.fashn.ai/sdk/typescript

Install the FASHN SDK using the pnpm package manager.

```bash
pnpm add fashn
```

--------------------------------

### Install FASHN Python SDK with uv

Source: https://docs.fashn.ai/sdk/python

Installs the FASHN Python SDK using uv. Run this in your terminal.

```bash
uv add fashn
```

--------------------------------

### Install FASHN Python SDK with poetry

Source: https://docs.fashn.ai/sdk/python

Installs the FASHN Python SDK using poetry. Run this in your terminal.

```bash
poetry add fashn
```

--------------------------------

### Install FASHN SDK with yarn

Source: https://docs.fashn.ai/sdk/typescript

Install the FASHN SDK using the yarn package manager.

```bash
yarn add fashn
```

--------------------------------

### Install FASHN Python SDK with pip

Source: https://docs.fashn.ai/sdk/python

Installs the FASHN Python SDK using pip. Run this in your terminal.

```bash
pip install fashn
```

--------------------------------

### Minimal JavaScript example for FASHN Try-On API

Source: https://docs.fashn.ai/guides/tryon-javascript-quickstart-guide

Use this snippet to run a Try-On prediction with FASHN. It sets up the API key and base URL, sends a POST request to /run with model and product image URLs, then polls /status until the prediction completes or fails. Requires the FASHN_API_KEY environment variable to be set. The example logs the prediction ID, status updates, and final output.

```javascript
// 1. Set up the API key and base URL
const API_KEY = process.env.FASHN_API_KEY;
if (!API_KEY) {
    throw new Error("Please set the FASHN_API_KEY environment variable.");
}
const BASE_URL = "https://api.fashn.ai/v1";

// 2. POST request to /run
const inputData = {
    model_name: "tryon-max",
    inputs: {
        model_image: "http://example.com/path/to/model.jpg",
        product_image: "http://example.com/path/to/garment.jpg"
    }
};

const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`
};

async function runPrediction() {
    try {
        // Make the initial run request
        const runResponse = await fetch(`${BASE_URL}/run`, {
            method: 'POST',
            headers: headers,
            body: JSON.stringify(inputData)
        });
        const runData = await runResponse.json();
        const predictionId = runData.id;
        console.log("Prediction started, ID:", predictionId);

        // Poll for status
        while (true) {
            const statusResponse = await fetch(`${BASE_URL}/status/${predictionId}`, {
                headers: headers
            });
            const statusData = await statusResponse.json();

            if (statusData.status === "completed") {
                console.log("Prediction completed.");
                console.log(statusData.output);
                break;
            } else if (["starting", "in_queue", "processing"].includes(statusData.status)) {
                console.log("Prediction status:", statusData.status);
                await new Promise(resolve => setTimeout(resolve, 3000));
            } else {
                console.log("Prediction failed:", statusData.error);
                break;
            }
        }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Run the prediction
runPrediction();
```

--------------------------------

### Example response for /v1/credits

Source: https://docs.fashn.ai/utility-endpoints/credits

Example JSON response from the credits endpoint. It shows the total credits (234), subscription credits (100), and on-demand credits (134).

```json
{
  "credits": {
    "total": 234,
    "subscription": 100,
    "on_demand": 134
  }
}
```

--------------------------------

### POST /v1/run - Try-On Max with base64 and hybrid inputs

Source: https://docs.fashn.ai/api-overview/data-retention-privacy

Example request body showing how to send input images as base64 data URIs or a hybrid of base64 and URLs to minimize data retention.

```APIDOC
## POST /v1/run

### Description
Sends input images using base64 encoding or a hybrid approach to minimize data retention. The customer photo is sent as base64 and the catalog image as a URL.

### Method
POST

### Endpoint
https://api.fashn.ai/v1/run

### Parameters
#### Request Body
- **inputs** (object) - Required - Contains the input images and options.
  - **model_image** (string) - Required - Base64 data URI of the customer photo.
  - **product_image** (string) - Required - URL of the catalog image.
  - **return_base64** (boolean) - Optional - Set to true to shorten the output availability window.

### Request Example
{
  "model_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "product_image": "https://your-cdn.com/catalog-garment.jpg",
  "return_base64": true
}

### Response
#### Success Response (200)
No response schema is provided in the source.

#### Response Example
No response example is provided in the source.
```

--------------------------------

### Install FASHN SDK

Source: https://docs.fashn.ai/guides/react-router-quickstart

Installs the FASHN TypeScript SDK via npm. The SDK is designed for server-side environments only; never call it from client components to protect your API key.

```bash
npm install fashn
```

--------------------------------

### Configure hybrid input strategy for Try-On Max

Source: https://docs.fashn.ai/api-overview/data-retention-privacy

An example of the inputs object using a Base64 data URI for sensitive images and a standard URL for catalog images.

```json
{
  "model_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "product_image": "https://your-cdn.com/catalog-garment.jpg",
  "return_base64": true
}
```

--------------------------------

### Minimal Python API Request and Polling

Source: https://docs.fashn.ai/guides/tryon-python-quickstart-guide

Demonstrates a basic request using model and product image URLs, including environment variable setup, POST request to /run, and status polling.

```python
import os
import time
import requests

# 1. Set up the API key and base URL
API_KEY = os.getenv("FASHN_API_KEY")
assert API_KEY, "Please set the FASHN_API_KEY environment variable."
BASE_URL = "https://api.fashn.ai/v1"

# 2. POST request to /run
input_data = 
}
headers = "}
run_response = requests.post(f"/run", json=input_data, headers=headers)
run_data = run_response.json()
prediction_id = run_data.get("id")
print("Prediction started, ID:", prediction_id)

# 3. Poll /status/
while True:
    status_response = requests.get(f"/status/", headers=headers)
    status_data = status_response.json()

    if status_data["status"] == "completed":
        print("Prediction completed.")
        # 4. The "output" field contains the final image URLs
        print(status_data["output"])
        break

    elif status_data["status"] in ["starting", "in_queue", "processing"]:
        print("Prediction status:", status_data["status"])
        time.sleep(3)

    else:
        print("Prediction failed:", status_data.get("error"))
        break
```

--------------------------------

### Request /v1/run via Python Requests

Source: https://docs.fashn.ai/api-overview/api-fundamentals

Example of sending a POST request to the /v1/run endpoint using the Python requests library.

```python
import requests

response = requests.post(
  "https://api.fashn.ai/v1/run",
  headers={
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  json={
    "model_name": "endpoint-specific-model-name",
    "inputs": {
      // endpoint-specific parameters
    }
  }
)
```

--------------------------------

### POST /v1/run - Try-On Max with short-lived signed URLs

Source: https://docs.fashn.ai/api-overview/data-retention-privacy

Example request to the Try-On Max endpoint using short-lived signed URLs for input images and return_base64 set to true to minimize data retention.

```APIDOC
## POST /v1/run

### Description
Runs the Try-On Max model with input images provided as short-lived signed URLs to minimize data retention. Setting return_base64 to true shortens the window during which the output is available.

### Method
POST

### Endpoint
https://api.fashn.ai/v1/run

### Parameters
#### Request Body
- **model_name** (string) - Required - The model name, set to "tryon-max".
- **inputs** (object) - Required - Contains the input images and options.
  - **model_image** (string) - Required - URL of the model image (person) with a short-lived signed URL.
  - **product_image** (string) - Required - URL of the product image (garment) with a short-lived signed URL.
  - **return_base64** (boolean) - Optional - Set to true to shorten the output availability window.

### Request Example
{
  "model_name": "tryon-max",
  "inputs": {
    "model_image": "https://your-cdn.com/person.jpg?expires=1735689600&signature=...",
    "product_image": "https://your-cdn.com/garment.jpg?expires=1735689600&signature=...",
    "return_base64": true
  }
}

### Response
#### Success Response (200)
No response schema is provided in the source.

#### Response Example
No response example is provided in the source.
```

--------------------------------

### Runtime Error Response Example

Source: https://docs.fashn.ai/api-overview/api-fundamentals

Example of a runtime error response returned when polling the status endpoint and the prediction has failed.

```APIDOC
## Runtime Error Response

### Description
This example shows the response format for a runtime error that occurs during model execution after a prediction ID has been returned.

### Response
#### Error Response (status: failed)
- **id** (string) - The prediction ID.
- **status** (string) - The status of the prediction, e.g., "failed".
- **error.name** (string) - The name of the error, e.g., "ImageLoadError".
- **error.message** (string) - A description of the error.

#### Response Example
```json
{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Error loading model image: Invalid URL format"
  }
}
```
```

--------------------------------

### Generate Try-On Images with Python

Source: https://docs.fashn.ai/api-reference/tryon-max

Submit product and model images to the /v1/run endpoint using the requests library.

```python
import requests

response = requests.post(
    'https://api.fashn.ai/v1/run',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    json={
        "model_name": "tryon-max",
        "inputs": {
            "product_image": "https://example.com/garment.jpg",
            "model_image": "https://example.com/person.jpg"
        }
    }
)

result = response.json()
print('Prediction ID:', result['id'])
```

--------------------------------

### API-Level Error Response Example

Source: https://docs.fashn.ai/api-overview/api-fundamentals

Example of an API-level error response returned when authentication fails before a prediction ID is issued.

```APIDOC
## API-Level Error Response

### Description
This example shows the response format for an API-level error, such as an authentication failure, that occurs before a prediction ID is issued.

### Response
#### Error Response (401 UnauthorizedAccess)
- **error** (string) - The error code, e.g., "UnauthorizedAccess".
- **message** (string) - A human-readable error message.

#### Response Example
```json
{
  "error": "UnauthorizedAccess",
  "message": "Unauthorized: Invalid token"
}
```
```

--------------------------------

### Set FASHN API key in .env.local

Source: https://docs.fashn.ai/guides/react-router-quickstart

Creates a .env.local file with the FASHN_API_KEY placeholder. Replace with your actual key, restart the dev server, and ensure the file is in .gitignore.

```env
FASHN_API_KEY=your_api_key_here
```

--------------------------------

### API-Level Error Response Example

Source: https://docs.fashn.ai/llms-full.txt

Example of an API-level error response returned when a request is rejected before processing, such as an unauthorized access error.

```APIDOC
## API-Level Error Response

### Description
An example of an API-level error response returned when a request is rejected before a prediction ID is issued. This example shows a 401 UnauthorizedAccess error.

### Response
#### Error Response (401 UnauthorizedAccess)
- **error** (string) - The error code.
- **message** (string) - A human-readable description of the error.

#### Response Example
{
  "error": "UnauthorizedAccess",
  "message": "Unauthorized: Invalid token"
}
```

--------------------------------

### Scaffold React Router project and run dev server

Source: https://docs.fashn.ai/guides/react-router-quickstart

Creates a new React Router application with Vite, TypeScript, and Tailwind CSS, then starts the development server. Visit http://localhost:5173 to see the welcome screen.

```bash
npx create-react-router@latest my-rr-fashn-app
cd my-rr-fashn-app
npm run dev
```

--------------------------------

### API-level error response example

Source: https://docs.fashn.ai/api-overview/error-handling

An example of an HTTP 401 UnauthorizedAccess error response returned when a request fails due to authentication issues.

```json
// HTTP 401 UnauthorizedAccess
{
  "error": "UnauthorizedAccess",
  "message": "Unauthorized: Invalid token"
}
```

--------------------------------

### Handle API and Runtime Errors in Python

Source: https://docs.fashn.ai/sdk/python

Demonstrates how to initialize the FASHN client and handle both API-level exceptions and runtime status checks for model predictions.

```python
import os
import fashn
from fashn import Fashn

client = Fashn(
    api_key=os.environ.get("FASHN_API_KEY"),  # This is the default and can be omitted
)

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

    # 1. Check for Runtime Errors (during model execution). Status can be failed, canceled or time_out.
    if result.status != "completed":
        print("Runtime Error - Status:", result.status)
        if result.error:
            print("Error message:", result.error.message)
    else:
        # 2. Success case (status is completed)
        print("Generation completed successfully!")
        print("Generated:", result.output)

except fashn.APIError as e:
    # 3. Handle API-Level Errors (before request processing)
    print("API-Level Error - Status:", e.status_code)
    print("Message:", e.message)
except Exception as e:
    # Network or unexpected error
    print("Network or unexpected error:", e)
```

--------------------------------

### Scaffold a Next.js project

Source: https://docs.fashn.ai/guides/nextjs-quickstart

Use create-next-app to initialize a new project with default settings, including TypeScript, ESLint, Tailwind CSS, and the App Router.

```bash
npx create-next-app@latest my-fashn-app --yes
cd my-fashn-app
npm run dev
```

--------------------------------

### Reframe API Response Example

Source: https://docs.fashn.ai/api-reference/reframe

Example JSON response from the Reframe API call, returning a prediction ID for status polling and an error field set to null.

```json
{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "error": null
}
```

--------------------------------

### Request /v1/run via cURL

Source: https://docs.fashn.ai/api-overview/api-fundamentals

Example of sending a POST request to the /v1/run endpoint using cURL.

```bash
curl -X POST https://api.fashn.ai/v1/run \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "model_name": "endpoint-specific-model-name",
           "inputs": {
             // endpoint-specific parameters
           }
         }'
```

--------------------------------

### Try-On v1.6 API Parameters

Source: https://docs.fashn.ai/guides/tryon-parameters-guide

Documentation of the parameters for the Try-On v1.6 endpoint, including model_image, garment_image, category, mode, garment_photo_type, and num_samples.

```APIDOC
## Try-On v1.6 API Parameters

### Description
This endpoint performs virtual try-on using a model image and a garment image. It accepts various parameters to control the garment category, processing mode, photo type, and number of samples.

### Parameters

#### model_image
- **Type**: string (image URL or base64)
- **Required**: Yes
- **Description**: The primary image of the person on whom the virtual try-on will be performed. Can be a publicly accessible URL or a base64 string.

#### garment_image
- **Type**: string (image URL or base64)
- **Required**: Yes
- **Description**: The reference image of the clothing item to be tried on the model_image. Can be a URL or a base64 string.

#### category
- **Type**: string (enum: 'auto', 'tops', 'bottoms', 'one-pieces')
- **Required**: No
- **Description**: Specifies the type of garment in the garment_image. 'auto' is recommended and automatically determines the category. 'tops' for upper body, 'bottoms' for lower body, 'one-pieces' for full-body garments.

#### mode
- **Type**: string (enum: 'performance', 'balanced', 'quality')
- **Required**: No
- **Description**: Determines the trade-off between processing speed and output quality. 'performance' is fastest with reduced quality, 'balanced' is a middle ground, 'quality' is slowest with highest quality.

#### garment_photo_type
- **Type**: string (enum: 'auto', 'model', 'flat-lay')
- **Required**: No
- **Description**: Defines the garment photo type for optimal performance. 'model' for photos on a model, 'flat-lay' for flat-lay or ghost mannequin images, 'auto' for automatic detection. 'flat-lay' is required for precise handling of flat-lay images.

#### num_samples
- **Type**: integer
- **Required**: No
- **Description**: Specifies how many images to generate in a single run. Increasing this allows exploring multiple variations. Results are reproducible for a given num_samples count when used with the same seed.

### Notes
- For image URLs, ensure the URL is publicly accessible and the Content-Type header matches the image format.
- For base64 images, prefix the string with 'data:image/;base64,' where is the image type (e.g., jpeg, png).
- Use mode: performance for quick testing, then switch to mode: quality for final results.
- Use num_samples: 2-4 with mode: performance to test multiple seeds and assess sensitivity.
```

--------------------------------

### Install FASHN agent skill

Source: https://docs.fashn.ai/api-overview/api-fundamentals

Command to add the FASHN agent skill to your project for automated pattern integration.

```bash
npx skills add fashn-ai/fashn-skill
```

--------------------------------

### Try-On API Input Parameters

Source: https://docs.fashn.ai/llms-full.txt

Lists all input parameters for the FASHN AI try-on API, including their types, defaults, and descriptions.

```APIDOC
## Input Parameters

### product_image
- **Type**: image URL | data URI
- **Required**: Yes
- **Description**: Product image (garment, accessory, etc.) to place on the model.

### model_image
- **Type**: image URL | data URI
- **Required**: Yes
- **Description**: Image of the person who will wear the product. The try-on process preserves the model's identity, pose, and styling while seamlessly integrating the product.

### prompt
- **Type**: string
- **Required**: No
- **Default**: Empty string (uses intelligent defaults based on the images)
- **Description**: Optional instructions to customize the try-on result. Use this to adjust how the product is worn or make minor styling changes. Examples: "remove scarf", "tuck in shirt", "roll up sleeves", "open jacket".

### resolution
- **Type**: 1k | 2k | 4k
- **Required**: No
- **Default**: 1k
- **Description**: Output resolution tier. '1k' produces ~1 megapixel output, '2k' ~4 megapixels, and '4k' ~16 megapixels. Exact output dimensions depend on this tier and the image aspect ratio.

### generation_mode
- **Type**: fast | balanced | quality
- **Required**: No
- **Description**: Sets the generation quality level. 'quality' produces the most detailed and realistic output but takes longer to process and costs more credits. 'balanced' offers a middle ground between speed and quality. 'fast' prioritizes speed and lower cost. If omitted, FASHN selects generation_mode automatically. For tryon-max, omitted generation_mode is currently billed as 'balanced' at all resolutions.

### seed
- **Type**: integer
- **Required**: No
- **Default**: 42
- **Range**: 0 to 2^32 - 1
- **Description**: Sets random operations to a fixed state. Use the same seed to reproduce results with the same inputs, or a different seed to force different results.

### num_images
- **Type**: integer
- **Required**: No
- **Default**: 1
- **Description**: Number of images to generate in a single request. Must be between 1 and 4. Additional images consume more compute (and credits) and can increase processing time.

### output_format
- **Type**: png | jpeg
- **Required**: No
- **Default**: png
- **Description**: Specifies the output image format. png: Lossless quality, best for further editing or when maximum fidelity is needed. jpeg: Smaller file size with slight compression, suitable for direct web use.

### return_base64
- **Type**: boolean
- **Required**: No
- **Default**: false
- **Description**: When set to true, the API will return the generated image as a base64-encoded string instead of a CDN URL. The base64 string will be prefixed according to the output_format (e.g., data:image/png;base64,... or data:image/jpeg;base64,...). Privacy benefit: Outputs are available for up to 60 minutes instead of the standard three-day window. Request history contains only a placeholder.
```

--------------------------------

### POST /v1/run

Source: https://docs.fashn.ai/llms-full.txt

Creates a short video from a single image. The request body must include model_name set to 'image-to-video' and an inputs object containing endpoint-specific parameters.

```APIDOC
## POST /v1/run

### Description
Creates a short video from a single image with tasteful camera work and model movements tailored for fashion.

### Method
POST

### Endpoint
/v1/run

### Parameters
#### Request Body
- **model_name** (string) - Required - Must be `image-to-video`.
- **inputs** (object) - Required - Contains the endpoint-specific parameters documented under Input parameters.

### Request Example
{
  "model_name": "image-to-video",
  "inputs": {}
}

### Response
#### Success Response (200)
No response schema is documented in the source.

#### Response Example
No response example is documented in the source.

### Error Handling
Runtime errors use the shared set in Error Handling.
```
Tokens:
Raw