> ## 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.

# Forma AI

> Forma AI media analysis and generative image transforms on every plan with a Forma AI unit quota.

Forma AI adds model-backed media understanding and generative image work to your pipeline. Every plan includes a monthly **Forma AI unit** allowance (Free: 500, Starter: 7,500, Pro: 20,000, Business: 100,000). Free and Starter hard-cap at the included quota; Pro and Business can continue with overage billing when enabled in Usage settings.

You do not bring model keys or manage AI vendors. Your app calls Convertly, Convertly runs the AI operation, and usage is billed through your Convertly plan.

There are two endpoint families:

| Endpoint                 | Output                                   | Operations                                                                                          |
| ------------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `POST /api/ai/tools`     | JSON                                     | `image.describe`, `image.alt-text`, `image.tags`, `image.moderate`                                  |
| `POST /api/ai/transform` | Image bytes (saved as a new stored file) | `image.edit`, `image.generate`, `image.upscale`, `image.background-replace`, `image.style-transfer` |

## Analysis — `/api/ai/tools`

Returns structured JSON describing the input image.

| Field       | Type   | Description                                                                                  |
| ----------- | ------ | -------------------------------------------------------------------------------------------- |
| `operation` | string | One of `image.describe`, `image.alt-text`, `image.tags`, `image.moderate`.                   |
| `file`      | file   | Image upload. Required unless `sourceUrl` is provided.                                       |
| `sourceUrl` | string | Public HTTP(S) image URL. Private networks, local hosts, and credentialed URLs are rejected. |
| `prompt`    | string | Optional context for the AI operation, up to 2,000 characters.                               |

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/ai/tools" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "operation=image.alt-text" \
  -F "sourceUrl=https://cdn.example.com/product.jpg" \
  -F "prompt=Write for an ecommerce product grid."
```

```json theme={"system"}
{
  "result": {
    "operation": "image.alt-text",
    "summary": "A white ceramic desk lamp on a clean studio background.",
    "altText": "White ceramic desk lamp photographed on a clean studio background.",
    "tags": ["lamp", "ceramic", "product-photo"],
    "categories": ["home decor"],
    "confidence": 0.86
  },
  "usage": { "units": 3, "operation": "image.alt-text" }
}
```

Analysis calls cost between `2` and `~10` AI units depending on the image size, so most Pro accounts run hundreds of analyses inside their monthly quota.

## Image transforms — `/api/ai/transform`

Generative endpoints that return a new image. The output is persisted to your Convertly storage automatically and returned as a `stored_files` row with a signed download URL.

| Field          | Type    | Description                                                                                                                        |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `operation`    | string  | One of `image.edit`, `image.generate`, `image.upscale`, `image.background-replace`, `image.style-transfer`.                        |
| `prompt`       | string  | Instruction for the transform. Required for editing operations.                                                                    |
| `storedFileId` | string  | Reference an existing file in the caller's library. Preferred when the source already lives in Convertly.                          |
| `file`         | file    | Image upload — used when the source is not yet in your library.                                                                    |
| `sourceUrl`    | string  | Public HTTP(S) URL. Same restrictions as the analysis endpoint.                                                                    |
| `aspectRatio`  | string  | Output aspect ratio: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, or `21:9`. Most useful with `image.generate`.              |
| `async`        | boolean | When `true`, the job is queued and the response returns a job id immediately. The worker runs the transform and stores the result. |

`image.generate` is the only operation that does not require a source image — the model produces an image purely from the prompt. Pair it with `aspectRatio` to control the canvas shape, for example a `16:9` hero image or a `9:16` story.

### Examples

Edit an image already in the user's library:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/ai/transform" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "operation=image.edit" \
  -F "storedFileId=$FILE_ID" \
  -F "prompt=Make the background a clean white studio."
```

```json theme={"system"}
{
  "file": {
    "id": "c4c5fb2a-5a78-4e2b-8e7d-2d9e90e88f54",
    "filename": "make-the-background-a-clean-white-studio.png",
    "mime_type": "image/png",
    "size_bytes": 281024,
    "storage_path": "u/.../ai-generated/...png",
    "metadata": {
      "ai_operation": "image.edit",
      "ai_prompt": "Make the background a clean white studio.",
      "ai_source_file_id": "..."
    }
  },
  "result": {
    "operation": "image.edit",
    "storedFileId": "c4c5fb2a-...",
    "filename": "make-the-background-a-clean-white-studio.png",
    "mimeType": "image/png",
    "size": 281024,
    "downloadUrl": "https://.../signed-url",
    "prompt": "Make the background a clean white studio."
  },
  "usage": { "units": 78, "operation": "image.edit" }
}
```

Generate from a text prompt with no source image:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/ai/transform" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "operation=image.generate" \
  -F "prompt=A minimal product photo of a coffee mug on a marble countertop, soft morning light."
```

Queue a long-running job instead of waiting for the response:

```bash theme={"system"}
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"
```

```json theme={"system"}
{
  "job": { "id": "0d8f...", "status": "queued" },
  "usage": { "units": 76, "operation": "image.upscale" }
}
```

### Costs

Image-out operations are charged as `75` units base plus `1` unit per MB of source image. A 4 MB edit therefore costs **79 units**. Monthly allowances, hard caps, and overage rates are in [Limits](/limits#forma-ai).

## Generative fill (in-app)

Convertly's editor at `/app/editor/<id>` exposes an Expand tool that surfaces the generative-fill capability directly. Drag the canvas handles outward to add space on any side, optionally write a guidance prompt, and click **Generative fill with Forma AI**.

The editor composites the current preview onto a larger transparent canvas in the browser, then sends that composite to `/api/ai/transform` with `operation=image.outpaint`. Forma AI fills the transparent regions with content that continues the existing scene. The result lands as a new step in the edit stack and is auto-saved to the user's library.

The same outcome can be reproduced server-side by submitting a multipart `file` already padded with transparent pixels to `operation=image.outpaint` — the behaviour is identical.

## Quotas

AI endpoints use `X-Convertly-AI-*` response headers, shared between the analysis and transform routes:

| Header                           | Description                                     |
| -------------------------------- | ----------------------------------------------- |
| `X-Convertly-AI-Limit-Month`     | Included monthly AI units.                      |
| `X-Convertly-AI-Used-Month`      | AI units consumed in the current month.         |
| `X-Convertly-AI-Remaining-Month` | Included units remaining before overage or cap. |
| `X-Convertly-AI-Limit-Minute`    | Per-minute AI burst limit.                      |
| `X-Convertly-AI-Used-Minute`     | AI units consumed in the current minute.        |

Free and Starter plans receive a `402` when the monthly Forma AI quota is exhausted (no overage). Pro and Business accounts can continue past the included quota when overage billing is enabled. Enterprise plans use the same surface with larger allowances. See [Limits](/limits) for included units per plan.

## MCP for agents

The Convertly MCP server (`@convertly-sh/mcp`) exposes Forma AI to Claude, Cursor, and other MCP clients:

| MCP tool             | API                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `forma_ai_transform` | `POST /api/ai/transform` — generate, edit, upscale, background replace, style transfer, outpaint, object remove |
| `forma_ai_analyze`   | `POST /api/ai/tools` — describe, alt-text, tags, moderate                                                       |

Useful when the connected model cannot generate images natively: the agent calls Convertly with your API key and Forma AI units. See [MCP for AI agents](/docs/mcp-agents).

## Forma AI runtime

Forma AI is a managed Convertly service. The underlying model runtime may change by operation, region, cost, latency, or quality target, but the public API response shapes remain stable. All calls are authenticated and billed through your Convertly API key — there is nothing to configure on your side.