Skip to main content
Forma AI adds model-backed media understanding and generative image work to your pipeline. AI endpoints are available on the Pro plan and above, with separate AI unit quotas so media transforms, CDN delivery, and AI usage are metered independently. 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:
EndpointOutputOperations
POST /api/ai/toolsJSONimage.describe, image.alt-text, image.tags, image.moderate
POST /api/ai/transformImage 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.
FieldTypeDescription
operationstringOne of image.describe, image.alt-text, image.tags, image.moderate.
filefileImage upload. Required unless sourceUrl is provided.
sourceUrlstringPublic HTTP(S) image URL. Private networks, local hosts, and credentialed URLs are rejected.
promptstringOptional 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.
FieldTypeDescription
operationstringOne of image.edit, image.generate, image.upscale, image.background-replace, image.style-transfer.
promptstringInstruction for the transform. Required for editing operations.
storedFileIdstringReference an existing file in the caller’s library. Preferred when the source already lives in Convertly.
filefileImage upload — used when the source is not yet in your library.
sourceUrlstringPublic HTTP(S) URL. Same restrictions as the analysis endpoint.
aspectRatiostringOutput aspect ratio: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, or 21:9. Most useful with image.generate.
asyncbooleanWhen 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. With Pro overage at $0.002/unit that is roughly $0.16 per generated image; Business overage is $0.0015/unit.

​
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:
HeaderDescription
X-Convertly-AI-Limit-MonthIncluded monthly AI units.
X-Convertly-AI-Used-MonthAI units consumed in the current month.
X-Convertly-AI-Remaining-MonthIncluded units remaining before overage or cap.
X-Convertly-AI-Limit-MinutePer-minute AI burst limit.
X-Convertly-AI-Used-MinuteAI units consumed in the current minute.
Free and Starter plans receive a 402 response with an upgrade URL. Pro and Business accounts can continue past the included quota when overage billing is enabled. Enterprise plans use the same surface with larger allowances.

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