Transform Image

Take an image you have uploaded and transform it with a prompt. The request returns a task; the result arrives when you poll it.

Before you start

You need an assetId. Three calls, once per input image:

# 1. reserve — the response carries the id and the URL to send the bytes to
ASSET=$(curl -s -X POST https://app.piernode.com/api/v1/uploads \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentType": "image/png"}')
ASSET_ID=$(echo "$ASSET" | jq -r .id)
UPLOAD_URL=$(echo "$ASSET" | jq -r .uploadUrl)

# 2. send the bytes
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @photo.png

# 3. verify
curl -X POST https://app.piernode.com/api/v1/uploads/$ASSET_ID/complete \
  -H "Authorization: Bearer $PIERNODE_API_KEY"

# $ASSET_ID is what the requests below send as assetId.

Full details in uploading an image. Uploads are not billed, and one upload can be reused across as many generations as you like.

Minimal request

curl -X POST https://app.piernode.com/api/v1/images/transformations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "assetId": "c8f2a1d4e5b64c9a8f3d2e1b0a9c8d7e",
    "prompt": "make the sky look like dusk"
  }'

{
	"id": "fu0825tesv0laouebtjx0x5w",
	"status": "QUEUED",
	"createdAt": "2026-01-01T12:00:00.000Z"
}

Parameters

Field	Type	Required	Default	Description
`assetId`	string	yes	—	A `READY` upload of yours.
`prompt`	string	see note	—	1–2000 characters.
`effectId`	string	see note	—	A named effect that supplies the prompt.
`resolution`	string	no	`hd`	`hd` or `fhd`. Sets the price.
`aspectRatio`	string	no	from the image	`1:1`, `9:16`, `16:9`, `4:3`, `3:4`, `3:2`, `2:3`.

Send prompt, effectId, or both — a request with neither is a 400.

Two things differ from generating an image: the resolution values are hd/fhd rather than 1k/2k/4k, and there is no negativePrompt.

Leave aspectRatio out and the closest ratio to your uploaded image is used, which is usually what you want.

Using an effect instead of a prompt

An effect is an instruction PierNode maintains, named by a short id and sent as effectId in place of writing the instruction yourself. None is published for this endpoint yet — the field is accepted and resolved, so an id will work here the day one exists. A prompt on its own remains the ordinary request.

Browse what is available at Effects, or GET /api/v1/effects with no key.

Getting the result

Poll the task. On success:

{
	"status": "SUCCEEDED",
	"output": {
		"images": [{ "url": "https://...", "contentType": "image/png", "sizeBytes": 576963 }]
	}
}

Errors

400 with a message about the asset means the assetId is not a usable upload of yours — it does not exist, belongs to someone else, or was never completed. The three cases answer identically on purpose.

Task failures carry the same error.code values as generating an image, and release the reservation in full.