puter.ai.txt2vid()

Given a prompt, generate a short video clip using AI. Puter routes the request to one of three upstream providers (Google Veo, Together AI, BytePlus Seedance) based on the model you pick, waits for the clip to render, and resolves with a ready-to-play video. Every model can also start from an image you supply (image-to-video), and the same option names work across providers.

Syntax

puter.ai.txt2vid(prompt, testMode = false)
puter.ai.txt2vid(prompt, options = {})
puter.ai.txt2vid({prompt, ...options})

Parameters

prompt (String) (required)

The text description that guides the video generation. Describe the subject, the motion, the camera move and the mood; cues such as "slow motion", "aerial shot" or "handheld" are understood by most models.

testMode (Boolean) (optional)

When true, the call returns a short sample clip hosted by Puter instead of contacting a provider, so you can build your UI without spending credits. Defaults to false.

Test mode still resolves the model you asked for and still validates (and writes to) puter_output_path, so it catches misspelled model ids and permission problems before you go live.

options (Object) (optional)

Additional settings for the generation request. The options below carry the same meaning on every provider; each provider then accepts a few extras, listed in the sections that follow. Any option a provider does not recognize is ignored.

Choosing a model

Model ids are matched case-insensitively, and every model answers to a few spellings: the fully qualified id, the org/model form and the bare model name. 'google:google/veo-3.1-lite', 'google/veo-3.1-lite', 'veo-3.1-lite' and 'veo-3.1-lite-generate-preview' all select the same model. When a bare name is served by more than one provider ('veo-3.1' is offered by Google directly and through Together AI) Puter picks the cheaper listing; pass provider or the fully qualified id to choose explicitly.

When you pass no model, Puter uses Veo 3.1 Lite on Google (veo-3.1-lite). A self-hosted Puter without a Google key falls back to the first provider it has a key for.

seconds and size are normalized rather than rejected: a value the model does not offer is replaced by the model default, which is the first value listed in the tables below and also what you get when you leave the option out.

Image inputs

input_reference, last_frame and reference_images take the same three formats everywhere: a public image URL, a data: URI, or raw base64 (treated as PNG). Providers that need inline bytes fetch URLs server-side, so a URL works on every model. What each provider does with them:

Google (Veo) options

Available when using a Veo 3.1 model (provider 'gemini-video-generation'). Google has retired Veo 3.0; Veo 2.0 is offered through Together AI instead (see the next section).

Sizes map onto Veo's aspect ratio (16:9 or 9:16) and resolution tier (720p, 1080p or 4K). 1080p and 4K clips, and any request that uses reference_images, are always 8 seconds long regardless of seconds. Veo is billed per second; 4K costs more than 720p and 1080p, and on Veo 3.1 Fast and Veo 3.1 Lite 1080p costs more than 720p. Every Veo clip comes with a generated soundtrack.

For more details, see the Google Veo API reference.

Together AI options

Available when using any model below (provider 'together-video-generation'). Pass the model as 'org/model', or prefix it with togetherai: to make the routing explicit; 'togetherai:google/veo-3.1' runs Veo through Together AI while a bare 'veo-3.1' goes to Google directly.

Together AI models are priced in one of two ways, marked in the table:

• Per clip. The model renders a fixed-length clip for a flat price. The request is either affordable or rejected with insufficient_funds.
• Per second. Newer models are billed per second of output at a rate that depends on the resolution. Puter estimates the cost from the highest published rate before the request, shortens the clip to fit the remaining balance (see Cost and clip length), and then charges the exact amount Together AI reports for the finished job.

Most models size their output in pixels: pass size as 'WIDTHxHEIGHT' (or width and height directly) from the combinations each model advertises in the sizes column. Seedance 2.5 and Wan 2.7 instead work in resolution tiers, so size picks the tier of the shorter side (or name the tier directly), and Wan 2.7 takes the aspect ratio from it. "Keyframes" says whether the model can start from an image (first) and also end on one (last); supply them through input_reference and last_frame, or through frame_images for finer control. "Provider default" means Together AI has not published the values: the model applies its own defaults, and a seconds or size it does not accept is rejected with upstream_bad_request.

For more details about each option, see the Together AI API reference.

BytePlus (Seedance) options

Available when using a Seedance model served by BytePlus ModelArk (provider 'byteplus-video-generation'). These models take any whole number of seconds within their range and work in resolution tiers: pass size as a tier or as 'WIDTHxHEIGHT', which selects the tier of the shorter side and the aspect ratio.

The first resolution listed is the default. Seedance is billed per video token, and the token count grows with duration and pixel count, so a 4K clip costs several times more per second than 720p. Generated clips carry no watermark.

An invalid combination (a last frame without a first frame, reference images together with a first frame, or an option the model lacks) is rejected with bad_request before any credits are spent.

For more details, see the BytePlus ModelArk video generation reference.

Any properties not set fall back to provider defaults.

Saving to Puter filesystem

Pass puter_output_path to persist the generated video directly on the Puter filesystem. Relative paths are resolved against ~/AppData/<appID>/ when called from an app, or ~/ otherwise:

puter.ai.txt2vid("A drone shot over a forest", {
    puter_output_path: "videos/forest.mp4"  // saved to ~/AppData/<appID>/videos/forest.mp4
});

Absolute paths (/username/Videos/forest.mp4) and home-relative paths (~/Videos/forest.mp4) are sent as-is. Write permission to the destination is enforced server-side.

The destination is checked before generation starts, so a path you cannot write to fails immediately with access_denied and costs nothing. Missing parent folders are created and an existing file at the path is overwritten. Most providers return a temporary hosted URL (see Return value), so this is the way to keep a clip after the request completes.

Cost and clip length

Every successful generation is charged to the user's AI credits according to the model, duration and resolution. Before contacting the provider, Puter compares the estimated cost with the remaining balance:

• Veo and Seedance are priced per second. If the balance cannot cover the requested length, Puter shortens the clip to the longest duration the model supports that the balance does cover, and rejects with insufficient_funds only when even the shortest clip is unaffordable. The response does not flag a shortened clip, so read video.duration once metadata has loaded if the exact length matters. Veo clips at 1080p or 4K, or with reference_images, are fixed at 8 seconds and therefore all-or-nothing.
• Together AI prices its older models per clip, so those requests are either accepted at the model's duration or rejected with insufficient_funds. Its per-second models (marked in the Together AI table) are shortened like Veo and Seedance, and the final charge is the amount Together AI reports for the job.

A request that fails or times out is not charged. The request and concurrency limits that apply to every AI call are listed in Rate limits and quotas.

How long it takes

Video generation is slow: expect anywhere from tens of seconds to several minutes, growing with duration and resolution. The returned promise stays pending until the clip is ready, so keep the UI responsive with a progress indicator (see the examples below). Puter waits up to ten minutes for a job; one that outlives the window fails with upstream_timeout.

Return value

A Promise that resolves to an HTMLVideoElement (in browsers) that you can append to the DOM straight away:

• src is the clip's URL. Depending on the provider it is either an https: URL on the provider's storage (Together AI, Seedance, and usually Veo) or a data: URI holding the whole clip (Veo, when Google returns the bytes inline). Provider URLs are temporary; keep a copy with puter_output_path if you need the clip later.
• controls is enabled and preload is "metadata".
• The data-source attribute carries the same URL, and data-mime-type the MIME type when it is known (for example video/mp4).
• String(video) returns the URL, so the element can be dropped into a template or passed to fetch().

In Node.js and Workers, where there is no DOM, the promise resolves to a plain object with the same src, controls and preload fields and the same toString(); the data-* attributes are not present. Use fetch(video.src) to read the bytes, or puter_output_path to have Puter store the file for you.

In test mode src is always the https: URL of Puter's sample clip.

Note: Each successful generation consumes the user's AI credits in accordance with the model, duration and resolution you request. See Cost and clip length for how Puter fits a clip to the remaining balance.

Errors

A rejection carries the error body exactly as the backend sent it, or { message, code } for the checks the SDK runs before making the request. Every error has message and code; the other fields appear when they apply.

Other upstream_* codes mean the provider rejected the request or was unavailable before a job started; message carries the provider's reason.

Examples

Generate a sample clip (test mode)

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.ai.txt2vid(
            "A sunrise drone shot flying over a calm ocean",
            true // test mode avoids using credits
        ).then((video) => {
            document.body.appendChild(video);
        }).catch(console.error);
    </script>
</body>
</html>

Generate an 8-second cinematic clip in 1080p

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.ai.txt2vid("A fox sprinting through a snow-covered forest at dusk", {
            model: "veo-3.1-fast",
            seconds: 8,
            size: "1920x1080"
        }).then((video) => {
            document.body.appendChild(video);
            // Autoplay once metadata is available
            video.addEventListener('loadeddata', () => video.play().catch(() => {}));
        }).catch(console.error);
    </script>
</body>
</html>

Use a Google Veo model with a negative prompt

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.ai.txt2vid("A hummingbird hovering over a red flower, macro lens, soft morning light", {
            model: "veo-3.1-fast",
            seconds: 6,
            size: "1280x720",
            negative_prompt: "blurry, text, watermark, people"
        }).then((video) => {
            document.body.appendChild(video);
        }).catch(console.error);
    </script>
</body>
</html>

Animate a photo (image-to-video)

<html>
<body>
    <p>Pick a photo to animate:</p>
    <input type="file" id="photo" accept="image/*">
    <p id="status"></p>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        const status = document.getElementById('status');

        document.getElementById('photo').addEventListener('change', async (e) => {
            const file = e.target.files[0];
            if (!file) return;

            // Seedance and Veo take the first frame as a data: URI
            const dataUri = await new Promise((resolve, reject) => {
                const reader = new FileReader();
                reader.onload = () => resolve(reader.result);
                reader.onerror = reject;
                reader.readAsDataURL(file);
            });

            status.textContent = 'Generating... this can take a few minutes.';
            try {
                const video = await puter.ai.txt2vid("Slow push-in on the scene as a gentle wind moves through it", {
                    model: "seedance-2-0-mini",
                    seconds: 5,
                    size: "720p",
                    input_reference: dataUri,
                    generate_audio: false
                });
                status.textContent = '';
                document.body.appendChild(video);
            } catch (err) {
                status.textContent = `Failed: ${err.message} (${err.code})`;
            }
        });
    </script>
</body>
</html>

Save the clip to the Puter filesystem

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        // test_mode keeps this free; the sample clip is still written to the path
        puter.ai.txt2vid({
            prompt: "A paper boat drifting down a rain-soaked street",
            test_mode: true,
            puter_output_path: "videos/paper-boat.mp4"  // ~/AppData/<appID>/videos/paper-boat.mp4
        }).then(async (video) => {
            const file = await puter.fs.stat("videos/paper-boat.mp4");
            puter.print(`Saved ${file.name} (${file.size} bytes) to ${file.path}`);
            document.body.appendChild(video);
        }).catch(console.error);
    </script>
</body>
</html>

Show progress and handle errors

<html>
<body>
    <button id="go">Generate</button>
    <p id="status"></p>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        const status = document.getElementById('status');

        document.getElementById('go').addEventListener('click', async () => {
            const started = Date.now();
            const ticker = setInterval(() => {
                status.textContent = `Generating... ${Math.round((Date.now() - started) / 1000)}s`;
            }, 1000);

            try {
                // No model given: the default Veo 3.1 Lite is used
                const video = await puter.ai.txt2vid("A lighthouse in a storm, waves crashing, dramatic lighting", {
                    seconds: 4
                });
                status.textContent = 'Done';
                document.body.appendChild(video);
            } catch (err) {
                if (err.errorCode === 'moderation_flagged') {
                    status.textContent = 'The content filter refused this prompt. Try rewording it.';
                } else if (err.code === 'insufficient_funds') {
                    status.textContent = 'Not enough credits for this clip.';
                } else if (err.code === 'upstream_timeout') {
                    status.textContent = 'The provider took too long. Try again with a shorter clip.';
                } else {
                    status.textContent = `Failed: ${err.message} (${err.code})`;
                }
            } finally {
                clearInterval(ticker);
            }
        });
    </script>
</body>
</html>

Generate a clip from Node.js

import { init } from "@heyputer/puter.js/src/init.cjs";
const puter = init(process.env.puterAuthToken);

const video = await puter.ai.txt2vid("Time-lapse of clouds rolling over a mountain lake", {
    seconds: 6,
    puter_output_path: "~/Videos/clouds.mp4",
});

// There is no <video> element outside a browser; the result still exposes the URL.
console.log(String(video));
// The clip is also saved at ~/Videos/clouds.mp4 in the user's Puter filesystem.