> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Transform images with Forma AI

> Edit, restyle, upscale, replace backgrounds, and outpaint images with Forma AI — from the editor or the API.

Forma AI brings generative image operations to Convertly. It runs two ways: visually in the in-app editor, and programmatically through `POST /api/ai/transform`. Both are available on every plan and bill against your monthly Forma AI unit allowance.

<div className="convertly-callout">
  The in-app editor and `POST /api/ai/transform` share the same monthly Forma AI unit allowance. Free and Starter hard-cap at the included quota; Pro and Business can continue with overage billing when enabled.
</div>

For the full endpoint reference, see [Forma AI](/docs/ai-tools).

## In the editor

Open any image at **Files → (pick an image) → Edit in editor**. Two surfaces use Forma AI:

<Steps>
  <Step title="Quick transforms — the Forma AI bar">
    The bar pinned to the bottom of the canvas runs prompt-driven operations against the current image: **Edit**, **Background** replace, **Restyle**, and **Upscale**. Pick an operation, describe what you want, and send. The result is generated, dropped onto the canvas, added to your edit stack, and saved to your library.
  </Step>

  <Step title="Generative fill — the Expand tool">
    Select the **Expand (AI)** tool in the sidebar. Drag the outer handles to grow the canvas past the image edges — the new area shows a checkerboard so you can see what will be filled. Optionally describe the scene in the prompt box, then click **Generative fill with Forma AI**.

    The editor composites your image onto the larger canvas and asks Forma AI to outpaint the transparent regions so they continue the existing scene. Larger expansions run as a background job, so the button stays responsive while the worker finishes.
  </Step>
</Steps>

## Via the API

Reference an image already in your library by `storedFileId`, upload a `file`, or pass a public `sourceUrl`. `image.generate` needs no source.

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/ai/transform" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "operation=image.background-replace" \
  -F "storedFileId=$FILE_ID" \
  -F "prompt=A bright minimalist studio with soft shadows"
```

The response includes the generated file's `storedFileId` and a signed `downloadUrl`. The output is saved to your library automatically, so you can pipe it straight into a conversion, CDN URL, or workflow.

### Long-running jobs

Upscales and outpaints can take longer than a typical request. Add `async=true` to enqueue the job and poll for the result:

```bash theme={"system"}
# Enqueue
curl -X POST "https://convertly.sh/api/ai/transform" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "operation=image.upscale" \
  -F "storedFileId=$FILE_ID" \
  -F "async=true"
# -> { "job": { "id": "...", "status": "queued" } }

# Poll
curl "https://convertly.sh/api/ai/transform/jobs/$JOB_ID" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
# -> { "job": { "status": "completed" }, "result": { ... } }
```

## Operations

| Operation                  | Needs source | What it does                                         |
| -------------------------- | ------------ | ---------------------------------------------------- |
| `image.edit`               | Yes          | Apply a described change, preserving subjects.       |
| `image.generate`           | No           | Create an image from a text prompt.                  |
| `image.upscale`            | Yes          | Produce a higher-resolution version.                 |
| `image.background-replace` | Yes          | Composite the subject onto a new background.         |
| `image.style-transfer`     | Yes          | Reimagine the image in a new visual style.           |
| `image.outpaint`           | Yes          | Extend the image into surrounding transparent areas. |

## Cost

Image transforms cost **75 AI units** plus **1 unit per MB** of source image. Analysis operations (alt text, tags, descriptions, safety) use fewer units. Every plan includes a monthly Forma AI allowance; Free and Starter hard-cap at the included quota; Pro and Business can continue with overage when enabled. Quota headers (`X-Convertly-AI-*`) return on every response. Allowances and overage rates: [Limits](/limits#forma-ai).