Outpaint (Aspect Ratio)

Expand the canvas of an image to a target aspect ratio (e.g. 16:9, 1:1, 9:16). The model decides where to add content - no need to specify per-side expand percentages.

Pricing: $0.55/request. Endpoint: POST /v1/models/runflow/outpaint/aspect-ratio/runs.

Expand the canvas of an image to a target aspect ratio (e.g. 16:9, 1:1, 9:16). The model decides where to add content - no need to specify per-side expand percentages.

Overview

• Endpoint: https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs
• Model ID: runflow/outpaint/aspect-ratio
• Provider: Runflow
• License: commercial
• Last Updated: 2026-05-03

Pricing

• Base price: $0.55/request
• Note: Per image - outpainting to target aspect ratio

Outpaint (Aspect Ratio) API

Endpoint: POST /v1/models/runflow/outpaint/aspect-ratio/runs

Run the model

Python

import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/outpaint/aspect-ratio/examples/2/before.png",
            "aspect_ratio": "9:16"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)

Node.js

const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "image_url": "https://public.runflow.io/images/models/runflow/outpaint/aspect-ratio/examples/2/before.png",
            "aspect_ratio": "9:16"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);

cURL

curl -X POST https://api.runflow.io/v1/models/runflow/outpaint/aspect-ratio/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "image_url": "https://public.runflow.io/images/models/runflow/outpaint/aspect-ratio/examples/2/before.png",
        "aspect_ratio": "9:16"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON

Request parameters

Parameter	Type	Required	Description
input	object	required	Model input parameters. See “Input schema” below.
callback_url	string | null	optional	Webhook URL - POSTed when the run reaches a terminal state.
metadata	object | null	optional	Arbitrary key-value pairs attached to the run.

Input schema

Field	Type	Required	Allowed values	Description
image_url	image	required	Any	URL of the inputs to process - typically a .zip produced by the frontend. bg-brain downloads it to /tmp/inputs/ and unzips with filenames preserved. HTTPS required.
justification	string	optional	center, manual, top-left, bottom-right, expand-all	Where to anchor the source image inside the expanded aspect ratio. “center” pads all sides equally. “top-left” pins the top-left corner and pads bottom-right. “bottom-right” pins the bottom-right corner and pads top-left. “expand-all” pads all sides. “manual” uses the explicit top/bottom/left/right percentages on the workflow.
aspect_ratio	string	required	Any	Target output aspect ratio. Examples: “1:1” (square), “16:9” (widescreen), “9:16” (portrait), “4:3”, “3:4”, “21:9” (cinematic).

Output schema

Field	Type	Description
outputs	json	Array of result items, each with at minimum a url field.
seed	json	Random seed used (null if N/A).
timing	json	Provider timing breakdown (null if not surfaced).
nsfw_detected	json	Provider NSFW flag (null if not surfaced).

Callback payload

When you provide a callback_url, Runflow POSTs to it once the run reaches a terminal state.

Field	Type	Description
event	string	Event type: “run.completed”, “run.failed”, or “run.cancelled”.
run_id	string	The unique identifier of the run.
status	string	Terminal status: “succeeded”, “failed”, or “cancelled”.
output	object | null	The run output. Null if the run failed or was cancelled.
duration_ms	number | null	Total run duration in milliseconds.
created_at	string | null	ISO 8601 timestamp when the run was created.
completed_at	string | null	ISO 8601 timestamp when the run reached terminal state.
metadata	object | null	The metadata object passed at run creation, if any.

• Retries: 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
• Headers: Runflow-Request-Id is always sent. Runflow-Signature is sent if a signing secret is configured.

Additional Resources

• Playground
• API Reference
• Documentation
• OpenAPI

Related

Browse all models

Browse the catalog.

Run lifecycle

Callbacks, polling, statuses.

Callbacks

Handle async results.

Pricing

How requests bill out.