> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Veo 3.1 Official

> 官方 VEO 3.1 视频生成，支持时长、音频控制和图片引导模式

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。

通过一个异步 API 调用官方 VEO 3.1 模型系列生成视频。根据所选模型和输入，这些生成模型支持文生视频、图生视频、首尾帧视频和三图参考生成。

## 模型

* **veo3.1-fast-official** - 快速官方生成，时长可选 `4`、`6` 或 `8` 秒
* **veo3.1-lite-official** - 轻量官方生成，按秒计费单价更低
* **veo3.1-quality-official** - 更高质量的官方生成，支持 4K

## 输入模式

* 不传 `image_urls`：文生视频
* 一张图片：图生视频
* 两张图片：首尾帧视频。第一张图片为起始帧，第二张图片为结束帧
* 三张图片：参考图生成。使用 `generation_type: "reference"` 和 `duration: 8`
* `veo3.1-lite-official` 最多支持两张图片，且不支持 `generation_type: "reference"`

## 参数

* **model**：必填的模型标识。使用 `veo3.1-fast-official`、`veo3.1-lite-official` 或 `veo3.1-quality-official`
* **prompt**：必填的视频生成文本提示词，最多 `1000` 个字符
* **image\_urls**：可选的图片 URL 数组。最多支持 `3` 个公开图片 URL
* **generation\_type**：可选 `frame` 或 `reference`。省略时根据 `image_urls` 推断模式
* **duration**：`4`、`6` 或 `8`，默认 `8`。参考图生成以及 `resolution: "1080p"` 下的 `veo3.1-lite-official` 仅支持 `8`
* **aspect\_ratio**：`16:9` 或 `9:16`。单图和双图工作流还支持 `auto`。默认 `16:9`
* **resolution**：`720p`、`1080p` 或 `4k`，默认 `1080p`。`veo3.1-lite-official` 不支持 `4k`
* **sound**：布尔型音频开关。默认 `true`；设为 `false` 输出无声视频
* **callback\_url**：可选的 Webhook URL，用于接收任务完成或失败通知

## 定价

按生成的秒数计费，具体因模型、分辨率以及是否生成音频而异。当前积分表见模型页面。

## 工作流 ID

现有 ID 继续可用。新接入可以选择专用的工作流：

* [google/veo3.1/text-to-video](https://docs.vidgo.ai/zh/api-manual/video-series/google-veo3-1-text-to-video.md)
* [google/veo3.1/image-to-video](https://docs.vidgo.ai/zh/api-manual/video-series/google-veo3-1-image-to-video.md)
* [google/veo3.1-fast/text-to-video](https://docs.vidgo.ai/zh/api-manual/video-series/google-veo3-1-fast-text-to-video.md)
* [google/veo3.1-fast/image-to-video](https://docs.vidgo.ai/zh/api-manual/video-series/google-veo3-1-fast-image-to-video.md)
* [google/veo3.1-lite/text-to-video](https://docs.vidgo.ai/zh/api-manual/video-series/google-veo3-1-lite-text-to-video.md)
* [google/veo3.1-lite/image-to-video](https://docs.vidgo.ai/zh/api-manual/video-series/google-veo3-1-lite-image-to-video.md)


## OpenAPI

````yaml zh/api-manual/video-series/veo-3-1-official.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - VEO 3.1 Official API
  description: 官方 VEO 3.1 视频生成，支持时长、音频控制和图片引导模式
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境服务器
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - VEO 3.1 Official
      summary: 提交 VEO 3.1 Official 任务
      description: >-
        提交异步的官方 VEO 3.1 视频生成任务。可使用 Fast、Lite 或 Quality
        版本，支持文生视频、图生视频、首尾帧或参考图生成工作流。
      operationId: submitVeo31OfficialTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              fast:
                summary: veo3.1-fast-official
                value:
                  model: veo3.1-fast-official
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A cinematic close-up of a paper boat drifting through a
                      neon-lit canal
                    duration: 6
                    aspect_ratio: '16:9'
                    resolution: 1080p
                    sound: true
              lite:
                summary: veo3.1-lite-official
                value:
                  model: veo3.1-lite-official
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A warm handheld shot of a ceramic coffee cup on a
                      windowsill as morning light moves across the steam
                    image_urls:
                      - https://cdn.vidgo.ai/temp/veo31-official-lite-source.png
                    duration: 8
                    aspect_ratio: '16:9'
                    resolution: 1080p
                    sound: true
              quality:
                summary: veo3.1-quality-official
                value:
                  model: veo3.1-quality-official
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A high-detail aerial view of a futuristic coastal city at
                      dusk, cinematic camera movement, realistic lighting, crisp
                      architectural detail
                    image_urls:
                      - >-
                        https://cdn.vidgo.ai/temp/veo31-official-reference-character.png
                      - >-
                        https://cdn.vidgo.ai/temp/veo31-official-reference-environment.png
                      - >-
                        https://cdn.vidgo.ai/temp/veo31-official-reference-detail.png
                    generation_type: reference
                    duration: 8
                    aspect_ratio: '16:9'
                    resolution: 4k
                    sound: true
      responses:
        '200':
          description: 任务提交成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              example:
                code: 200
                data:
                  task_id: task-unified-1780000000-veo31official
                  status: not_started
                  created_time: '2026-05-20T10:30:00'
        '400':
          description: 请求无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                lite-4k:
                  summary: Lite 不支持 4K
                  value:
                    code: 400
                    message: veo3.1-lite-official does not support 4k resolution
                lite-reference:
                  summary: Lite 不支持参考图生成
                  value:
                    code: 400
                    message: veo3.1-lite-official does not support reference mode
                reference-duration:
                  summary: 参考图生成要求时长为 8 秒
                  value:
                    code: 400
                    message: reference mode supports 8s duration only
                auto-aspect-ratio:
                  summary: auto 宽高比需要一张或两张图片
                  value:
                    code: 400
                    message: >-
                      aspect_ratio auto is supported only with one or two
                      image_urls
                prompt-too-long:
                  summary: 提示词长度超出限制
                  value:
                    code: 400
                    message: >-
                      prompt must be 1000 characters or fewer for
                      veo-3.1-official
        '401':
          description: 未授权 - API Key 无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 401
                message: Unauthorized
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          example: veo3.1-fast-official
        callback_url:
          type: string
          format: uri
          description: 用于接收结果通知的 Webhook 回调 URL
          example: https://your-domain.com/callback
        input:
          type: object
          required:
            - prompt
          description: 生成所需的输入参数
          properties:
            prompt:
              type: string
              description: 必填，描述目标视频的文本提示词。
              example: >-
                A cinematic close-up of a paper boat drifting through a neon-lit
                canal.
            image_urls:
              type: array
              items:
                type: string
                format: uri
              minItems: 1
              maxItems: 3
              description: >-
                可选的图片 URL 数组。不传图片为文生视频，传一张为图生视频，传两张为首尾帧生成，传三张则必须使用参考图生成。Lite
                最多支持两张图片。
            generation_type:
              type: string
              enum:
                - frame
                - reference
              description: >-
                可选的生成模式。两张图片 URL 时使用 frame，三张图片 URL 时使用 reference。省略时根据
                image_urls 推断模式。
            duration:
              type: integer
              description: 输出时长（秒）。支持 4、6 或 8，默认 8。参考图生成和 Lite 1080p 仅支持 8。
              enum:
                - 4
                - 6
                - 8
              default: 8
              example: 8
            aspect_ratio:
              type: string
              description: 视频宽高比。auto 仅支持单图和双图工作流。
              enum:
                - auto
                - '16:9'
                - '9:16'
              default: '16:9'
              example: '16:9'
            resolution:
              type: string
              description: 输出分辨率。Lite 不支持 4k。
              enum:
                - 720p
                - 1080p
                - 4k
              default: 1080p
              example: 1080p
            sound:
              type: boolean
              description: 生成原生音频。默认为 true；设为 false 输出无声视频。
              default: true
              example: true
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          description: 响应码
          example: 200
        data:
          type: object
          description: 已提交任务的元数据
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              description: 用于跟踪状态的唯一任务标识
              example: task-unified-1780000000-veo31official
            status:
              type: string
              description: 任务初始状态
              enum:
                - not_started
              example: not_started
            created_time:
              type: string
              format: date-time
              description: 任务创建时间（ISO 8601 时间戳）
              example: '2026-05-20T10:30:00'
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: 错误码
          example: 400
        message:
          type: string
          description: 描述错误原因的错误信息
          example: duration must be one of [4, 6, 8] for veo-3.1-official
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证


        获取 API Key：


        进入 **仪表盘 → API 密钥**（[API Key
        管理页面](https://vidgo.ai/apis/dashboard/api-key)）获取你的 API Key


        在请求头中添加：


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.