---
title: "Getting Started with the Veo 3.1 API: First Video in 5 Steps | imaginary.app"
description: "Send your first Veo 3.1 API request: create a key, POST one curl call, poll the task, download the MP4. Real responses, error codes and credit costs."
url: https://www.imaginary.app/blog/getting-started-veo-3-api
---

Updated November 2026

# Getting Started with the Veo 3.1 API: Your First Video in Five Steps

Create a key on the imaginary.app API page, send one `POST /api/generate` request to `https://api.veo3gen.app`, poll `GET /api/status/{taskId}` every 10 seconds, then download the MP4. The test clip below costs 1 credit and usually finishes in one to two minutes.

Key takeaways

- Two endpoints are all you need: **POST /api/generate** returns a `taskId` with HTTP 202, and **GET /api/status/:taskId** tells you when the video is ready.
- Send the key as `Authorization: Bearer veo_…`. `X-API-Key` also works.
- Only `model` and `prompt` are required. Defaults are 1080p, 16:9, 8 seconds, audio on, which for `veo3-fast` is 10 credits ($2.13–$2.50).
- Failed generations are refunded automatically, and the status response shows the refund.
- Every request on this page goes to the base URL `https://api.veo3gen.app`.

Veo 3.1 API quick start

Create a key and send your first request

One API key, no Google Cloud project, credits refunded when a generation fails.

[Get API Access](https://www.imaginary.app/api)[Read the Docs](https://www.imaginary.app/api-docs)

Sign in with Google to create an account; buy credits only when you need them.

## What you need

You need a Google account to sign in, a terminal with `curl` (or Python 3 for the full script), and a few credits. There is no SDK to install. The API takes and returns JSON over HTTPS, so any language with an HTTP client works.

You do not need a Google Cloud project, a billing account, a service account or a quota request. We call Google's Veo 3.1 models on Google Cloud for you (Veo 3.1 and Veo 3.1 Fast are generally available there; Veo 3.1 Lite is in Preview). That matters right now: Google shut down the Veo 3.1 preview models on the Gemini API on October 22, 2026, and the [Gemini API shutdown guide](https://www.imaginary.app/guides/veo-3-1-gemini-api-shutdown) covers the migration options. If you want to know what the API offers before you write code (every endpoint, model and limit), read [Veo 3.1 API access: auth, models and limits](https://www.imaginary.app/blog/veo-3-1-api-access) first. This page is only about getting the first request working.

## The five steps

1. ### Sign in and add credits

   Open the [API page](https://www.imaginary.app/api) and sign in with Google. Your API keys share your account's credit balance with the web app. Packs start at $9.99 on the [pricing page](https://www.imaginary.app/pricing).

2. ### Create an API key

   Under API Keys, click **Create API key** and give it a name such as "local-dev" (names must be unique, up to 100 characters). The full key starts with `veo_` and is shown once. Put it in an environment variable, never in source control. You can keep up to 10 active keys, so use one per environment.

3. ### Send the generate request

   This asks Veo 3.1 Lite for a 4-second silent 720p clip, which is the cheapest valid request (1 credit):

   ```
   export IMAGINARY_API_KEY="veo_your_key_here"

   curl -X POST https://api.veo3gen.app/api/generate \
     -H "Authorization: Bearer $IMAGINARY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "veo3-lite",
       "prompt": "A serene sunrise over calm ocean waves, cinematic, slow motion",
       "audio": false,
       "options": { "resolution": "720p", "aspectRatio": "16:9", "duration": 4 }
     }'
   ```

   The API checks the request and your balance, then answers straight away with HTTP 202 and a task handle. The real response also echoes your options; it is shortened here:

   ```
   HTTP/1.1 202 Accepted
   {
     "success": true,
     "message": "Video generation started",
     "taskId": "veo_1762560000000_k3j9x2",
     "status": "pending",
     "model": "veo3-lite",
     "creditsRequired": 1,
     "estimatedTime": "1-2 minutes",
     "audio": false,
     "resolution": "720p",
     "duration": 4,
     "polling": {
       "endpoint": "/api/status/veo_1762560000000_k3j9x2",
       "intervalSeconds": 10,
       "timeoutSeconds": 300
     }
   }
   ```

4. ### Poll the task status

   Call the status endpoint with the `taskId`. The response suggests 10 seconds between checks, and you get 120 status checks per minute per key, so that rate is well inside the limit.

   ```
   curl -H "Authorization: Bearer $IMAGINARY_API_KEY" \
     https://api.veo3gen.app/api/status/veo_1762560000000_k3j9x2
   ```

   `status` moves from `pending` to `processing` to `completed`. It ends at `failed`, `timeout` or `cancelled` if something goes wrong. While the task runs, a `progress` object gives a stage and a rough time estimate.

5. ### Download the MP4

   When the task completes, `result.videoUrl` is a direct MP4 link:

   ```
   {
     "success": true,
     "taskId": "veo_1762560000000_k3j9x2",
     "status": "completed",
     "model": "veo3-lite",
     "generationType": "text-to-video",
     "result": {
       "videoUrl": "https://storage.googleapis.com/.../sample_0.mp4",
       "mimeType": "video/mp4",
       "duration": 4,
       "resolution": "720p",
       "aspectRatio": "16:9",
       "hasAudio": false,
       "processingTimeSeconds": 74
     },
     "credits": { "required": 1, "charged": 1, "refunded": 0 }
   }
   ```

   Download the file and store it yourself. We do not publish a retention period for these URLs, so don't hot-link them from production pages.

## The same flow as one Python script

This script submits the job, polls until it finishes and saves the video. It only uses fields the API really returns. Run it with `IMAGINARY_API_KEY` set in your shell.

```
# pip install requests
import os, time, requests

BASE = "https://api.veo3gen.app"
HEADERS = {"Authorization": f"Bearer {os.environ['IMAGINARY_API_KEY']}"}

job = requests.post(f"{BASE}/api/generate", headers=HEADERS, json={
    "model": "veo3-lite",
    "prompt": "A serene sunrise over calm ocean waves, cinematic, slow motion",
    "audio": False,
    "options": {"resolution": "720p", "aspectRatio": "16:9", "duration": 4},
}, timeout=60)
body = job.json()
if job.status_code != 202:
    raise SystemExit(f"{job.status_code} {body.get('errorType')}: {body.get('error')}")

task_id = body["taskId"]
print("queued", task_id, "credits:", body["creditsRequired"])

deadline = time.time() + 12 * 60          # Quality can take up to ~10 minutes
while time.time() < deadline:
    time.sleep(10)                         # the API suggests a 10-second interval
    s = requests.get(f"{BASE}/api/status/{task_id}", headers=HEADERS, timeout=30).json()
    if s["status"] == "completed":
        url = s["result"]["videoUrl"]
        with open(f"{task_id}.mp4", "wb") as f:
            f.write(requests.get(url, timeout=120).content)
        print("saved", f"{task_id}.mp4")
        break
    if s["status"] in ("failed", "timeout", "cancelled"):
        print("failed:", s["error"]["type"], s["error"]["message"], "refunded:", s["credits"]["refunded"])
        break
    print(s["status"], s.get("progress", {}).get("stage"))
```

The 12-minute deadline is our own safety margin. Our backend waits up to about 8 minutes for Lite and Fast and about 10 minutes for Quality before it marks a task as failed and refunds it. For a Node.js worker with a job table, retries and storage, see the [integration architecture guide](https://www.imaginary.app/blog/integrate-ai-video-generation-in-your-app).

Want to test a key without writing code?

[Try your key in the browser](https://www.imaginary.app/use-key)

## Errors you might hit on the first call

Every error response has `success: false`, a readable `error` and a stable `errorType`. These are the ones new integrations run into most:

| HTTP | errorType                   | What it means                                                | Fix                                                |
| ---- | --------------------------- | ------------------------------------------------------------ | -------------------------------------------------- |
| 401  | MISSING\_API\_KEY           | No key found in the request                                  | Send Authorization: Bearer veo\_…                  |
| 401  | INVALID\_API\_KEY           | Key is wrong, revoked or expired                             | Check for stray spaces; create a new key           |
| 400  | VALIDATION\_ERROR           | A field is invalid; the response includes field              | Fix that field. Retrying unchanged will fail again |
| 400  | INSUFFICIENT\_CREDITS       | Balance is below the cost; includes required and available   | Top up, or pick a cheaper model or duration        |
| 400  | CONTENT\_POLICY\_VIOLATION  | Prompt rejected before generation, no credits taken          | Rephrase; real-person impersonation is blocked     |
| 429  | CONCURRENT\_LIMIT\_EXCEEDED | Too many jobs running at once on your account                | Wait for a job to finish                           |
| 429  | RATE\_LIMIT\_EXCEEDED       | Hourly per-key limit, or the 15-minute per-IP limit, reached | Back off; honour Retry-After if present            |

Two details catch people out. An empty prompt is always rejected on the developer API, even when you send an image. And `options.duration` must be the number 4, 6 or 8, not a string like `"8s"`.

Failed generations refund themselves

If Google rejects or filters a job after it starts, the task ends as `failed` and the credits go back to your balance. The status response shows `credits.charged: 0` and the refunded amount. In rare cases you may see `recoveryState: "refund_pending"`, which means the refund is being retried automatically.

## What to change after the smoke test

Once the cheap clip works, change one thing at a time. Switch `model` to `veo3-fast` or `veo3-quality`, turn `audio` back on, and set `resolution` to `1080p` (on Fast and Quality, 720p and 1080p cost the same). To animate a still image, add an `image` object with base64 bytes and a MIME type; the [Veo 3.1 image-to-video page](https://www.imaginary.app/models/veo-3-1/image-to-video) covers the details. If you are unsure which model to use, the [Lite vs Fast vs Quality comparison](https://www.imaginary.app/compare/veo-3-1-lite-vs-fast-vs-quality) shows the trade-offs, and the [cost calculator](https://www.imaginary.app/tools/veo-3-1-cost-calculator) prices any mix. The complete parameter reference is in the [API docs](https://www.imaginary.app/api-docs).

## Frequently asked questions

### Where do I get a Veo 3.1 API key?

Sign in with Google on the imaginary.app API page, open API Keys and click "Create API key". Give it a name; the full key (it starts with veo\_) is shown once, so copy it into an environment variable straight away. You can have up to 10 active keys. No Google Cloud project is involved.

### What is the cheapest possible test request?

A 4-second, 720p Veo 3.1 Lite clip with audio off costs 1 credit. That is the request used in this tutorial. Credits come in packs from $9.99, and signing up needs no credit card.

### Which base URL should I use?

Use https\://api.veo3gen.app, the host our API docs use. https\://api.imaginary.app is an alias for the same API and accepts the same keys.

### Why did my request return 400 instead of 202?

A 400 response carries an errorType. VALIDATION\_ERROR names the bad field (for example options.duration must be 4, 6 or 8). INSUFFICIENT\_CREDITS includes required and available counts. CONTENT\_POLICY\_VIOLATION means the prompt was rejected before any credits were taken.

### Do I pay for a generation that fails?

No. If a task fails or Google filters the output, the credits are returned automatically and the status response shows them under credits.refunded.

### Is this affected by the Gemini API Veo shutdown?

No. Google shut down the Veo 3.1 preview models on the Gemini API on October 22, 2026. imaginary.app calls the Veo 3.1 models on Google Cloud, so the same request keeps working. Veo 3.1 and Veo 3.1 Fast are generally available on Google Cloud; Veo 3.1 Lite is in Preview.

How we checked: every request and response field on this page was compared with our backend source (the developer generate, status and API-key middleware routes) on November 8, 2026. Credit costs come from our live pricing catalog.

## Sources

Prices, model specs and dates on this page were checked on November 8, 2026. Third-party prices change; check the source before you rely on a number.

- [Google AI for Developers — Gemini API deprecations](https://aistudio.google.com/docs/deprecations)
- [Google Cloud — model versions and lifecycle](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions)
- [imaginary.app pricing](https://www.imaginary.app/pricing)

Five steps, two endpoints

## Send your first Veo 3.1 API request today

Create a key, send one POST, and poll for the MP4. Packs start at $9.99, with no subscription required.

[Get API Access](https://www.imaginary.app/api)[Read the Docs](https://www.imaginary.app/api-docs)

Sign in with Google to create an account; buy credits only when you need them.
