YL AI

Appearance

Veo 3.1 Fast 视频生成 ​

本文档说明YL兼容的 Gemini 视频生成接口：

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

它的请求体风格与 Gemini generateContent 一致，使用 contents[].parts[] 传入内容，而不是 Google 官方 Veo 原生 REST 文档里的 instances/parameters 结构。

请求地址 ​

text
POST https://huobaoapi.com/v1beta/models/veo-3.1-fast-generate-preview:generateContent

鉴权 ​

  • YL网关：Authorization: Bearer sk-xxxxxxxxxxxx
  • Google 官方原生 Gemini API：通常使用 x-goog-api-key: $GEMINI_API_KEY

最小请求示例 ​

如果你只是传一个视频提示词，请求体就是这种结构：

bash
curl "https://huobaoapi.com/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."
          }
        ]
      }
    ]
  }'

请求体结构 ​

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

常用请求字段 ​

字段必填说明
contents是输入内容数组
contents[].role否角色，常见为 user
contents[].parts是内容片段数组
parts[].text是视频生成提示词
parts[].inlineData否内联图片、音频或视频数据；如平台支持，可用于图生视频或参考素材
parts[].fileData否文件引用；如平台支持，可用于引用已上传素材
generationConfig否生成配置；如平台支持，可放宽高比、时长、输出偏好等扩展参数
safetySettings否安全过滤设置

TIP

这类兼容接口的关键点是：入口仍然叫 generateContent，但模型本身是视频模型，所以最终结果通常不是一段文本，而是一个异步视频任务或视频结果引用。

示例 ​

纯文本提示词生成视频 ​

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

带系统提示词 ​

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

带参考图片 ​

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

返回说明 ​

该接口虽然使用 generateContent 风格的请求体，但视频生成通常仍然按异步任务处理。

也就是说，首次请求通常不会直接返回最终视频文件，而是先返回一个任务对象、操作对象，或者包含视频结果引用的响应。由于这是平台兼容接口，实际返回字段请以网关真实响应为准。

兼容任务返回示例 ​

下面是适合文档展示的兼容示例：

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

处理中示例 ​

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

完成示例 ​

json
{
  "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"
  }
}

失败示例 ​

json
{
  "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."
  }
}

WARNING

上面的任务返回示例是按“平台兼容的 generateContent 视频接口”整理的文档示例，不是 Google 官方逐字返回。你的网关如果已有固定字段，应以实际返回为准继续细化。

建议文档口径 ​

如果你的平台就是这种接口风格，文档建议统一写成：

  • 请求入口：POST /v1beta/models/veo-3.1-fast-generate-preview:generateContent
  • 请求体结构：contents[].parts[].text
  • 结果类型：异步视频任务
  • 状态字段：status、progress
  • 成功结果：返回视频地址或文件引用

与 Google 官方原生接口的差异 ​

截至 2026-03-23，Google AI for Developers 在 2026-03-05 UTC 更新的 Veo 3.1 文档里，原生 REST 主示例仍是：

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

也就是说：

  • Google 官方原生：偏 predictLongRunning 风格
  • 你当前需要的YL兼容文档：偏 generateContent 风格

这两者不是同一套请求体格式，文档里需要明确区分。

参考文档 ​

YL AI

Copyright © 2024-present