fashn-logo
FASHNAI

Agent Images: Fashion AI Agent API

Agent Images is the FASHN Agent API endpoint: a fashion AI agent that turns a plain-language request into finished images. Describe the result in a prompt and attach up to six images, such as product photos, a model photo, or a location. The FASHN Agent decides which operations the request needs, such as a try-on, a model swap, or an edit, runs them, and returns every image it made.

Use it for agentic fashion content creation: on-model product photos, packshots, catalog images, and lookbooks. One request can cover several steps that would otherwise take a chain of calls to the single-task endpoints. It is a plain REST endpoint, so your own code can call it, or a coding agent such as Claude Code, Codex, or Cursor can call it for you. Your agent acts as the producer and the FASHN Agent as the photographer. See Use it from a coding agent.

New to the Agent? The FASHN Agent API Quickstart walks through a first request and example prompts.

Lifecycle: Experimental · Released: October 26, 2026

Request body

Send the parameters documented under Input parameters as top-level fields of a JSON object. A field not listed there is rejected with 400 BadRequest.

Request

Run the Agent and wait for its images in the same request:

POSThttps://api.fashn.ai/v1/agent/images

Request examples

curl -X POST https://api.fashn.ai/v1/agent/images \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "prompt": "Put the dress from the second image on the model in the first image",
           "images": [
             "https://example.com/person.jpg",
             "https://example.com/dress.jpg"
           ]
         }'

Response

Returns every image the Agent made:

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

The request stays open until the Agent finishes, which takes about 40 seconds for one image at the default settings and longer for requests with several steps. To avoid holding a connection open, use an asynchronous run instead.

Input parameters

prompt
Required
string

What you want, in plain language: between 1 and 10,000 characters. Refer to the images by their position ("the first image", "the dress in the second image") or by what they show.

The Agent never asks a question back. When the prompt is unclear, it makes the best guess that fits the prompt and the images.

images(image URL | data URI)[]

Up to 6 images, in the order the prompt refers to them. Each item is a publicly accessible http(s) image URL or a base64 data URI (data:image/<format>;base64,...).

Default: [] (the Agent generates from the prompt alone)

aspect_ratio'1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9'

Aspect ratio of the generated images. An aspect ratio asked for in the prompt takes precedence.

Default: None. The Agent chooses: an edit keeps the edited image's frame, and a new image gets a frame that suits the request.

resolution'1k' | '2k' | '3k' | '4k'

Output resolution tier of the generated images. '1k' produces about 1 megapixel, '2k' about 4, '3k' about 9, and '4k' about 16. An output size asked for in the prompt takes precedence. Some images are made and billed at '2k' when '3k' or '4k' is requested.

Default: 1k

generation_mode'fast' | 'balanced' | 'quality'

Sets the generation quality level for every image the Agent generates. 'quality' produces the most detailed and realistic output but takes longer and costs more credits. 'fast' prioritizes speed and lower cost.

Default: balanced

return_base64boolean

When set to true, every image in results is returned as a base64 data URI (data:image/png;base64,...) instead of a CDN URL.

The images are still stored on the CDN for three days.

Default: false

What the Agent can do

For each request, the Agent can:

  • Generate images: create new images or edit existing ones, including try-on, product-to-model, model creation and swap, background changes, packshots, and transparent images.
  • Upscale images: enlarge an image or restore its detail.
  • Remove backgrounds: return a transparent cutout of an image.

Each of these counts as one operation; inspecting its own results does not.

A request for several images, such as "three angles" or "two colorways", makes one image per generation. The Agent adds no steps you did not ask for, such as an upscale or a variation.

The Agent makes images only. A request for a video, or one that cannot be met with images, fails with NoImageGenerated. To make videos, use Agent Videos.

Use it from a coding agent

Claude Code, Codex, Cursor, and other coding agents can call Agent Images for you. Your agent finds the photos, sends the request, and saves the results, and the FASHN Agent makes the images.

Follow a recipe. The lookbook recipe is a set of instructions, written for Claude Code, that makes a four-look lookbook from six photos in one call. Open Claude Code in a folder with a face photo, a location photo, and four outfit photos, then 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 looks in a new folder. How to make an AI lookbook with Claude Code ↗ walks through a full run.

Point your agent at this page. Every page of these docs is also available as Markdown. Ask your agent to read https://docs.fashn.ai/api-reference/agent-images.md and build the request your project needs, for example a script that turns every product photo in a folder into an on-model photo.

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

Technical limitations

RequirementLimit
Input images6 per request
Base64 image size10 MB per image
Image formatsJPEG, PNG, WebP
Prompt length10,000 characters
Operations8 per request
Request duration15 minutes to start operations

A request with too many images, a base64 image over 10 MB, or a prompt over 10,000 characters fails with 400 BadRequest. An image the Agent cannot read, such as one in another format, fails with 422 BadRequest.

A request that reaches 8 operations stops and returns the images made so far. After 15 minutes, a request starts no new operations, waits for the ones already running, and returns every image made; they are billed as usual. A request can therefore take up to about 30 minutes in total. If it made no image, it fails with 504 AgentTimeout.

Each operation counts against your concurrency limit while it runs. Rate limits are 100 requests per 60 seconds to start a run and 50 requests per 10 seconds for /v1/agent/status.

Credit cost

You pay only for the images the Agent makes. Each generated image costs:

generation_mode \ resolution1k2k3k4k
fast1111
balanced1233
quality2344

Additional pricing rules:

  • An upscale or a background removal costs 1 credit.
  • A request costs the sum of its operations, intermediate images included, with at most 8 operations per request, so at most 32 credits.
  • Failed operations do not consume credits.
  • The top-level credits_used field and the X-Fashn-Credits-Used response header give the exact cost of the request, and each entry in predictions gives its own.

Response

idstring

ID of the Agent run. Errors returned after the run starts include it too.

status'completed' | 'failed'

completed when the Agent made at least one image, failed when it made none.

errorobject | null

null when the run completed. Otherwise the error, as name and message. See Errors.

predictionsobject[]

Every operation, in the order the Agent ran them, intermediate steps included: failed generations and calls refused for credits or concurrency are listed too. Each entry has:

  • id: the prediction ID.
  • tool: the operation, generate-image, image-upscale, or background-remove.
  • status: completed or failed.
  • results: the images it produced, as CDN URLs, or as data URIs with return_base64. Empty for a failed entry.
  • credits_used: the credits it consumed. 0 for a failed entry.
  • error: null when completed, otherwise name and message.

To get the images, use the entries whose status is completed.

credits_usedinteger

Total credits consumed by the request.

The Agent's text is never returned.

Asynchronous runs

To avoid waiting on an open request, start the run, then poll its status or receive it on a webhook. The run takes the same request body as /v1/agent/images:

POSThttps://api.fashn.ai/v1/agent/images/run

Request example

curl -X POST "https://api.fashn.ai/v1/agent/images/run?webhook_url=https://your-server.com/webhook" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "prompt": "Put the dress from the second image on the model in the first image",
           "images": [
             "https://example.com/person.jpg",
             "https://example.com/dress.jpg"
           ]
         }'

Response

Returns the run ID for status polling:

{
  "id": "3c1f6a52-8e0b-4d7a-9a51-2f4b7c9d0e18",
  "error": null
}

With the optional webhook_url query parameter, FASHN sends the run's result to that URL when the run ends, with the same body as a completed or failed status response. See Webhooks.

Status polling

Poll the run with the ID returned when it started:

GEThttps://api.fashn.ai/v1/agent/status/{id}

The response follows the /v1/status states, processing, completed, and failed, with no partial results while the run is processing. A completed run returns the same predictions and credits_used as the synchronous response, and sets the X-Fashn-Credits-Used header:

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

A failed run returns the error, with the predictions it tried and credits_used, and HTTP 200:

{
  "id": "3c1f6a52-8e0b-4d7a-9a51-2f4b7c9d0e18",
  "status": "failed",
  "error": {
    "name": "NoImageGenerated",
    "message": "The agent did not generate an image for this request. Make the prompt more specific or check the input images."
  },
  "predictions": [],
  "credits_used": 0
}

A run that does not exist, or that belongs to another user, returns 404.

Errors

An invalid request fails before the run starts, with the API-level errors, such as 400 BadRequest or 429 RateLimitExceeded. The API also checks your credit balance and that a concurrency slot is free before the run starts, and otherwise returns 429 OutOfCredits or 429 ConcurrencyLimitExceeded with no id, as /v1/run does. During the run, a generation refused with OutOfCredits or ConcurrencyLimitExceeded stops the run: no further generations start, those already running finish and are returned, and if the run made no image it fails with that 429 error.

Otherwise, a run that made no image fails with one of the errors below. A synchronous request returns the run with status: "failed" and the HTTP status shown, and an asynchronous run returns the same body as its failed status.

CodeNameCauseHow to fix
422NoImageGeneratedThe Agent did not make an image, for example for a video request or an unclear prompt.Make the prompt more specific, or check the input images.
422ImageLoadErrorAn input image URL could not be downloaded.Use publicly accessible image URLs, or send the images as base64.
422BadRequestAn input image could not be read.Send JPEG, PNG, or WebP images, and a smaller version of a very large image.
422Runtime error nameThe Agent's last generation failed, for example with ContentModerationError.See Common runtime errors.
504AgentTimeoutThe request ran longer than 15 minutes and made no image.Simplify the request, or split it into several requests.
500InternalServerErrorThe run failed unexpectedly.Retry with backoff; contact support@fashn.ai with the run id if it persists.
// HTTP 422 NoImageGenerated
{
  "id": "3c1f6a52-8e0b-4d7a-9a51-2f4b7c9d0e18",
  "status": "failed",
  "error": {
    "name": "NoImageGenerated",
    "message": "The agent did not generate an image for this request. Make the prompt more specific or check the input images."
  },
  "predictions": [],
  "credits_used": 0
}

When the Agent made at least one image, the run succeeds with the images it made, even if a later step failed.

Data handling

Base64 input images are stored privately while the run uses them, and deleted after it ends. Generated images follow the standard data retention of API outputs.

On this page