Tools

Photo to Video

Turn a start photo — and optionally an end photo — into a video. With an end photo the camera travels from the first photo and lands exactly on the second (e.g. two views of the same kitchen → an orbit around the island). Pick a ready-made camera move or write your own prompt; choose the model, length and sound.

post/api/v1/tools/photo_to_video

Request

  • Base URL: https://pixly.app
  • URL: https://pixly.app/api/v1/tools/photo_to_video
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://pixly.app/oauth/authorize, token URL https://pixly.app/api/oauth/token, scopes: tools)

Headers

Idempotency-Keystring

Recommended. A retry with the same key and body returns the first run's result (header Idempotency-Replayed: true) instead of running and charging again. Kept 24 hours; failed runs release the key.

Request body

imageUrlstring

Start frame — where the video begins. Public https URL or data: URI; either imageUrl or r2Path is required.

r2Pathstring

Storage path of a photo already in the user's Pixly library (from list_library, or returned by an upload ticket) — the alternative to imageUrl.

endImageUrlstring

Optional end frame — the camera travels from the start photo and lands exactly on this one. Best when both photos show the same space from different spots.

endR2Pathstring

R2 path of the end frame — the alternative to endImageUrl.

cameraMove'smooth' | 'walk' | 'orbitLeft' | 'orbitRight' | 'pushIn' | 'pullBack' | 'riseUp'

Ready-made camera move used when no prompt is given.

promptstring

Your own description of the video, in any language. Replaces cameraMove when set.

model'kling-v3' | 'kling-2.6'

kling-v3: 3/5/8/10/15 s, optional sound, lands most precisely on the end frame. kling-2.6: 5/10 s, silent, cheaper.

durationSecondsinteger

Clip length. kling-v3 takes 3, 5, 8, 10 or 15; kling-2.6 takes 5 or 10.

soundboolean

Add ambient sound (kling-v3 only; kling-2.6 is always silent).

format'original' | '16:9' | '9:16' | '1:1'

Video shape. original (default) keeps the start photo's own shape; 16:9, 9:16 or 1:1 crop the photos, centred, to that shape before they are animated.

Response

Finished inline — resultUrls present (photo tools)

jobIdstring required

Job id — pass to get_job to poll

type'image_staging' | 'video_pair' | 'video_tour' required

Job family

status'pending' | 'processing' | 'completed' | 'failed' required

Anything not completed/failed is still running

creditsChargednumber nullable required

Credits debited for this job

createdAtstring date-time required

Submission time

completedAtstring date-time

Present once finished

resultUrlsstring[]

Presigned download URLs (present when completed; valid 7 days)

resultPathsstring[]

Storage path of each result, in resultUrls order — pass one as r2Path (or beforeR2Path, a photos[] item…) to run another tool on this result

errorstring

Failure reason; the message says whether the credit came back immediately or is in 24h refund review

notestring

Hint for agents, e.g. poll again in a few seconds

Changes

No recorded changes to this operation across all 1 revision of this API.