Reframe

Reframe intelligently adjusts image aspect ratios using AI-powered content analysis. The model analyzes your image and automatically decides whether to expand (outpaint/zoom-out) or crop (zoom-in) to reach the target aspect ratio while preserving important content.

Model Specifications

Model Name: reframe
Lifecycle: experimental
Processing Time: 20s–120s (see below)
Credits: 1-5 per output image depending on resolution and generation_mode

Request

Reframe images by submitting the source image and target aspect ratio 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",
             "aspect_ratio": "16:9"
           }
         }'

Response

Returns a prediction ID for status polling:

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

Request Parameters

`image`
Required
image URL | base64

Source image to reframe to a new aspect ratio. The AI analyzes the image content and intelligently decides whether to expand or crop based on subject position, content density, and edge details.

Base64 Format

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

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

Target aspect ratio for the reframed image. The AI determines whether expansion or cropping is more appropriate based on the current image content and dimensions.

`resolution`'1k' | '2k' | '4k'

Output resolution tier. '1k' produces ~1 megapixel output, '2k' ~4 megapixels, and '4k' ~16 megapixels. Exact output dimensions depend on this tier and the image aspect ratio.

Default: '1k'

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

Sets the generation quality level. 'quality' produces the most detailed and realistic output but takes longer to process and costs more credits. 'fast' prioritizes speed and lower cost. If omitted, FASHN selects generation_mode automatically. For reframe, omitted generation_mode is currently billed as 'fast' at 1k and as 'quality' at 2k or 4k.

`num_images`integer

Number of images to generate in a single run. Image generation has a random element, so generating multiple images increases the chances of getting a good result.

Default: 1 Range: 1 to 4

`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 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

Credit Cost

`generation_mode` \ `resolution`	`1k`	`2k`	`4k`
`fast`	1	2	3
`balanced`	2	3	4
`quality`	3	4	5

Additional pricing rules:

num_images multiplies the total cost by the number of outputs requested.
If generation_mode is omitted, automatic pricing applies.

Processing Time

Processing time depends on both resolution and generation_mode. The fastest configuration (fast + 1k) typically completes in under 20 seconds, while the most intensive (quality + 4k) can take up to 120 seconds. Actual latency may vary with current server load.

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, adjusted to the target aspect ratio.

Runtime Errors

Reframe shares the common runtime errors in Error Handling.

In addition, Reframe may return:

Error	Description
`InputValidationError`	Image already matches target aspect ratio

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

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

Supported Aspect Ratios

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

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

num_imagesinteger

seedinteger

output_format'png' | 'jpeg'

return_base64boolean

On this page