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

# 视频生成

> 使用 Veo 模型生成视频

## 可用模型

| 模型                              | 说明        |
| ------------------------------- | --------- |
| `veo-3.1-generate-preview`      | 标准质量，画质更优 |
| `veo-3.1-fast-generate-preview` | 快速出片，速度更快 |

## 创建视频任务

### 文生视频

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "A cinematic shot of a lion walking through golden savanna at sunset, dramatic lighting",
    "seconds": 6,
    "size": "1280x720"
  }'
```

### 图生视频

通过参考图生成视频，支持以下方式：

**JSON 方式（URL）：**

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Camera slowly zooms in, cinematic lighting",
    "seconds": 6,
    "size": "1280x720",
    "input_reference": ["https://example.com/image.jpg"]
  }'
```

**Multipart 方式（上传文件）：**

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Camera slowly zooms in, cinematic lighting" \
  -F "seconds=6" \
  -F "size=1280x720" \
  -F "input_reference=@image.jpg"
```

### 首尾帧视频

提供首帧和尾帧图片，生成过渡视频：

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Smooth transition between scenes",
    "seconds": 6,
    "size": "1280x720",
    "input_reference": [
      "https://example.com/first_frame.jpg",
      "https://example.com/last_frame.jpg"
    ]
  }'
```

### 响应示例

```json theme={null}
{
  "id": "video_abc123",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1761234567
}
```

## 查询任务状态

```bash theme={null}
curl "$BASE_URL/v1/videos/{video_id}" \
  -H "Authorization: Bearer $TOKEN"
```

### 状态说明

| 状态            | 说明  |
| ------------- | --- |
| `queued`      | 排队中 |
| `in_progress` | 生成中 |
| `completed`   | 已完成 |
| `failed`      | 失败  |

### 完成响应示例

```json theme={null}
{
  "id": "video_abc123",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "completed",
  "progress": 100,
  "video_url": "https://...",
  "seconds": 6,
  "size": "1280x720"
}
```

## 下载视频

```bash theme={null}
curl -L "$BASE_URL/v1/videos/{video_id}/content" \
  -H "Authorization: Bearer $TOKEN" \
  -o output.mp4
```

## 参数说明

| 参数                | 类型         | 必填 | 说明                 |
| ----------------- | ---------- | -- | ------------------ |
| `model`           | string     | 是  | 模型名称               |
| `prompt`          | string     | 是  | 文本提示词              |
| `seconds`         | int/string | 否  | 视频时长：4、6、8 秒（默认 6） |
| `size`            | string     | 否  | 分辨率（见下表）           |
| `input_reference` | array      | 否  | 参考图 URL 数组（1-3 张）  |

### 分辨率选项

| 分辨率         | 画幅      | 说明             |
| ----------- | ------- | -------------- |
| `1280x720`  | 16:9 横屏 | 720p（默认）       |
| `720x1280`  | 9:16 竖屏 | 720p           |
| `1920x1080` | 16:9 横屏 | 1080p（仅支持 8 秒） |
| `1080x1920` | 9:16 竖屏 | 1080p（仅支持 8 秒） |

## 最佳实践

* **提示词**：描述具体场景、镜头运动、光线氛围，效果更佳
* **1080p 限制**：高清分辨率仅支持 8 秒时长
* **参考图**：建议与目标画幅比例一致
* **轮询间隔**：建议 6-10 秒，避免频繁请求
* **快速版 vs 标准版**：快速版适合预览，标准版画质更优


## OpenAPI

````yaml POST /v1/videos
openapi: 3.0.0
info:
  title: Gemini Veo Video API
  description: Gemini Veo 视频生成 API（OpenAI 风格）
  version: 1.0.0
servers:
  - url: https://models.hingnet.com.cn
    description: HingNet 生产环境
security:
  - BearerAuth: []
paths:
  /v1/videos:
    post:
      tags:
        - Veo Videos
      summary: 创建视频任务
      description: 使用 Veo 模型创建视频生成任务
      operationId: createVeoVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VideoCreateRequestForm'
      responses:
        '200':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoObject'
              example:
                id: video_abc123
                object: video
                created_at: 1761234567
                status: queued
                model: veo-3.1-fast-generate-preview
                prompt: A cinematic lion at sunset
                progress: 0
                seconds: 6
                size: 1280x720
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 认证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    VideoCreateRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: 模型名称
          enum:
            - veo-3.1-generate-preview
            - veo-3.1-fast-generate-preview
          example: veo-3.1-fast-generate-preview
        prompt:
          type: string
          description: 文本提示词
          example: A cinematic lion at sunset
        seconds:
          oneOf:
            - type: integer
            - type: string
          description: 视频时长（秒）：4、6、8
          example: 6
        size:
          type: string
          description: 分辨率
          enum:
            - 1280x720
            - 720x1280
            - 1920x1080
            - 1080x1920
          default: 1280x720
          example: 1280x720
        input_reference:
          type: array
          description: 参考图 URL 数组（1-3 张）
          items:
            type: string
          example:
            - https://example.com/image.jpg
    VideoCreateRequestForm:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: 模型名称
          example: veo-3.1-fast-generate-preview
        prompt:
          type: string
          description: 文本提示词
          example: A cinematic lion at sunset
        seconds:
          type: integer
          description: 视频时长（秒）
          example: 6
        size:
          type: string
          description: 分辨率
          example: 1280x720
        input_reference:
          type: string
          format: binary
          description: 参考图文件
    VideoObject:
      type: object
      properties:
        id:
          type: string
          description: 任务 ID
          example: video_abc123
        object:
          type: string
          enum:
            - video
          example: video
        created_at:
          type: integer
          description: 创建时间戳
          example: 1761234567
        completed_at:
          type: integer
          description: 完成时间戳
        status:
          type: string
          description: 任务状态
          enum:
            - queued
            - in_progress
            - completed
            - failed
          example: queued
        model:
          type: string
          description: 模型名称
          example: veo-3.1-fast-generate-preview
        prompt:
          type: string
          description: 提示词
        progress:
          type: number
          description: 进度（0-100）
          example: 0
        seconds:
          type: integer
          description: 视频时长
          example: 6
        size:
          type: string
          description: 分辨率
          example: 1280x720
        video_url:
          type: string
          description: 视频直链（完成后返回）
        error:
          $ref: '#/components/schemas/VideoError'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
    VideoError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API Key

````