fashn-logo
FASHNAI

Agent Videos: Fashion AI Video Agent API

Agent Videos is the FASHN Agent API endpoint for video: a fashion AI agent that turns a plain-language request into finished videos. Describe the result in a prompt and attach up to six images, such as a model photo, product photos, or a location. The FASHN Agent decides how to use each image, writes the shot, generates the videos, and returns every video it made.

Use it for on-model videos, product clips, and transitions between two looks. One request can make several videos, such as one video per product photo. It takes the same kind of request as Agent Images, with video settings instead of image settings, and returns the same response shape.

Lifecycle: Experimental · Released: November 16, 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 videos in the same request:

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

Request examples

curl -X POST https://api.fashn.ai/v1/agent/videos \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "prompt": "The model turns slowly to show the dress from every side",
           "images": [
             "https://example.com/model-in-dress.jpg"
           ]
         }'

Response

Returns every video the Agent made:

{
  "id": "7d2e9b41-5c3a-4f08-b6e2-1a9c4d8f0e27",
  "status": "completed",
  "error": null,
  "predictions": [
    {
      "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
      "tool": "generate-video",
      "status": "completed",
      "results": [
        "https://cdn.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.mp4"
      ],
      "credits_used": 5,
      "error": null
    }
  ],
  "credits_used": 5
}

The request stays open until the Agent finishes, which takes a few minutes for one video at the default settings and longer for longer or higher-resolution videos. 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. Describe the motion, the camera, and the scene, and refer to the images by their position ("the first image", "the jacket 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,...). See How the Agent uses images.

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

durationinteger

Length of each video, in whole seconds, from 4 to 15. A duration asked for in the prompt takes precedence.

Default: 5

resolution'480p' | '720p' | '1080p'

Output resolution of each video. A resolution asked for in the prompt takes precedence.

Default: 480p

aspect_ratio'16:9' | '9:16' | '4:3' | '3:4' | '1:1'

Aspect ratio of a video made without a start image. A video that starts from an image keeps that image's frame. An aspect ratio asked for in the prompt takes precedence.

Default: None. The Agent chooses a frame that suits the request.

audioboolean

Whether the videos have sound. true adds sound to every video, and false makes silent videos. Sound asked for, or ruled out, in the prompt takes precedence.

Default: None. The Agent adds sound only when the prompt asks for it.

How the Agent uses images

The Agent decides the role of each image from the prompt:

  • Start frame: the video begins on the image and animates it, for example a model photo that starts walking. The video keeps the image's frame.
  • Start and end frames: the video moves from the first image to the second, for example a transition between two looks.
  • Reference images: the video shows the people, garments, or products from the images in a new scene, for example a person from one image wearing a jacket from another.

When the prompt asks for a different aspect ratio than a start image has, the Agent uses the image as a reference instead, so the video can have the requested frame.

A request for several videos, such as "one video per image" or "three clips", makes one video per generation, up to 8 videos per request. The Agent adds no videos you did not ask for.

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

Use it from a coding agent

Claude Code, Codex, Cursor, and other coding agents can call Agent Videos for you. Every page of these docs is also available as Markdown: ask your agent to read https://docs.fashn.ai/api-reference/agent-videos.md and build the request your project needs, for example a script that turns every on-model photo in a folder into a short video.

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
Video duration4 to 15 seconds
Videos8 per request
Request duration20 minutes to start operations

A request with too many images, a base64 image over 10 MB, a prompt over 10,000 characters, or a duration outside 4 to 15 seconds 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 videos stops and returns the videos made so far. After 20 minutes, a request starts no new videos, waits for the ones already running, and returns every video made; they are billed as usual. A request can therefore take up to about 40 minutes in total. If it made no video, it fails with 504 AgentTimeout.

Each video 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 videos the Agent makes. Each video costs credits per second of video, by resolution, with sound included:

resolutionCredits per second5-second video10-second video15-second video
480p151015
720p2102030
1080p4204060

Additional pricing rules:

  • A request costs the sum of its videos, with at most 8 videos per request, so at most 480 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 video, failed when it made none.

errorobject | null

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

predictionsobject[]

Every video generation, in the order the Agent started them: failed generations and calls refused for credits or concurrency are listed too. Each entry has:

  • id: the prediction ID.
  • tool: the operation, generate-video.
  • status: completed or failed.
  • results: the video it produced, as a CDN URL to an MP4 file. 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 videos, 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/videos:

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

Request example

curl -X POST "https://api.fashn.ai/v1/agent/videos/run?webhook_url=https://your-server.com/webhook" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "prompt": "The model turns slowly to show the dress from every side",
           "images": [
             "https://example.com/model-in-dress.jpg"
           ],
           "duration": 10,
           "resolution": "1080p"
         }'

Response

Returns the run ID for status polling:

{
  "id": "7d2e9b41-5c3a-4f08-b6e2-1a9c4d8f0e27",
  "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, on the same status route as Agent Images:

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": "7d2e9b41-5c3a-4f08-b6e2-1a9c4d8f0e27",
  "status": "completed",
  "error": null,
  "predictions": [
    {
      "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
      "tool": "generate-video",
      "status": "completed",
      "results": [
        "https://cdn.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.mp4"
      ],
      "credits_used": 40,
      "error": null
    }
  ],
  "credits_used": 40
}

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

{
  "id": "7d2e9b41-5c3a-4f08-b6e2-1a9c4d8f0e27",
  "status": "failed",
  "error": {
    "name": "NoVideoGenerated",
    "message": "The agent did not generate a video 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 video it fails with that 429 error.

Otherwise, a run that made no video 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
422NoVideoGeneratedThe Agent did not make a video, for example for an image 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 20 minutes and made no video.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 NoVideoGenerated
{
  "id": "7d2e9b41-5c3a-4f08-b6e2-1a9c4d8f0e27",
  "status": "failed",
  "error": {
    "name": "NoVideoGenerated",
    "message": "The agent did not generate a video for this request. Make the prompt more specific or check the input images."
  },
  "predictions": [],
  "credits_used": 0
}

When the Agent made at least one video, the run succeeds with the videos it made, even if a later generation failed.

Data handling

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

On this page