---
title: "Veo 3.1 JSON Prompt Guide — API for Newcomers 2026"
description: "Beginner-friendly Veo 3.1 JSON prompt guide: every field explained, 3 copy-paste examples, and when to use it vs alternatives. 26 credits on AI Content Drop."
canonical: "https://aicontentdrop.com/blog/veo-3-1-json-prompt-guide"
source: "https://aicontentdrop.com/blog/veo-3-1-json-prompt-guide"
---
## What This Guide Does

This guide explains every field in a Veo 3.1 JSON prompt — the structured text request you send to Google's video generation model. By the end you'll be able to send your first request to Veo 3.1 and understand every field in the JSON, even if you've never called an AI model API before.

We'll start with the terminology you need, show you the full request body you can copy and run today, then break down every field one by one. We'll also cover the most common mistakes newcomers make and show you three ready-to-use prompt bodies for different video styles. No background in coding is required — if you can read and copy text, you can follow along.

## What Is Veo 3.1?

Veo 3.1 is a text-to-video AI model made by Google DeepMind. You give it a text description — called a **prompt** — and it generates a short video clip. It sits above the original [Veo 3 Fast](https://aicontentdrop.com/blog/veo-3-fast-review) in Google's model lineup, offering sharper motion, stronger prompt adherence, and more consistent human figures. It excels at realistic lifestyle and commercial footage where physical accuracy matters — a skincare founder talking to camera, a product sitting on a shelf, a chef plating a dish. The one thing it can't do well today is long-form multi-scene video; it tops out at around 8 seconds per generation.

Veo 3.1 is available via Google's official Gemini API. On AI Content Drop, each Veo 3.1 generation costs **26 credits** — billed only after your video generates successfully (post-deduct billing means you don't pay if the generation fails). AI Content Drop handles the API call for you so you don't need a Google Cloud project — but if you want to call Google directly, this guide shows the official request shape. For context on how that compares to older versions, see the [Veo 3 vs Sora comparison](https://aicontentdrop.com/blog/veo-3-vs-sora).

## The Complete JSON Prompt

Below is a full Veo 3.1 API request body you can copy, paste, and send right now. This is **JSON** — JavaScript Object Notation, a text format APIs use to send structured requests. Each line is a key–value pair; together they tell the model exactly what video to make.

```
{
  "instances": [
    {
      "prompt": "A skincare founder in her 30s holds up a glass serum bottle and speaks confidently to camera, slow push-in from medium to close-up, soft studio lighting with a warm white backdrop, photorealistic commercial style"
    }
  ],
  "parameters": {
    "aspectRatio": "9:16",
    "durationSeconds": 5,
    "negativePrompt": "blurry, watermark, text overlay, distorted hands",
    "personGeneration": "allow_adult",
    "sampleCount": 1
  }
}
```

At a glance: `instances[0].prompt` is your description of the scene; `parameters.aspectRatio` and `parameters.durationSeconds` set the frame and length; `parameters.negativePrompt` tells the model what to avoid; `parameters.personGeneration` controls whether human figures are allowed; and `parameters.sampleCount` controls how many video variants to generate at once.

## Field-by-Field Breakdown

Let's go through every field. For each one you'll see its type, whether it's required, what happens if you leave it out, and a quick example showing what good usage looks like versus a common mistake.

### instances[0].prompt

**Type:** string | **Required:** yes

This is the most important field. It sits inside the `instances` array — a list with one object that contains your text description of the video. The model reads your prompt and tries to generate a clip that matches. A good prompt covers four things: what's in the frame (subject), what's happening (action), how the camera is positioned (framing), and the visual style.

**Good:** "A woman in her 30s in a white blazer gestures at a laptop screen in a bright modern office, slow push-in from medium to close-up, natural window light, photorealistic corporate advertisement style"
**Weak:** "A woman at work" — too vague; the model will guess everything and produce something generic.

Keep prompts between 30 and 200 words. Under 30 words the model lacks enough detail; over 200 words it starts ignoring parts of the description.

### parameters.aspectRatio

**Type:** string (enum) | **Required:** no |  **Default:** `"16:9"`

Sets the shape of the output video. `"9:16"` is vertical (for TikTok and Instagram Reels), `"16:9"` is horizontal (for YouTube and presentations), and `"1:1"` is square (for Instagram feed posts).

**Good:** `"9:16"` when your prompt describes a full-body person or tall product shot.
**Mistake:** Using `"16:9"` for a "full-body runway walk" — portrait subjects get awkwardly cropped in landscape frames. Match the ratio to the subject.

### parameters.durationSeconds

**Type:** number (integer) | **Required:** no |  **Default:** `5`

How many seconds long the video should be. Veo 3.1 supports 5 and 8 seconds. Most social ad use cases work best at 5 seconds — it's enough for a single clear action. Use 8 seconds when you need a slightly longer reveal or a natural sentence of dialogue.

**Good:** `5` for a product close-up or talking-head hook.
**Mistake:** Sending `10` — Veo 3.1 does not support 10-second clips and will return an error. See the reference table below for all valid values.

### parameters.negativePrompt

**Type:** string | **Required:** no |  **Default:** `""` (empty)

A description of things you do *not* want to appear in the video. The model uses this to steer away from common artifacts. Useful values include `"blurry, watermark, text overlay, distorted hands"`. Keep it under 50 words — longer negative prompts can confuse the model.

**Good:** `"blurry, extra limbs, watermark"`
**Mistake:** `"no bad quality, no ugly, no artifacts"` — vague negatives have no measurable effect. Be specific about the exact visual problem you want to avoid.

### parameters.personGeneration

**Type:** string (enum) | **Required:** no |  **Default:** `"allow_adult"`

Controls whether and how human figures may appear in the generated video. The most commonly used values are `"allow_adult"` (adults allowed, the default for most commercial use cases) and `"dont_allow"` (no people at all — useful for pure product or landscape shots). This setting exists so the API can apply Google's content policies consistently.

**Good:** `"allow_adult"` for founder UGC or talking-head ads.
**Mistake:** Leaving this out entirely when generating scenes with people — the API applies a default, but being explicit ensures you get the result you expect.

### parameters.sampleCount

**Type:** number (integer) | **Required:** no |  **Default:** `1`

How many video variants to generate in a single API call. Setting this to `2` or `4` produces multiple clips from the same prompt, which is useful for A/B testing different takes without re-sending the request. Each variant counts as a separate generation for billing purposes.

**Good:** `1` while you're testing a new prompt — keep costs predictable.
**Mistake:** Setting `4` on every request during iteration — you multiply your credit spend before you've confirmed the prompt direction is right.

## Allowed Values Reference Table

This table lists every enum value Veo 3.1 accepts. Bookmark it — when you get an "invalid parameter" error, this is the first place to check.

| Field | Allowed values | Notes |
| --- | --- | --- |
| `instances[0].prompt` | Any string, 1–2000 chars | Sweet spot is 30–200 words. Required field. |
| `parameters.aspectRatio` | `"16:9"`, `"9:16"`, `"1:1"` | Default is `"16:9"`. 3:4 is not supported — use 9:16 and crop. |
| `parameters.durationSeconds` | `5`, `8` | Seconds. Values outside this range return an error. |
| `parameters.negativePrompt` | Any string, up to ~200 chars | Optional. Describe what to avoid. Keep specific. |
| `parameters.personGeneration` | `"allow_adult"`, `"dont_allow"` | Controls human figure generation. Default is `"allow_adult"`. |
| `parameters.sampleCount` | Positive integer (typically 1–4) | Number of video variants per request. Each variant costs credits. |

## 3 Working Copy-Paste Examples

### Example 1: E-commerce — Sneaker Product Ad

```
{
  "instances": [
    {
      "prompt": "White Nike Air Max 90 sneaker rotating slowly on a matte black pedestal, 360-degree orbit camera movement, soft studio lighting with a gradient backdrop from charcoal to white, photorealistic product advertisement style, clean and minimal"
    }
  ],
  "parameters": {
    "aspectRatio": "1:1",
    "durationSeconds": 5,
    "negativePrompt": "blurry, watermark, extra objects, text overlay",
    "personGeneration": "dont_allow",
    "sampleCount": 1
  }
}
```

This prompt is built for a square product card. The orbit camera movement shows all angles of the shoe. Setting `personGeneration` to `"dont_allow"` keeps the frame clear of any background figures and ensures the shoe stays the sole subject. The minimal negative prompt handles the most common artifacts for product shots. Expect a clean, polished loop suitable for Instagram feed or Amazon listing video.

### Example 2: Portrait — Founder Talking-Head

```
{
  "instances": [
    {
      "prompt": "A confident woman in her early 30s wearing a tailored cream blazer speaks directly to camera in a bright modern co-working space, static medium close-up with subtle handheld motion, soft diffused natural window light from the left, photorealistic UGC-style testimonial"
    }
  ],
  "parameters": {
    "aspectRatio": "9:16",
    "durationSeconds": 8,
    "negativePrompt": "distorted face, extra limbs, blurry, watermark",
    "personGeneration": "allow_adult",
    "sampleCount": 1
  }
}
```

Portrait ratio (9:16) puts the subject front and centre — perfect for TikTok or Reels. Eight seconds gives enough run-time for a natural conversational hook. The subtle handheld motion keeps it from looking too stiff. Setting `personGeneration` to `"allow_adult"` explicitly tells the API that the human figure in the scene is expected and intended.

### Example 3: Cinematic — Moody Street Scene

```
{
  "instances": [
    {
      "prompt": "A rain-soaked narrow alley in Tokyo at night, neon signs reflecting in puddles on the cobblestones, slow forward dolly from wide shot pushing toward a red lantern in the distance, volumetric fog catching pink and blue neon light, cinematic 35mm film aesthetic, moody and atmospheric"
    }
  ],
  "parameters": {
    "aspectRatio": "16:9",
    "durationSeconds": 8,
    "negativePrompt": "people, text, watermark, overexposed",
    "personGeneration": "dont_allow",
    "sampleCount": 1
  }
}
```

Landscape ratio suits the wide establishing shot described in the prompt. Eight seconds lets the dolly movement complete naturally. The volumetric fog phrase reliably activates atmospheric depth on Veo 3.1. This style works well as brand-feel B-roll or as the opening shot of a cinematic ad. Expect deep shadows with vivid neon highlights — exactly what the prompt asks for.

## How to Send the Request

An **API endpoint** is a URL your code sends a request to — think of it like a mailbox address where the AI model lives. The official Google Gemini API endpoint for Veo 3.1 is `https://generativelanguage.googleapis.com/v1beta/models/veo-3.1-generate-001:predictLongRunning`. Because Veo generates video asynchronously, the call is a two-step process: you POST the request to start a long-running operation, then GET the operation URL until it reports `done: true`. To get a Gemini API key, visit `https://aistudio.google.com/app/apikey`.

**Step 1 — Start the generation (curl):**

```
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/veo-3.1-generate-001:predictLongRunning" \
  -H "x-goog-api-key: YOUR_GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [
      {
        "prompt": "A skincare founder holds a serum bottle and speaks to camera, photorealistic, soft studio lighting"
      }
    ],
    "parameters": {
      "aspectRatio": "9:16",
      "durationSeconds": 5,
      "personGeneration": "allow_adult",
      "sampleCount": 1
    }
  }'
```

The response is an operation object with a `name` field — a path like `operations/abc123`. Save it; you need it in Step 2.

**Step 2 — Poll until done (curl):**

```
curl "https://generativelanguage.googleapis.com/v1beta/{OPERATION_NAME}" \
  -H "x-goog-api-key: YOUR_GEMINI_API_KEY"
```

Repeat every 5–10 seconds until `done` is `true`. Then read the video URI from the response (see Section 8 below for the full response shape).

Here is the same two-step flow in JavaScript (works in Node.js or a browser):

```
const API_KEY = "YOUR_GEMINI_API_KEY";
const BASE = "https://generativelanguage.googleapis.com/v1beta";

// Step 1 — start generation
const startRes = await fetch(
  `${BASE}/models/veo-3.1-generate-001:predictLongRunning`,
  {
    method: "POST",
    headers: { "x-goog-api-key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      instances: [{ prompt: "A skincare founder holds a serum bottle and speaks to camera, photorealistic, soft studio lighting" }],
      parameters: { aspectRatio: "9:16", durationSeconds: 5, personGeneration: "allow_adult", sampleCount: 1 }
    })
  }
);
const { name: operationName } = await startRes.json();

// Step 2 — poll until done
let done = false;
let result;
while (!done) {
  await new Promise(r => setTimeout(r, 8000)); // wait 8 seconds
  const pollRes = await fetch(`${BASE}/${operationName}`, {
    headers: { "x-goog-api-key": API_KEY }
  });
  result = await pollRes.json();
  done = result.done === true;
}
const videoUri = result.response.generateVideoResponse.generatedSamples[0].video.uri;
console.log("Video ready:", videoUri);
```

Or skip the API key entirely — paste your prompt into the [Chat-to-Ads Studio](https://aicontentdrop.com/) or the [video generation page](https://aicontentdrop.com/best-ai-video-generator) and we'll handle the request for you. No Google Cloud project or API key needed.

## What the Response Looks Like

Veo 3.1 is an **async** model — it doesn't return the finished video instantly. Instead it returns a long-running operation immediately, and you check back for the result. This process is called **polling**: you ask "is it done yet?" every few seconds until `done` becomes `true`.

Initial response right after you POST your prompt (the operation is still running):

```
{
  "name": "operations/abc123xyz",
  "done": false
}
```

Save the `name` value. Use it to poll the GET endpoint: `GET https://generativelanguage.googleapis.com/v1beta/operations/abc123xyz`

When the video is ready, the polled response looks like this:

```
{
  "name": "operations/abc123xyz",
  "done": true,
  "response": {
    "generateVideoResponse": {
      "generatedSamples": [
        {
          "video": {
            "uri": "https://storage.googleapis.com/.../output.mp4",
            "encoding": "video/mp4"
          }
        }
      ]
    }
  }
}
```

Once `done` is `true`, your video URI lives at `response.generateVideoResponse.generatedSamples[0].video.uri`. Download the file from that URL before it expires — Google Cloud Storage signed URLs are time-limited. Most Veo 3.1 generations complete within 30–90 seconds.

## Common Errors and Fixes

- Error:
  
  INVALID_ARGUMENT
  
  — invalid value for
  
  parameters.aspectRatio
  
  Meaning:
  
  You sent a ratio Veo 3.1 doesn't support (e.g.,
  
  "3:4"
  
  or
  
  "4:3"
  
  ).
  
  Fix:
  
  Use only
  
  "16:9"
  
  ,
  
  "9:16"
  
  , or
  
  "1:1"
  
  . For portrait-ish content, use
  
  "9:16"
  
  and crop in post if needed.
- Error:
  
  INVALID_ARGUMENT
  
  — prompt exceeds maximum length
  
  Meaning:
  
  Your prompt exceeds the character limit (roughly 2000 chars).
  
  Fix:
  
  Trim your prompt. Focus on one subject, one action, and one style. Everything else is noise.
- Error:
  
  INVALID_ARGUMENT
  
  — instances[0].prompt is required
  
  Meaning:
  
  You forgot to include the
  
  prompt
  
  key inside
  
  instances[0]
  
  , or its value is an empty string.
  
  Fix:
  
  Make sure your
  
  instances
  
  array contains one object with a non-empty
  
  prompt
  
  string. It's the only required field.
- Error:
  
  PERMISSION_DENIED
  
  — 403 or 401
  
  Meaning:
  
  Your Gemini API key is missing, wrong, or the key doesn't have the Gemini API enabled.
  
  Fix:
  
  Check that your
  
  x-goog-api-key
  
  header value is copied correctly — no extra spaces or newlines. You can generate a fresh key at
  
  https://aistudio.google.com/app/apikey
  
  .
- Error:
  
  safetyAttributes
  
  block in the response — content filtered
  
  Meaning:
  
  Your prompt triggered Google's content safety guardrails — usually references to violence, explicit content, or real named individuals.
  
  Fix:
  
  Rephrase. Replace specific names with descriptions ("a tech founder" instead of a real person's name), and remove any graphic language.
- Error:
  
  RESOURCE_EXHAUSTED
  
  — 429
  
  Meaning:
  
  You've hit your Gemini API quota, or your AI Content Drop credit balance is zero.
  
  Fix:
  
  Wait before retrying. If credits are the issue, top up your account balance. On AI Content Drop, each Veo 3.1 run costs 26 credits.
- Error:
  
  done: true
  
  but
  
  response
  
  is missing or
  
  error
  
  is set in the operation
  
  Meaning:
  
  The model attempted generation but couldn't complete it. This is rare and usually a transient server issue.
  
  Fix:
  
  Retry the same request. If it fails three times in a row, check the Google AI status page. You are not charged for failed generations on AI Content Drop (post-deduct billing).

## Veo 3.1 vs Alternatives — When to Use Which

Not every video generation job calls for Veo 3.1. Here's a plain comparison to help you pick the right model. You can browse all available models on the [model marketplace](https://aicontentdrop.com/marketplace).

| Use this if… | Model | Credits |
| --- | --- | --- |
| You want the sharpest realistic footage — commercial ads, talking-head UGC, product demonstrations | Veo 3.1 | 26 |
| You need faster turnaround on quick concepts and can accept slightly lower fidelity — see the [Veo 3 Fast review](https://aicontentdrop.com/blog/veo-3-fast-review) for details | Veo 3 Fast | 14 |
| You need multi-scene narrative, storyboarding, or creative/fantastical scenes where strict realism doesn't matter — full breakdown in [Veo 3 vs Sora](https://aicontentdrop.com/blog/veo-3-vs-sora) | Sora 2 | 45 |

For a broader look at all available models, [the 2026 guide to AI video generators](https://aicontentdrop.com/blog/best-ai-video-generators-2026) covers every option with credit costs and use-case breakdowns.

## Cost Math for Newcomers

Let's work through a real example so you know what to budget.

Say you want to test **10 ad variants** for a product launch — different founders, different product angles, different hooks. Each Veo 3.1 generation costs **26 credits**. Ten variants = **260 credits**.

On the Starter plan ($19/month), you get credits that cover this test batch comfortably. On the Professional plan ($49/month), you have enough credits for roughly 4–5 full product campaigns per month. The key thing to remember: you're only charged on successful generations (post-deduct billing) — if a video fails, you keep your credits.

To minimize waste, use `"standard"` quality while you're iterating on the prompt, then switch to `"high"` only for the 2–3 variants you actually want to publish. That discipline alone can cut your credit spend by 30–40% on a typical campaign.

## Glossary

**Prompt**

The text description you write to tell an AI model what video to generate. It goes in the `prompt` field of your JSON request.

**JSON (JavaScript Object Notation)**

A plain-text format for sending structured data to APIs. It uses curly braces `{}`, key–value pairs, and commas.

**API request**

A message your code sends to a remote service (like a video model) asking it to do something. The request includes a URL, a method (POST or GET), and usually a JSON body.

**Endpoint**

The specific URL you send your request to. For Veo 3.1 via the official Google Gemini API, the endpoint is `https://generativelanguage.googleapis.com/v1beta/models/veo-3.1-generate-001:predictLongRunning`.

**Operation name**

A unique identifier the Gemini API returns when you submit a long-running generation job. It looks like `operations/abc123xyz`. You use it to poll for the video result.

**Polling**

The process of repeatedly asking the API "is the video ready yet?" by making GET requests to the status endpoint every few seconds.

**Aspect ratio**

The width-to-height proportion of the video frame. `16:9` is standard landscape; `9:16` is vertical (mobile-first); `1:1` is square.

**Seed**

A number that pins the model's randomness so you can reproduce a result. Same prompt + same seed = very similar output.

**Negative prompt**

A list of things you want the model to avoid — like "blurry, watermark, extra limbs". Goes in the `negativePrompt` field.

## FAQ

### Can I just use the chat instead of writing JSON?

Yes. The [Chat-to-Ads Studio](https://aicontentdrop.com/) lets you describe your video in plain English and handles the JSON formatting for you. Writing raw JSON gives you more precise control — but for most newcomers, starting with the chat interface is faster and less error-prone.

### What if I get a 401 or PERMISSION_DENIED error?

This means your Gemini API key is missing or invalid. Check that your `x-goog-api-key` header is spelled correctly and the value matches the key shown in [Google AI Studio](https://aistudio.google.com/app/apikey). Copy the key fresh — trailing spaces and accidental newlines are the most common cause. Also confirm the Gemini API is enabled for that key in Google Cloud Console.

### How do I get an aspect ratio not in the list?

You can't — Veo 3.1 only supports `16:9`, `9:16`, and `1:1`. If you need a different ratio (like 4:5 for an Instagram portrait ad), generate in `9:16` and crop the top and bottom in a video editor afterward. Most editing tools let you do this in under a minute.

### Does Veo 3.1 support audio or music?

Veo 3.1 generates video only — no audio track is included in the output. If you need a voiceover or background music, generate the video first, then add audio separately using your editing tool or a TTS service. The [video generation page](https://aicontentdrop.com/best-ai-video-generator) on AI Content Drop lets you combine Veo 3.1 video with audio in one workflow.