AI Video Generation API: Run Text-to-Video in TypeScript

An AI video generation API turns a prompt into a video through an asynchronous run: start the Video Generator, poll the returned run ID, and read the video URL from the completed run’s assets. Pipe2’s TypeScript SDK exposes those public operations directly, so a prompt-only text-to-video integration can stay small.

Run text-to-video with the TypeScript SDK

Install @pipe2-ai/sdk, put a Pipe2 token in PIPE2_TOKEN, and run this module with Node. The example uses one observable action and a short timeline so the generator has a clear shot to produce.

import { createClient } from '@pipe2-ai/sdk';

const input = {
  prompt: '[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music.',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'video-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Video generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

The same pipeline request, separated from authentication and polling, is:

{
  "pipeline_slug": "video-generator",
  "input": {
    "prompt": "[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music."
  }
}

The TypeScript SDK documentation covers installation, authentication, pipeline runs, status queries, subscriptions, uploads, and credit operations.

Understand the run, poll, and asset flow

RunPipeline accepts the pipeline slug plus a JSON input object. It returns identifiers for the new run rather than holding the request open until video generation finishes. Keep run_pipeline.run_id; it is the identifier used by GetPipelineRun.

Each poll returns the current run record. A completed run can include generated assets, and the example prints the first asset URL. A failed run includes an error message that the integration should surface or log. Production code should also set its own overall timeout and treat an absent run as an error instead of polling forever.

Polling every few seconds is adequate for a small script. For a service that needs live updates, the SDK also exposes WatchPipelineRun as an async iterable over the same run state.

Start with the least complicated valid input

The request uses only prompt. That is the smallest useful text-to-video input and leaves the pipeline’s model selector on Auto. The shipped Video Generator can also work with start or end frames and with optional image, video, or audio references, while supported duration, resolution, aspect ratio, and reference limits depend on the compatible model route.

Add one control only when the product requirement needs it. A destination-specific aspect ratio may be important; a reference image may be necessary for identity; a longer clip may require a different compatible route. Before dispatching a more expensive or media-heavy request, call the SDK’s EstimatePipelineCost operation with the same pipeline_slug and input.

Write prompts that fit one generated shot

A text-to-video API does not remove the need for a precise shot brief. Describe visible action, camera behavior, environment, timing, and sound. Keep the action physically achievable inside the requested time.

The example uses two time ranges but one continuous event: the airplane circles, then lands. It does not ask for a location change, several characters, or multiple edits. This makes the returned clip easier to inspect for motion continuity, object shape, the landing moment, and audio.

For a larger production, generate and approve individual shots before assembling them. The guide to making AI videos covers planning, review, assembly, captions, and finishing beyond this API call.

Handle authentication and failures explicitly

Create the client with a Pipe2 token and keep that token on the server or in a secure local environment variable. Do not put it in browser-delivered source, commit it, or include it in the pipeline input.

Separate dispatch errors from run failures. A dispatch can fail before a run begins because the request is unauthenticated, invalid, or cannot reserve the required credits. A successfully created run can later finish with failed; inspect its error_message. Only consume asset URLs after the status is completed.

If the workflow begins from an image rather than text, upload or reference the asset through the documented SDK asset flow and follow the practical image-to-video guide for source preparation and motion prompting.