Skip to main content
POST
/
api
/
ai
/
transform
Run a Forma AI image transform
curl --request POST \
  --url https://convertly.sh/api/ai/transform \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'
{
  "file": {},
  "result": {
    "operation": "<string>",
    "storedFileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "filename": "<string>",
    "mimeType": "<string>",
    "size": 123,
    "downloadUrl": "<string>",
    "prompt": "<string>"
  },
  "usage": {
    "units": 123,
    "operation": "<string>"
  }
}

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