Forma AI

Forma AI adds model-backed media understanding and generative image work to your pipeline. Every plan includes a monthly Forma AI unit allowance (Free: 200, Starter: 3,000, Pro: 12,000, Business: 50,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 output (saved to the library for API calls; temporary in the editor until you save)	`image.edit`, `image.generate`, `image.upscale`, `image.background-replace`, `image.style-transfer`, `image.outpaint`, `image.object-remove`

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.

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

{
  "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 return a new image. The output is persisted to your Convertly storage automatically and returned as a file record with a signed download URL.

Field	Type	Description
`operation`	string	One of `image.edit`, `image.generate`, `image.upscale`, `image.background-replace`, `image.style-transfer`, `image.outpaint`, or `image.object-remove`.
`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:

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

{
  "file": {
    "id": "c4c5fb2a-5a78-4e2b-8e7d-2d9e90e88f54",
    "filename": "make-the-background-a-clean-white-studio.png",
    "mime_type": "image/png",
    "size_bytes": 281024,
    "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:

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:

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": "0d8f...", "status": "queued" },
  "usage": { "units": 76, "operation": "image.upscale" }
}

Costs

At the default 1K output size, generative image operations use 100 units plus 1 unit per MB of source and reference images. A 4 MB edit therefore uses 104 units. The base is 150 units at 2K and 225 units at 4K. Standard studio upscaling is free; generative edits, outpainting, object removal, background replacement, and style transfer use the Forma AI pool. Monthly allowances, hard caps, and overage rates are in Limits.

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 temporary step in the edit stack; it is written to the library only when the user chooses Save or Save as copy. 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.

Background-removal previews

The Remove BG quick action in the file lightbox runs managed ML subject segmentation. It automatically chooses a small, medium, or large cutout model from the image complexity. The preview uses 5 Forma AI units plus 1 unit per MB of source image; saving an accepted preview does not charge those units again. If the source already contains a meaningful transparent cutout, Convertly preserves it and uses 0 Forma AI units. The standalone POST /api/media/remove-background Media Tools endpoint is metered as a Media API operation instead. It uses the same managed segmentation service but does not consume the Forma AI pool.

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

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.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Analysis — `/api/ai/tools`

Image transforms — `/api/ai/transform`

Examples

Costs

Generative fill (in-app)

Background-removal previews

Quotas

MCP for agents

Forma AI runtime

​Analysis — /api/ai/tools

​Image transforms — /api/ai/transform

​Examples

​Costs

​Generative fill (in-app)

​Background-removal previews

​Quotas

​MCP for agents

​Forma AI runtime

Analysis — `/api/ai/tools`

Image transforms — `/api/ai/transform`

Examples

Costs

Generative fill (in-app)

Background-removal previews

Quotas

MCP for agents

Forma AI runtime