Agent Images

Agent Images is an endpoint 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 or a model photo. The 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.

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:

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"
           ]
         }'

{
  "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
}

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

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.

Technical limitations

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. A request still running after 15 minutes stops the same way. If it made no image, it fails with 504 AgentTimeout. Generations still running at that point complete and are billed, but are not returned.

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:

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

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:

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"
           ]
         }'

{
  "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:

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",
  "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,
  "error": null
}

A failed run returns the error:

{
  "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."
  }
}

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. When a generation is refused for your credits or concurrency limit and the run made no image, the run fails with that 429 error, OutOfCredits or ConcurrencyLimitExceeded.

Otherwise, a run that made no image fails with one of the errors below. A synchronous request returns it with the HTTP status shown and the run's id, and an asynchronous run returns it as its failed status.

// HTTP 422 NoImageGenerated
{
  "error": "NoImageGenerated",
  "message": "The agent did not generate an image for this request. Make the prompt more specific or check the input images.",
  "id": "3c1f6a52-8e0b-4d7a-9a51-2f4b7c9d0e18"
}

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.

Related guides

• Prompting in FASHN ↗ - Learn how to write effective prompts for best results
• Image Preprocessing Best Practices - Optimize your input images for better results
• Data Retention & Privacy - Understand how FASHN handles your data