Reference · Video
Make a clip from words, frames, references or a video to follow
Make a clip — from words, from a start (and end) frame, from reference pictures, clips and sounds, or by working on a video: carry it on (extend), change it (edit), or have the character in a picture take its moves (motion) — the Video page’s run. Pick the model with GET /api/v1/models (studio "video"): each lists its lengths, shapes, sizes, sound, the inputs it takes and what its bar says of them. Files go in as storage keys or https links to them. The words name each reference by its @name — its atName from GET /api/v1/library or POST /api/v1/library/use — as in "@vera holds @osmelle up to the camera", with the names in referenceNames in the order of the keys; one with no name goes by its place: @Image1, @Video1, @Audio1. A sound on its Audio refs sets how a line sounds, never what is said: the words are the prompt’s quotes. A real person’s face or voice in a file the person brings needs their say-so (whoIsInPicture, whoIsInVideo, whoseAudio); the quote states it in full. It comes back as a job (kind "video") to follow with GET /api/v1/jobs/{jobId}.
- Key needs
create· Make things and spend credits- Price it first
POST /videos/quote· free- Answers
- A job to follow
curl -X POST https://vessero.com/api/v1/videos \ -H "Authorization: Bearer $VESSERO_API_KEY" \ -H "Idempotency-Key: 47f8f6f5-ea00-4fb1-925f-76aac956a0ec" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.5", "prompt": "A slow push in on a steaming coffee cup on a café table", "durationSec": 5, "firstKey": "https://example.com/frames/coffee-cup.jpg", "confirmCredits": 58, "webhookUrl": "https://example.com/hooks/vessero" }'
{ "object": "job", "id": "video.8f1c2d3e-4b5a-4789-8abc-def012345678", "kind": "video", "status": "working", "stage": "Queued", "files": [], "credits": 58, "url": "/api/v1/jobs/video.8f1c2d3e-4b5a-4789-8abc-def012345678" }
The same body without confirmCredits. It answers the price and your balance, and runs nothing.
Header
- Idempotency-KeystringYour id for this request: 8–64 letters, digits, - or _. A repeat within 10 minutes gets the first answer back and never runs twice. Use the same one for the quote and the run.
- Preferstring
wait=N(up to 60): hold the answer up to N seconds while the job is made, within 80 seconds for the whole call.
Body
- promptstringWhat happens in the shot, e.g. "Slow push in on the bottle as morning light sweeps across the table". For an edit, the change to make; to extend, what happens next. Optional only for motion, whose moves come from the video.
- modelstringrequiredA video model id from GET /api/v1/models (studio "video"), e.g. "seedance-2.5"; Genjutsu’s motion transfer and object swap are listed under studio "genjutsu".
- durationSecintegerSeconds, one of the model’s durations. Default: its own length, as /video starts it (defaultDurationSec in GET /api/v1/models).
- aspectRatiostringA shape the model lists, e.g. "9:16". Default: the model’s own.
- resolutionstringA size the model lists, e.g. "720p". Default: the model’s own.
- audiobooleanSound, on a model where it is optional (sound "optional"); it may cost more.
- musicbooleanBackground music of the model’s own, on a model with a Music switch (music "optional" in GET /api/v1/models: Seedance), while sound is on. false: no background music — only the voices and sounds the prompt asks for. true: the model may add its own. Default: false, as the Video page starts it. Never moves the price.
- draftbooleanA draft, on a model with the switch (draft in GET /api/v1/models: Seedance 2.5): made at its draft resolution (480p) and that price, a quick look. The clip worth keeping is made sharp with upgradeDraftOf, within its days. Default: off.
- loopbooleanA clip that loops, on a model that makes one (loop "optional" in GET /api/v1/models: Grok Imagine 1.5): the start frame is the end frame too. Only with firstKey and no lastKey. Never moves the price.
- cutsbooleanCuts, on a model with the switch (cuts "optional" in GET /api/v1/models: PixVerse v6, Kling O3): the model plans a few shots in one clip — never between firstKey and lastKey, beside shots of the person’s own, or with a reference clip. Never moves the price.
- seedintegerA seed, on a model that takes one (seed "optional" in GET /api/v1/models: PixVerse v6, v6 Max): the same seed and settings help make the same clip again. Default: a new one each run. Never moves the price.
- effectIdstringAn effect, by its id from GET /api/v1/models (effects, on PixVerse v6): a ready-made motion — a product turned into a landmark, a dance trend, a stadium moment — from the person’s own pictures in effectKeys. The effect fixes the clip’s length, and its price follows it; send no durationSec, frames or references with it. Words are optional: without them the effect’s name goes.
- effectKeysstring[] · up to 2The effect’s pictures, as many as it takes (its pictures in GET /api/v1/models: 1 or 2), in order.
- referenceLinkstring · httpsA public web page the clip is made from, by its https:// link, on a model that reads one (page "optional" in GET /api/v1/models: Wan 3.0, Wan 3.0 Prime): one that opens without signing in, read by the model for what the clip shows. Never with firstKey or lastKey. Never moves the price.
- upgradeDraftOfstringA finished draft of theirs, by its id (from this tool or GET /api/v1/work, which says which clips are drafts): make it sharp — the same take at its model’s upgrade resolution (1080p), priced at that rate for its length — rather than a new clip. Send it with the draft’s model alone.
- modelModestringThe way the model runs, on one that runs more than one way (ways in GET /api/v1/models): Kling 4.0’s keyframes — firstKey, keyframeKeys and lastKey, in that order — or omni, its references; Grok Imagine 1.5’s frames (its start, end and frames between, or a loop) or refs. Default: the way what is sent calls for: references run on the way that takes them.
- firstKeystringThe start frame, a picture: a storage key from POST /api/v1/files or POST /api/v1/library/use, or an https link to the file (brought into their Uploads first).
- lastKeystringThe end frame, a picture, on a model that takes one: a storage key from POST /api/v1/files or POST /api/v1/library/use, or an https link to the file (brought into their Uploads first).
- keyframeKeysstring[] · up to 8Frames between firstKey and lastKey, in order, on a way that takes them: on Kling 4.0’s keyframes up to 8, and no more frames in all than one more than the clip’s seconds; on Grok Imagine 1.5’s frames up to 4, one fewer than its seconds, each at an even whole second. Named @Keyframe1… in the words.
- referenceKeysstring[] · up to 30Reference pictures, up to the model’s own number (inputs.pictures).
- referenceVideoKeysstring[] · up to 10Reference clips, up to the model’s own number (inputs.videos). Priced by their length where the model bills it.
- referenceAudioKeysstring[] · up to 10Reference sounds, up to the model’s own number (inputs.sounds; its audioRefs says what each takes). On a model that takes any sound (Seedance, Wan 3.0) each is what the prompt makes it, called by its @name or @Audio1, @Audio2… in the order sent: a voice whose timbre, tone and accent the clip speaks in, a song or a bed under it, or a sound effect. Never lip-synced to and never transcribed — write what is said in quotes in the prompt. For a recording said as it is, lip-synced, use POST /api/v1/avatars.
- referenceNamesobjectWhat the words call each reference, as its tile does: its @name, such as "@vera", one list a kind in the order of its keys (images for referenceKeys, videos for referenceVideoKeys, audio for referenceAudioKeys), null for one with no name, which the words call by its place (@Image2). Each name goes to the model as the reference it calls. Never moves the price. A reference’s @name is the atName GET /api/v1/library and POST /api/v1/library/use give.
- images(string | null)[] · up to 30The @names of referenceKeys, in the order of its keys.
- videos(string | null)[] · up to 10The @names of referenceVideoKeys, in the order of its keys.
- audio(string | null)[] · up to 10The @names of referenceAudioKeys, in the order of its keys.
- whoseAudioobject · kind no-voice | voiceWhose voice is in the reference sounds, as the person says: {kind: "no-voice"}, or {kind: "voice", name, agreed} for a real person’s. Not asked of sounds made in Vessero.
- parentIdstringA finished clip of theirs to work on, by its id (from this tool or GET /api/v1/work). Give this or sourceVideoKey.
- sourceVideoKeystringA video to work on, uploaded: a storage key from POST /api/v1/files or POST /api/v1/library/use, or an https link to the file (brought into their Uploads first).
- sourceStartSecnumberWhere in the video to start, in seconds.
- sourceEndSecnumberWhere in the video to end, in seconds.
- clipUsestringWhat to do with the video put in (parentId or sourceVideoKey), on a model that does it (worksOnVideo): extend it, edit it (the default), or motion — the character on firstKey takes its moves.
extendeditmotion - keepSoundbooleanAn edit: keep the video’s own sound (the default, where the model can) or make new.
- motionFacingstringMotion: the character faces as in the clip or as in the picture.
clippicture - motionBackgroundstringMotion: the clip’s background or the picture’s.
clippicture - whoIsInPictureobject · kind no-person | personMotion: who is in the picture on firstKey, as the person says; asked of an uploaded picture.
- whoIsInVideoobject · kind no-person | personWho is in the uploaded video, where the model keeps its people (an edit that keeps them).
- shotsobject[] · up to 6A clip in shots, on a model that takes a storyboard (inputs.storyboard): its own number of shots, each its own seconds. On Kling O3 the shots go beside reference pictures (referenceKeys), and no clip goes with them.
- promptstringrequiredWhat happens in this shot.
- durationSecintegerrequiredIts seconds.
- presetIdstringThe style a job runs in, on a model that has styles (presets in GET /api/v1/models: Restyle): one of its presets.choices ids. Needed where presets.required.
- camerastringA camera move added to the words: dolly-in (Dolly in), dolly-out (Dolly out), crash-zoom (Crash zoom), orbit-360 (360 orbit), crane-up (Crane up), whip-pan (Whip pan), fpv-dive (FPV dive), handheld (Handheld), bullet-time (Bullet time), snorricam (Snorricam), drone-reveal (Drone reveal), locked-off (Locked-off). Never changes the price.
dolly-indolly-outcrash-zoomorbit-360crane-upwhip-panfpv-divehandheldbullet-timesnorricamdrone-reveallocked-off - confirmCreditsintegerrequiredThe price you agree to, in credits: the
creditsits quote gave. It runs at that price, or at a lower one when that figure was quoted for this Idempotency-Key; above the price now, nothing runs (409price_changed). Left out, nothing runs and the error carries the quote. - webhookUrlstring · httpsAn https address to POST the job to once it is done or has failed — or waits for a yes, as a UGC ad made step by step does once its previews are in — signed (see Webhooks).
Answers
- 202jobStarted: follow the job, or wait for its webhook.
- 200jobA job that ended at once: done, or failed (see error and charged).
- 400confirm_credits_requiredA run that spends needs confirmCredits: the quote is in details.
- 402insufficient_creditsThe account has too few credits for this.
- 409price_changedThe price is above the confirmCredits sent: nothing ran; the new quote is in details.
- 422content_refusedThe content check refused it.
- 429daily_cap_reachedThe key’s daily credit cap would be passed: see Retry-After.