# Expand an image

> Grow a finished image outward by a number of pixels on each side, filling the new space with more of the same scene. Delivered as one image file.

**Endpoint:** `POST https://api.refabric.com/v1/tasks/image.expand` · **Task:** `image.expand` · **Scope:** `tasks:run` · **Category:** Image editing

Send a finished image and the pixels to add on each side. The new space is filled with more of the same scene, so you can reframe a picture for a wider or taller format without cropping anything away. At `4K` the grown image is also enlarged.

## Quick start

```python
import os
import time
import requests

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

job = requests.post(
    "https://api.refabric.com/v1/tasks/image.expand",
    headers=headers,
    json={
        "image": "art:9f2c01",
        "grow": {
            "top": 0,
            "right": 256,
            "bottom": 0,
            "left": 256,
        },
    },
).json()
print(job["job_id"])

while True:
    status = requests.get(job["status_url"], headers=headers).json()
    if status["lifecycle"] == "terminal":
        break
    time.sleep(5)

print(requests.get(job["result_url"], headers=headers).json())
```

```javascript
const headers = {
  Authorization: `Key ${process.env.REFABRIC_API_KEY}`,
  "Content-Type": "application/json",
};

const job = await fetch("https://api.refabric.com/v1/tasks/image.expand", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image": "art:9f2c01",
    "grow": {
      "top": 0,
      "right": 256,
      "bottom": 0,
      "left": 256
    }
  }),
}).then((r) => r.json());
console.log(job.job_id);

let status = job;
while (status.lifecycle !== "terminal") {
  await new Promise((r) => setTimeout(r, 5000));
  status = await fetch(job.status_url, { headers }).then((r) => r.json());
}

console.log(await fetch(job.result_url, { headers }).then((r) => r.json()));
```

```bash
curl -X POST "https://api.refabric.com/v1/tasks/image.expand" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"image":"art:9f2c01","grow":{"top":0,"right":256,"bottom":0,"left":256}}'
```

## Input schema

- `image` (string, _required_, pattern: ^(https://|art:|file:).+$) — The finished image to grow; what it already shows is untouched. As one string: a URL, a file from an earlier result (`art:…` or its url) or an upload (`file:…`). If it is one of your files placed in a project or on a design in the Refabric app, the result is filed there too.
  Example: `art:9f2c01`
- `grow` (object, _required_) — How many pixels of the source image to add on each side, `{top, right, bottom, left}` (whole numbers, 0 or more; an absent side is 0). At least one side must be more than 0. The new space is filled with more of the same scene. To reach an aspect ratio, work out the pixels from the image's size.
  Example: `{"top":0,"right":256,"bottom":0,"left":256}`
  - `top` (integer, _optional_, at least 0) — Pixels to add at the top.
  - `right` (integer, _optional_, at least 0) — Pixels to add at the right.
  - `bottom` (integer, _optional_, at least 0) — Pixels to add at the bottom.
  - `left` (integer, _optional_, at least 0) — Pixels to add at the left.
- `resolution` (string, _optional_, default: `2K`) — How large the result is; `4K` also enlarges the grown image. `2K` is sharp enough for screens and review; ask for `4K` when the result will be printed or zoomed into.
  Values: `2K` (Standard size, for screens and review.); `4K` (Large size, for print and zoom. When the image will be printed or zoomed into.)
  Example: `2K`

## Required-fields example

```json
{
  "image": "art:9f2c01",
  "grow": {
    "top": 0,
    "right": 256,
    "bottom": 0,
    "left": 256
  }
}
```

## Full example

```json
{
  "image": "art:9f2c01",
  "grow": {
    "top": 0,
    "right": 256,
    "bottom": 0,
    "left": 256
  },
  "resolution": "2K"
}
```

## Output schema

- `files` (array<object>, _optional_) — One file: the grown image. Pass it on to another edit to continue from it.

## Response example

```json
{
  "job_id": "d2b3c4d500004000800000000000000c",
  "lifecycle": "queued",
  "status_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000c",
  "result_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000c/result",
  "cancel_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000c/cancel"
}
```

## Result example

```json
{
  "job_id": "d2b3c4d500004000800000000000000c",
  "files": [
    {
      "file": "art:9f2c04",
      "url": "https://files.example.com/image.expand/1.png",
      "media_type": "image/png",
      "task": "image.expand",
      "job_id": "d2b3c4d500004000800000000000000c",
      "created_at": "2026-10-01T09:20:05Z"
    }
  ],
  "has_more": false
}
```

`grow` is the pixels to add per side (an absent side is 0; at least one must be more than 0). `resolution: 4K` also enlarges the grown image.

## Built for

- A portrait image reframed for a landscape banner
- Room around a product for text or a crop
- A tight shot given more background

## What you get

- One image: yours, with the new space around it filled with more of the same scene.

## Specs

- **Input formats:** Images, each one string: a URL, an upload (`file:…`) or a file from an earlier result (`art:…`). Upload types and sizes: `GET /v1/meta` `limits.upload`.
- **Input count:** `image`: one
- **Output format:** Files: each one line with its `url` and its `media_type`, in the job's result.
- **Output resolution:** `2K`, `4K`
- **Outputs per job:** One image file per job, however far the sides grow.

## Choosing a task

- Use this when you want more scene around the picture: a larger frame with new content in it. Use `image.upscale` when you want the same picture at a higher resolution, with nothing added.

## Errors

- `field_not_accepted`
- `invalid_request`
- `not_found`
- `permission_denied`
- `insufficient_credits`
- `content_refused`
- `processing_failed`
- `invalid_option`

## Related

- `photoshoot.create` — It runs before: its result is this input.
- `image.change_background` — It does a neighbouring job.
- `image.upscale` — It runs after: it takes this task's result.

## Good to know

- `grow.top` is at least 0.
- `grow.right` is at least 0.
- `grow.bottom` is at least 0.
- `grow.left` is at least 0.

## For agents and code generation

- https://api.refabric.com/v1/tasks/image.expand/llms.txt
- https://api.refabric.com/v1/tasks/image.expand/openapi.json
- GET https://api.refabric.com/v1/tasks/image.expand