Keytween

Get started

Workflows and use cases

Each recipe lists the MCP tool calls in order. The REST equivalents are in the REST API reference. An agent should read the matching prompting guide first and quote the cost with estimate_cost before spending the user's credits.

Every generate call waits up to wait_seconds (default 45) and returns the job. If status is still queued or running, call wait_for_job with the job_id until it is succeeded, failed or cancelled.

One image from text #

generate_image  prompt, aspect_ratio "4:5", megapixels 1

Without sequence_id the image goes to the image library. The result has job.outputs[0].download_url (a PNG), a small preview the agent can look at and the seed. Cost: 2 credits at 1 MP.

A high-resolution image #

generate_image  prompt, aspect_ratio "3:2", megapixels 4           (about a minute)

Standalone images go up to 4 megapixels, for prints, wallpapers and hero images. Cost: 7 credits at 4 MP. Explore at 0.5 or 1 MP first, then render the keeper large with the same seed.

Game sprites and icons #

generate_sprite  prompt "A 16-bit pixel art RPG inventory icon of ...", width 32     -> 32 x 32 PNG with transparency
export_sprite    image_id <sprite>, width 64                                         (free)

See Game sprites and icons for sizes, styles, palettes and keeping a set consistent.

Several variations #

generate_image  prompt, aspect_ratio "16:9"                        (new seed each time)
generate_image  prompt, aspect_ratio "16:9"
generate_image  prompt, aspect_ratio "1:1"                         (another shape)

A few generations may run at once (get_account reports the limit), so the calls can be sent with wait_seconds: 0 and collected with wait_for_job. Accounts take turns on the GPU, so a batch is interleaved with other people's work rather than blocking it.

Edit an image #

generate_image  prompt                                             -> image A
edit_image      image_id A, prompt "Replace ... Keep everything else unchanged."   -> image B
edit_image      image_id B, prompt "..."                           -> image C

save_as defaults to "image": every version is kept as its own library image, so edits can be chained and compared. Any image you own can be edited this way, including frames and last frames from sequences. Edits keep the source's shape and run at up to 2 MP.

Edit a picture you already have #

create_upload_url  role "image"                                    -> upload_url, curl_command
(run the curl command with the local file; its output has the new asset "id")
edit_image         image_id <id>, prompt "..."

An image with a specific character, product or style #

create_upload_url  role "reference", label "bottle"                (no sequence_id: a library reference)
(run the curl command)
generate_image     prompt "... the exact same glass bottle shown in @bottle, emerald green with a brass cap ..."

References belong to the image library or to one sequence. For a sequence's frames, pass its sequence_id to both calls.

To reuse an image you already made as a reference: add_reference with source_asset_id and a label, optionally with a crop. Each reference mentioned adds a few seconds of render time.

Animate an image #

create_sequence  from_asset_id <image>                             -> sequence_id S (start frame set, scaled to at most 1 MP)
generate_video   mode "image_to_video", sequence_id S, prompt "what happens next, camera, sound"

Text to video #

generate_video  mode "text_to_video", prompt, aspect_ratio "16:9", duration_seconds 5   -> job J
wait_for_job    job_id J    (repeat until succeeded)

The output is an MP4 with sound. Cost: 10 credits for 4.33 s at standard size. Use it for quick ideas and b-roll where the exact look is not fixed.

Image to video #

Animate a picture; the ending is open.

create_sequence  title "Night market"                              -> sequence_id S
generate_image   sequence_id S, prompt, aspect_ratio "9:16"        -> start frame A
generate_video   mode "image_to_video", sequence_id S, prompt "what happens next, camera, sound"
wait_for_job

With your own picture, upload it as the start frame first (create_upload_url, role start_frame). To animate an image from the library or from another sequence, copy it into a fresh sequence: create_sequence with from_asset_id.

First and last frame to video #

Control exactly where the shot ends.

create_sequence                                                    -> sequence_id S
generate_image  sequence_id S, prompt                              -> start frame A
edit_image      image_id A, save_as "end_frame", prompt "the end state. Keep everything else unchanged."   -> end frame B
generate_video  mode "first_last_frame", sequence_id S, prompt "what happens between the frames, camera, sound"
wait_for_job

Use it for transformations, before-and-after, time-lapses, reveals, camera moves with a set destination, and any shot that must hand over to the next one exactly.

A seamless loop: make the end frame a near-copy of the start frame with one very small edit, and describe motion that leaves and returns to where it began.

A multi-shot film #

Each step starts on the previous take's last frame, so the shots join without a visible cut.

create_sequence  title                                             -> sequence_id S
generate_image   sequence_id S, prompt                             -> start frame, step 1
edit_image       image_id <start>, save_as "end_frame", prompt     -> end of shot 1
generate_video   mode "first_last_frame", sequence_id S, prompt    -> take 1
get_asset        asset_id <take 1>, preview "contact_sheet"        (check it; re-render if it misses)
accept_step      sequence_id S                                     -> step 2, starting on take 1's last frame

get_sequence     sequence_id S                                     -> step 2's start_frame_id
edit_image       image_id <step 2 start frame>, save_as "end_frame", prompt   -> end of shot 2
generate_video   mode "first_last_frame", sequence_id S, prompt    -> take 2
accept_step      sequence_id S
...
export_sequence  sequence_id S                                     -> one MP4 with sound
  • Mix modes freely: a step can be rendered with image_to_video when its ending should be open.
  • Several takes can be rendered for a step; select_frames with take_id picks one before accepting.
  • reopen_step undoes an accept, and deletes the later steps built on it.
  • Export is free and can be repeated after changes.

The storyboard prompt (a slash command in clients that support MCP prompts) walks an agent through planning, quoting and building a film this way.

Batch work #

  • Check get_account for the balance and the concurrency limit, and estimate_cost for the whole batch.
  • Submit with wait_seconds: 0, keep the job_ids, and collect with wait_for_job. list_jobs with active_only shows what is still running.
  • On too_many_jobs, wait for one to finish before submitting the next.

Saving results #

download_url needs no credentials and is valid for an hour:

curl -sS -o shot.mp4 "<download_url>"

get_asset returns a fresh link at any time, and list_assets finds anything made earlier.

Cleaning up #

delete_asset removes one image, take, reference or export; delete_sequence removes a sequence with everything in it. Both are permanent. The account owner can also review and delete everything in the Library on the website; see Your data and deleting it.

All docs