Skip to main content
POST
Run a Forma AI image transform

Authorizations

Authorization
string
header
required

Dashboard-generated Convertly API key. Keys currently begin with cvly_.

Body

multipart/form-data
operation
enum<string>
required

Transform operation to apply. image.generate does not require a source image; all others do.

Available options:
image.edit,
image.generate,
image.upscale,
image.background-replace,
image.style-transfer,
image.outpaint
prompt
string

Instruction for the transform. Required for editing operations.

Maximum string length: 2000
file
file

Image upload. Used when the source is not yet in your library.

storedFileId
string<uuid>

Reference an existing file in your library as the source.

sourceUrl
string<uri>

Public HTTPS image URL. Private networks and credentialed URLs are rejected.

aspectRatio
enum<string>

Output aspect ratio. Most useful for image.generate, which has no source to inherit dimensions from.

Available options:
1:1,
16:9,
9:16,
4:3,
3:4,
3:2,
2:3,
21:9
async
boolean
default:false

When true, the job is enqueued and the response returns a job id immediately. Poll GET /api/ai/transform/jobs/{jobId} for the result.

Response

Synchronous transform — returns the produced file row and a signed download URL.

file
object
result
object
usage
object
Last modified on July 31, 2026