Transform Video

Take a still image you have uploaded and turn it into a video. A named effect supplies the motion.

Before you start

You need an assetId — the same three-call upload used by transforming an image, and the same assetId can drive both. Full details in uploading an image.

Minimal request

curl -X POST https://app.piernode.com/api/v1/videos/transformations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "assetId": "c8f2a1d4e5b64c9a8f3d2e1b0a9c8d7e",
    "effectId": "<effect-id>"
  }'

{
	"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.
`effectId`	string	yes	—	A named effect. Supplies the motion.
`prompt`	string	no	—	1–2000 characters, added to the effect's own instruction.
`resolution`	string	no	`hd`	`hd` or `fhd`.
`aspectRatio`	string	no	from the image	`16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `1:1`.
`durationSeconds`	int	no	`5`	`5` or `8`. No other length.

Unlike transforming an image, a prompt on its own is not a request this endpoint can run: the model behind it is driven by per-effect adapters, and the effect is what selects them. A request without an effectId is a 400.

prompt is still accepted, and is added to the effect's own instruction rather than replacing it — use it to nudge a result, not to describe the motion from scratch:

curl -X POST https://app.piernode.com/api/v1/videos/transformations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "c8f2a1d4e5b64c9a8f3d2e1b0a9c8d7e",
    "effectId": "<effect-id>",
    "prompt": "keep the background still",
    "durationSeconds": 8
  }'

Browse the catalogue at Effects, or GET /api/v1/effects?surface=video with no key.

Two lengths, not a range

durationSeconds is 5 or 8. This model produces those two lengths and no others, so unlike generating a video there is no range here and nothing in between — 6 is a 400, not a rounded-up 8.

It is priced per second all the same, at one rate per tier: an eight-second clip costs eight times what a second of it does, and durationSeconds is what that rate is multiplied by. See pricing.

Its own resolutions

hd and fhd, not text-to-video's 720p/1080p. The tier picks the output's base dimensions rather than an upscale applied to fixed ones, so the two products' numbers are not comparable and deliberately do not share names. fhd is 1280×720 on the long edge; hd is 832×480.

21:9 is not available here. 3:2 and 2:3 are.

Getting the result

Poll the task. On success the clip is under videos, in the same shape as generating a video.

Errors

400 with a message about the asset means the assetId is not a usable upload of yours. 400 about effectId means it is missing, unknown, or names an image effect — the message says which. Task failures carry the same error.code values as generating an image.