FASHN Agent API Quickstart

The FASHN Agent API is the main way to make fashion images with FASHN. You send one request with a plain-language prompt and up to six reference images, and the FASHN Agent plans the steps, runs them, and returns every image it made. It can run try-on, product-to-model, model creation and swap, edits, background changes, packshots, transparent images, upscaling, and background removal.

This page takes you from an API key to your first images, then shows prompts for common fashion content. For every parameter, limit, and error, see the Agent Images reference.

See it in action: this video makes a four-look lookbook from six photos with Claude Code and one FASHN Agent API call.

Make your first request

export FASHN_API_KEY="your-api-key"

curl -X POST https://api.fashn.ai/v1/agent/images \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $FASHN_API_KEY" \
     -d '{
           "prompt": "Show the jacket in the first image on a model in a bright studio, full body, front view",
           "images": ["https://example.com/jacket.jpg"]
         }'

{
  "id": "3c1f6a52-8e0b-4d7a-9a51-2f4b7c9d0e18",
  "predictions": [
    {
      "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
      "tool": "generate-image",
      "results": [
        "https://cdn.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.png"
      ],
      "credits_used": 1
    }
  ],
  "credits_used": 1
}

Run longer requests in the background

Requests with several steps, such as a lookbook, can take a few minutes. Instead of holding the connection open, start a run with POST /v1/agent/images/run. It takes the same body and returns a run ID right away. Then poll the run's status with that ID until status is completed or failed:

# Start the run
curl -X POST https://api.fashn.ai/v1/agent/images/run \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $FASHN_API_KEY" \
     -d '{
           "prompt": "Show the jacket in the first image on a model in a bright studio, full body, front view",
           "images": ["https://example.com/jacket.jpg"]
         }'
# Returns {"id": "3c1f6a52-8e0b-4d7a-9a51-2f4b7c9d0e18", "error": null}
 
# Check on it
curl https://api.fashn.ai/v1/agent/status/3c1f6a52-8e0b-4d7a-9a51-2f4b7c9d0e18 \
     -H "Authorization: Bearer $FASHN_API_KEY"

A completed run returns the same predictions and credits_used as the synchronous response. To get the result on your server instead of polling, add a webhook_url query parameter when you start the run. See Asynchronous runs and Webhooks.

Example prompts for fashion content

Each example below is a request body for /v1/agent/images or /v1/agent/images/run. Replace the image URLs with your own, or send base64 data URIs.

On-model product photos

Turn a product photo into photos of a model wearing it:

{
  "prompt": "Show the dress in the first image on a model in a bright studio. Make three images from different angles: front, three-quarter, and side, full body.",
  "images": ["https://example.com/dress.jpg"],
  "aspect_ratio": "3:4"
}

A request for several images, such as three angles, makes one image per generation and is billed per image.

Packshots

Make a clean product image from a photo of the product:

{
  "prompt": "Make a packshot of the bag in the first image, alone on a plain white background with a soft studio shadow",
  "images": ["https://example.com/bag-photo.jpg"],
  "aspect_ratio": "1:1"
}

For a cutout, ask for a transparent background instead.

Catalog images

Put several products on the same model in the same setting, one image per product:

{
  "prompt": "Put each garment from images 2 to 4 on the model from image 1, one image per garment. Full body, front view, plain light gray studio background, the same pose and lighting in every image.",
  "images": [
    "https://example.com/model.jpg",
    "https://example.com/shirt.jpg",
    "https://example.com/trousers.jpg",
    "https://example.com/coat.jpg"
  ],
  "aspect_ratio": "3:4",
  "resolution": "2k"
}

A request takes up to six images and runs up to eight operations, so a larger catalog takes several requests. They can run in parallel up to your concurrency limit.

Lookbooks

A lookbook keeps one model and one location across several looks. The lookbook recipe makes four looks from a face photo, a location photo, and four outfits in one call, with a prompt worded to keep the face the same in every look:

{
  "prompt": "Make a lookbook of four full body photos. Image 1 is the model, image 2 is the location, and images 3 to 6 are four outfits, one per look. Make look 1 first. Then make looks 2, 3 and 4, each one directly from look 1, in a different pose, head angle and expression. In every look, use the face from image 1, so the model matches image 1 exactly.",
  "images": [
    "https://example.com/face.jpg",
    "https://example.com/location.jpg",
    "https://example.com/outfit-1.jpg",
    "https://example.com/outfit-2.jpg",
    "https://example.com/outfit-3.jpg",
    "https://example.com/outfit-4.jpg"
  ],
  "resolution": "2k",
  "aspect_ratio": "2:3",
  "generation_mode": "quality"
}

Run it in the background: it takes about five minutes and, at these settings, 12 credits for the four looks.

Use it from Claude Code or Codex

A coding agent can run these requests for you. It finds the photos, sends the request, and saves the results, and the FASHN Agent makes the images: your agent is the producer, and the FASHN Agent is the photographer.

Claude Code. Open Claude Code in a folder with a face photo, a location photo, and four outfit photos, and paste:

Download https://docs.fashn.ai/recipes/lookbook.md with curl and follow it exactly

The recipe sets up your API key in a .env file, confirms which photo is which, and saves the four looks in a new folder. How to make an AI lookbook with Claude Code ↗ walks through a full run.

Codex, Cursor, and other agents. Every page of these docs is also available as Markdown. Ask your agent to read the Agent Images reference, then describe what you need, for example:

Read https://docs.fashn.ai/api-reference/agent-images.md.
Then turn every product photo in ./products into an on-model photo
with the FASHN Agent API, and save the results in ./on-model.

See Coding Agents for more ways to use FASHN from a coding agent.

Tips for better results

• Refer to the images by their position ("the first image") or by what they show ("the dress").
• The Agent never asks a question back. When a prompt is unclear, it makes its best guess, so say what you want: framing, background, pose, and how many images.
• The Agent adds no steps you did not ask for, such as an upscale or a variation. Ask for them in the prompt.
• Use generation_mode: "fast" for drafts, and "quality" with a higher resolution for final assets. See Credit cost.
• Each request runs at most 8 operations, so it costs at most 32 credits.
• The Agent makes images only. For video, use Image to Video.

Next: Read the full Agent Images reference, or set up Webhooks for background runs.