# A text-to-video API: a six-second clip from a prompt

> Add AI video generation to your app with one API key using asynchronous jobs, generating 6-second clips with sound for $0.54 per render.

**The most direct way to add AI video generation to your app is through an asynchronous jobs API that manages rendering and stores the resulting clip automatically.** thelastapi provides this with `vibiz/video`, which runs LTX-2.5 Fast to generate six-second clips at 720p with sound from a text prompt or an existing still image. You authenticate with one key, poll a single job status endpoint, and receive a permanent media link stored directly in your project.

This guide walks through submitting video jobs, animating existing images, choosing aspect ratios, and managing budgets inside your application.

## How video generation differs from chat completions

Text and voice generation return data within seconds or stream tokens over a server-sent events connection. Video rendering takes longer because the model must synthesize dozens of coherent frames and synchronize audio tracks.

Because HTTP requests will time out during long render times, video generation runs as an asynchronous job:

1. **Job creation:** Your app posts the prompt, aspect ratio, and optional source image to `/v1/ai/jobs`.
2. **Immediate response:** The API answers with an HTTP `202 Accepted` status and a unique job identifier.
3. **Status polling:** Your app polls `/v1/ai/jobs/:id` every few seconds to check whether the status is pending, processing, or completed.
4. **File delivery:** Once completed, the response returns the final video link, metadata, and exact cost. When run within a project, the file is saved permanently to [Files](https://thelastapi.dev/docs/files).

This workflow prevents hanging sockets on your servers and allows background workers to handle video creation cleanly.

## Submitting a video job with code

To generate a video, send a JSON payload specifying the job type as `video` and the model as `vibiz/video`. You can test this immediately from your terminal using the CLI or via HTTP requests.

### Using the CLI

Run `vibiz video` with your prompt to generate and download a clip in one step:

```bash
vibiz video "A golden retriever running through autumn leaves in a park" \
  -o dog.mp4 \
  -aspect 16:9
```

### Using HTTP and curl

To integrate video creation into backend services written in Python, Go, or Ruby, call the [AI](https://thelastapi.dev/docs/ai) jobs endpoint directly:

```bash
curl -X POST https://thelastapi.dev/v1/ai/jobs \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "vibiz/video",
    "input": {
      "prompt": "Ocean waves crashing against basalt cliffs at dawn, cinematic lighting",
      "aspect_ratio": "16:9"
    }
  }'
```

The gateway returns a `202 Accepted` response with the created job:

```json
{
  "id": "job_01k8v92m7x4n",
  "object": "job",
  "type": "video",
  "status": "pending",
  "model": "vibiz/video",
  "created_at": "2026-10-28T12:00:00.000Z"
}
```

### Polling for completion

Poll the job status endpoint until the render completes:

```bash
curl https://thelastapi.dev/v1/ai/jobs/job_01k8v92m7x4n \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

When the render finishes, the status changes to `completed` and returns the file details:

```json
{
  "id": "job_01k8v92m7x4n",
  "object": "job",
  "type": "video",
  "status": "completed",
  "model": "vibiz/video",
  "served_model": "ltx-2.5-fast",
  "cost_micro_usd": 540000,
  "output": {
    "data": [
      {
        "url": "https://thelastapi.dev/f/Qm9x8172938475610293847561029384/2026-10-28-ocean-waves.mp4",
        "file_id": "file_01k8v93b9x2p",
        "file_url": "https://thelastapi.dev/f/Qm9x8172938475610293847561029384/2026-10-28-ocean-waves.mp4"
      }
    ]
  }
}
```

The `cost_micro_usd` value shows the exact charge ($0.54 in this example). Because this was called under a project, the URL is permanent and `expires_at` is `null`.

## Animating stills with image-to-video

You can also use an existing still image as the starting frame. This is useful for animating product photography, portraits, or artwork generated through [image generation APIs](https://thelastapi.dev/blog/image-generation-api-developers).

Add `image_url` inside the `input` object:

```json
{
  "type": "video",
  "model": "vibiz/video",
  "input": {
    "prompt": "Camera zooms out slowly as steam rises from the coffee cup",
    "image_url": "https://thelastapi.dev/f/Qm9x8172938475610293847561029384/coffee-still.png",
    "aspect_ratio": "16:9"
  }
}
```

From the CLI, pass the `--from-image` flag:

```bash
vibiz video "Steam rising from the cup, gentle camera drift" \
  -from-image "https://thelastapi.dev/f/Qm9x8172938475610293847561029384/coffee-still.png" \
  -o coffee.mp4
```

## Video specifications and parameters

`vibiz/video` standardizes video output across common formats so you do not have to manage resolution inconsistencies in your frontend video players.

| Parameter | Supported values | Details |
| --- | --- | --- |
| `model` | `vibiz/video` | Runs LTX-2.5 Fast (Lightricks) |
| Duration | 6 seconds | Fixed duration per render |
| Resolution | 720p | High-definition output |
| Audio | Included | Generated sound synchronized with the clip |
| `aspect_ratio` | `16:9` or `9:16` | Horizontal or vertical; `1:1` is automatically returned as `16:9` |
| `image_url` | Valid public HTTPS URL | Optional starting frame to animate |
| Pricing | $0.54 per video | Billed per successful job |

For applications supporting both desktop web feeds and mobile social interfaces, use `16:9` for widescreen players and `9:16` for mobile vertical stories. If you need unified access across still images, speech, and video under a single system, see our guide on [one API for image, video and voice AI models](https://thelastapi.dev/blog/one-api-image-video-voice-models).

## Accessing specialized video models by id

Beyond the standard `vibiz/video` tier, you can call specialized models from other labs by passing their exact model id to `POST /v1/ai/jobs`. This gives you access to models like Kling, Seedance, Veo, Hailuo, or Wan without creating accounts with each research lab.

To search for available video models and check their live pricing, run:

```bash
vibiz media-models --category image-to-video
```

To call a lab model directly, provide its id and pass its specific configuration inside the `model_input` object (up to 16 KB):

```ts
import { vibiz } from '@vibiz/app';

const job = await vibiz.ai.jobs.create({
  type: 'video',
  model: 'kling-video/v2.1/master/image-to-video',
  input: {
    prompt: 'A gentle breeze blowing through green grass',
    image_url: 'https://thelastapi.dev/f/Qm9x8172938475610293847561029384/field.png',
    model_input: {
      duration: '10',
    },
  },
});
```

Lab models called by id charge live rates against your account credits. To prevent accidental overspending, any individual call that would exceed $10 is rejected with a `call_too_expensive` error. For more details on pricing differences between tiers, consult our breakdown on [how much AI video generation costs per clip via API](https://thelastapi.dev/blog/ai-video-api-cost-per-clip).

## Safeguarding production with budgets and spend limits

Video generation costs significantly more per call than text generation. Building video tools without strict limits can deplete an account balance quickly if users generate clips in tight loops.

thelastapi applies budget ceilings at multiple levels:

- **Daily account spend ceiling:** New accounts have a $5 daily limit across all AI calls and actions by default. An owner can raise this in the Billing console.
- **Daily project budget:** Each project defaults to a $1 daily AI budget. You can adjust this to fit expected production traffic:

```bash
vibiz ai budget 25.00 --project prj_123
```

- **Per-user tracking:** Pass your internal user identifier in the `user` parameter (or `X-Vibiz-User` header) with job requests. The console breaks down spend by end user, helping you identify heavy accounts.

When a job exceeds a budget, the API answers with an HTTP `429` error carrying `details.reason: "project_budget"` or `details.reason: "daily_spend"`. Your code can inspect this error to inform users when their daily generation quota has been met.

## Automated file storage

Handling video uploads manually requires setting up media buckets, generating signed upload URLs, and cleaning up failed uploads. thelastapi automates this entirely:

1. Every video created under a project key is automatically ingested into the project's **Files** storage.
2. The URL returned in the completed job payload is public and permanent, formatted as `https://thelastapi.dev/f/<key>/<filename>.mp4`.
3. Clips generated using development keys are stored in the project's development Files environment, keeping test assets separate from production user data.

You can inspect, search, and download your generated clips using the CLI:

```bash
# Get the URL of the most recently generated video
vibiz files latest --type video

# Search for videos matching a specific prompt
vibiz files search "autumn leaves"
```

If you call the API using an account key without specifying a project, the generated video link remains active for 24 hours. To make assets permanent, always link the generation call to a project.

To begin integrating video generation into your application, check the API parameters in the [AI docs](https://thelastapi.dev/docs/ai) or review our guide on [generating images and video from Claude Code](https://thelastapi.dev/blog/ai-video-from-claude-code).

## Frequently asked questions

### How long does it take for a video job to finish rendering?

Video generation via `POST /v1/ai/jobs` is asynchronous. Most six-second renders finish within a couple of minutes, during which your application polls `GET /v1/ai/jobs/:id` until the status changes from `pending` or `processing` to `completed`.

### What happens if I request a 1:1 aspect ratio for a video?

The `vibiz/video` model accepts `16:9` and `9:16` aspect ratios. If your request submits a `1:1` aspect ratio, the gateway processes the clip and returns it formatted as `16:9`.

### Are generated video links permanent or do they expire?

When you generate a video using a project key or pass a project header, the video is saved directly to your project's Files with a permanent link that never expires. Calls made with an account key outside of a project receive links that expire after 24 hours.

---

Published 2026-11-15 · https://thelastapi.dev/blog/text-to-video-api
