Refabric Docs

For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-api-reference/image.expand.md, and the index of every page is https://docs.refabric.com/llms.txt.

Image editing

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.expandTask: image.expandScope: tasks:runCategory: Image editing

Quick start

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())

cURL waits for the result with Prefer: wait; when the job outlives the wait, it answers 202 with the job's URLs.

Input schema

  • stringrequired

    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.

    pattern: ^(https://|art:|file:).+$

    Example: art:9f2c01

  • objectrequired

    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}

  • stringoptionalDefault: 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

Output schema

  • array<object>optional

    One file: the grown image. Pass it on to another edit to continue from it.

Required-fields example

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

Full example

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

Response example

{
  "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

{
  "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.

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.

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 formatsImages, 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 countimage: one
Output formatFiles: each one line with its url and its media_type, in the job's result.
Output resolution2K, 4K
Outputs per jobOne image file per job, however far the sides grow.

Choosing a task

Errors

Related

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.

Pricing: Estimate a request before you run it, or see the price of each option.

For agents and code generation

Schema changes follow Versioning.