Reframe

Reframe enables you to extend and reshape images using generative fill technology. This versatile endpoint offers two distinct modes: directional extension to reveal more content, and aspect ratio adjustment to fit specific canvas dimensions.

Model Specifications

Model Name: reframe
Processing Time: 10 seconds
Maximum Resolution: up to 1.05MP (see full list below)

Dual Operation Modes

Direction Mode: Extend images in specific directions (up, down, both) to reveal more content
Aspect Ratio Mode: Transform images to match target aspect ratios using generative filling

Request

Extend and reshape images by submitting the source image to the universal /v1/run endpoint:

POST`https://api.fashn.ai/v1/run`

Request Examples

curl -X POST https://api.fashn.ai/v1/run \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "model_name": "reframe",
           "inputs": {
             "image": "https://example.com/portrait.jpg",
             "mode": "direction",
             "target_direction": "down"
           }
         }'

Response

Returns a prediction ID for status polling:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "error": null
}

Request Parameters

Required Parameters

`image`
Required
image URL | base64

Source image to extend or reframe. The AI will intelligently generate new content to expand the image based on the selected mode and parameters.

Resolution Handling

Output resolution is limited to 1MP. If your image is already at or above this size, it will be downsampled so that, after any extensions are applied, the final result fits within the 1MP limit.

Base64 Format

Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)

Mode Selection

`mode`'direction' | 'aspect_ratio'

Selects the reframing operation mode:

direction – Directed zoom-out: extend image in specific directions to reveal more content
aspect_ratio – Canvas adjustment: transform image to match a target aspect ratio

Parameter Requirements

direction mode requires target_direction
aspect_ratio mode requires target_aspect_ratio

Default: direction

Optional Parameters

`target_direction`'both' | 'down' | 'up'

Direction of image extension when using mode: "direction". This parameter is ignored when mode: "aspect_ratio".

both – Expand in both directions (zoom out effect)
down – Expand only downward (reveal lower content, e.g., show full body from upper body shot)
up – Expand only upward (reveal upper content, e.g., show face from headless shot)

Default: both

`target_aspect_ratio`'1:1' | '2:3' | '3:4' | '4:5' | '9:16' | '4:3'

Target aspect ratio for the output canvas when using mode: "aspect_ratio". This parameter is ignored when mode: "direction".

`seed`integer

Sets random operations to a fixed state. Use the same seed to reproduce results with the same inputs, or different seed to force different results.

Default: 42
Range: 0 to 2^32 - 1

`output_format`'png' | 'jpeg'

Specifies the desired output image format.

-png: Delivers the highest quality image, ideal for use cases such as content creation where quality is paramount.
-jpeg: Provides a faster response with a slightly compressed image, more suitable for real-time applications.

Default: png

`return_base64`boolean

When set to true, the API will return the generated image as a base64-encoded string instead of a CDN URL. The base64 string will be prefixed according to the output_format (e.g., data:image/png;base64,... or data:image/jpeg;base64,...).

This option offers enhanced privacy as user-generated outputs are not stored on our servers when return_base64 is enabled.

Default: false

Examples

Direction Mode

Extend images in specific directions while preserving the original aspect ratio:

{
  "model_name": "reframe",
  "inputs": {
    "image": "https://example.com/upper-body.jpg",
    "mode": "direction",
    "target_direction": "down",
  }
}

Aspect Ratio Mode

Transform images to match specific aspect ratios using generative filling:

{
  "model_name": "reframe",
  "inputs": {
    "image": "https://example.com/portrait.jpg",
    "mode": "aspect_ratio",
    "target_aspect_ratio": "1:1",
  }
}

Response Polling

After submitting your request, poll the status endpoint using the returned prediction ID. See API Fundamentals for complete polling details.

Successful Response

When your reframe operation completes successfully, the status endpoint will return:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "completed",
  "output": [
    "https://cdn.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.png"
  ],
  "error": null
}

The output array contains URLs to your reframed images with extended or reshaped content based on your selected mode and parameters.

Runtime Errors

Reframe may encounter the following model-specific errors during processing:

Name	Cause	Solution
`ImageLoadError`	The pipeline was unable to load the input image from the provided inputs.	For Image URLs: Ensure the URL is publicly accessible and not restricted by permissions. Verify that the Content-Type header specifies the correct image format (e.g., image/jpeg, image/png). For Base64-encoded images: Prefix the string with data:image/`format`;base64, where format is the image type (e.g., jpeg, png).
`InputValidationError`	Invalid parameter combination or missing required parameters for the selected mode.	Ensure `target_aspect_ratio` is provided when `mode: "aspect_ratio"`. Check that aspect ratio values are from the supported list.
`ThirdPartyError`	A third-party processor failed or refused to handle the request.	Most likely caused by content restrictions enforced by supporting services (e.g., image captioning). If that’s the case, try modifying your image inputs. If the issue persists across different inputs, contact support@fashn.ai with the prediction ID.
`PipelineError`	An unexpected error occurred during the execution of the pipeline.	Retry the request (you will not be charged for failed attempts). If the issue persists, please reach out to us at support@fashn.ai and include the prediction ID from the failed attempt to help us locate and address the issue promptly.

The Error Object

{
  "error": {
    "name": "InputValidationError",
    "message": "target_aspect_ratio is required when mode is 'aspect_ratio'"
  }
}

Example of an error when polling the /status endpoint:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Error loading input image: The URL's Content-Type is not an image. Content-Type: text/plain;charset=UTF-8"
  }
}

If you encounter an unrecognized error, please contact us at support@fashn.ai.

For detailed implementation guidance and best practices:

Image Preprocessing Best Practices - Optimize your source images for reframing operations

Reframe

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

Response

imageRequiredimage URL | base64

mode'direction' | 'aspect_ratio'

target_direction'both' | 'down' | 'up'

target_aspect_ratio'1:1' | '2:3' | '3:4' | '4:5' | '9:16' | '4:3'

Supported Aspect Ratios

seedinteger

output_format'png' | 'jpeg'

return_base64boolean

On this page