Skip to main content
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 the Pro plan and above and bill against your monthly AI unit allowance.
The in-app editor and POST /api/ai/transform share the same monthly AI unit allowance on Pro and above.
For the full endpoint reference, see Forma AI.

​
In the editor

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

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

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.

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

OperationNeeds sourceWhat it does
image.editYesApply a described change, preserving subjects.
image.generateNoCreate an image from a text prompt.
image.upscaleYesProduce a higher-resolution version.
image.background-replaceYesComposite the subject onto a new background.
image.style-transferYesReimagine the image in a new visual style.
image.outpaintYesExtend 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) are far cheaper. Pro includes 5,000 units/month with overage at 0.002/unit;Businessincludes35,000at0.002/unit; Business includes 35,000 at 0.0015/unit. Quota headers (X-Convertly-AI-*) return on every response.