Veo 3.1 Fast Video Generation

This document describes the hboom-compatible Gemini video generation endpoint:

POST /v1beta/models/veo-3.1-fast-generate-preview:generateContent

The request body follows the Gemini generateContent style using contents[].parts[], not the instances/parameters structure found in Google's native Veo REST docs.

Endpoint

POST https://hboom.ai/v1beta/models/veo-3.1-fast-generate-preview:generateContent

Authentication

• hboom gateway: Authorization: Bearer sk-xxxxxxxxxxxx
• Google native Gemini API: typically uses x-goog-api-key: $GEMINI_API_KEY

Minimal Request Example

curl "https://hboom.ai/v1beta/models/veo-3.1-fast-generate-preview:generateContent" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "A cinematic shot of a majestic lion in the savannah."
          }
        ]
      }
    ]
  }'

Request Body Structure

{
  "contents": [
    {
      "parts": [
        {
          "text": "A cinematic shot of a majestic lion in the savannah."
        }
      ]
    }
  ]
}

Common Request Fields

Field	Required	Description
contents	Yes	Input content array
contents[].role	No	Role, typically user
contents[].parts	Yes	Content parts array
parts[].text	Yes	Video generation prompt
parts[].inlineData	No	Inline image/audio/video data for image-to-video or reference material
parts[].fileData	No	File reference for uploaded assets
generationConfig	No	Generation config (aspect ratio, duration, output preferences, etc.)
safetySettings	No	Safety filter settings

TIP

The key point of this compatible endpoint is that the entry is still called generateContent, but the model is a video model — so the result is typically an async video task or a video result reference, not a text response.

Examples

Text-only Prompt

{
  "contents": [
    {
      "parts": [
        {
          "text": "A drone shot flying over snowy mountains at sunrise, cinematic, realistic lighting."
        }
      ]
    }
  ]
}

With System Prompt

{
  "system_instruction": {
    "parts": [
      {
        "text": "Generate concise, high-motion cinematic video prompts."
      }
    ]
  },
  "contents": [
    {
      "parts": [
        {
          "text": "A cat surfing on ocean waves at sunset."
        }
      ]
    }
  ]
}

With Reference Image

{
  "contents": [
    {
      "parts": [
        {
          "text": "Animate this character walking through a neon-lit city street."
        },
        {
          "fileData": {
            "mimeType": "image/png",
            "fileUri": "https://example.com/reference.png"
          }
        }
      ]
    }
  ]
}

Response

Although this endpoint uses the generateContent request style, video generation is still processed as an async task.

The initial request typically returns a task object or operation object with a video result reference, not the final video file directly. Since this is a platform-compatible endpoint, refer to the actual gateway response for the exact fields.

Queued

{
  "id": "video_task_123",
  "object": "video.task",
  "model": "veo-3.1-fast-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600
}

Processing

{
  "id": "video_task_123",
  "object": "video.task",
  "model": "veo-3.1-fast-generate-preview",
  "status": "processing",
  "progress": 42,
  "created_at": 1712697600
}

Completed

{
  "id": "video_task_123",
  "object": "video.task",
  "model": "veo-3.1-fast-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1712697600,
  "completed_at": 1712697815,
  "result": {
    "video_url": "https://example.com/output.mp4"
  }
}

Failed

{
  "id": "video_task_123",
  "object": "video.task",
  "model": "veo-3.1-fast-generate-preview",
  "status": "failed",
  "progress": 15,
  "error": {
    "code": "generation_blocked",
    "message": "The request was blocked by a safety filter."
  }
}

Difference from Google's Native API

As of 2026-03-23, Google's native Veo 3.1 REST docs (updated 2026-03-05 UTC) use:

POST /v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning

In other words:

• Google native: predictLongRunning style
• hboom compatible: generateContent style

These are different request body formats — be sure to distinguish them clearly.

References

• Gemini Veo 3.1 Video Docs: https://ai.google.dev/gemini-api/docs/video?hl=zh-CN
• Gemini Text Generation: https://ai.google.dev/gemini-api/docs/text-generation