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

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

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,
    "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:

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

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.

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

Quotas

MCP for agents

Forma AI runtime

​Analysis — /api/ai/tools

​Image transforms — /api/ai/transform

​Examples

​Costs

​Generative fill (in-app)

​Quotas

​MCP for agents

​Forma AI runtime

Analysis — `/api/ai/tools`

Image transforms — `/api/ai/transform`

Examples

Costs

Generative fill (in-app)

Quotas

MCP for agents

Forma AI runtime