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:
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
promptRequiredstring
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
| Requirement | Limit |
|---|---|
| Input images | 6 per request |
| Base64 image size | 10 MB per image |
| Image formats | JPEG, PNG, WebP |
| Prompt length | 10,000 characters |
| Video duration | 4 to 15 seconds |
| Videos | 8 per request |
| Request duration | 20 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:
resolution | Credits per second | 5-second video | 10-second video | 15-second video |
|---|---|---|---|---|
480p | 1 | 5 | 10 | 15 |
720p | 2 | 10 | 20 | 30 |
1080p | 4 | 20 | 40 | 60 |
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_usedfield and theX-Fashn-Credits-Usedresponse header give the exact cost of the request, and each entry inpredictionsgives 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:completedorfailed.results: the video it produced, as a CDN URL to an MP4 file. Empty for a failed entry.credits_used: the credits it consumed.0for a failed entry.error:nullwhen completed, otherwisenameandmessage.
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
Response
Returns the run ID for status polling:
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:
A failed run returns the error, with the predictions it tried and credits_used, and HTTP 200:
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.
| Code | Name | Cause | How to fix |
|---|---|---|---|
| 422 | NoVideoGenerated | The 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. |
| 422 | ImageLoadError | An input image URL could not be downloaded. | Use publicly accessible image URLs, or send the images as base64. |
| 422 | BadRequest | An input image could not be read. | Send JPEG, PNG, or WebP images, and a smaller version of a very large image. |
| 422 | Runtime error name | The Agent's last generation failed, for example with ContentModerationError. | See Common runtime errors. |
| 504 | AgentTimeout | The request ran longer than 20 minutes and made no video. | Simplify the request, or split it into several requests. |
| 500 | InternalServerError | The run failed unexpectedly. | Retry with backoff; contact support@fashn.ai with the run id if it persists. |
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.
Related guides
- Agent Images - Make on-model photos, packshots, and lookbooks with the FASHN Agent
- Coding Agents - Use FASHN from Claude Code, Codex, Cursor, and other coding agents
- 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