> ## 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.

# 视频生成

> 通过 OpenAI 兼容 /v1/videos 创建和管理 Sora 视频任务

通过 `/v1/videos` 创建 OpenAI 兼容的 Sora 视频任务。本文只描述 OpenAI 官方契约；关于 HingNet AI 的模型分组路由、灰色 / reverse 渠道差异和平台扩展字段，请参考 [Sora 视频路由与分组](/guide/sora-video-routing)。

## 官方参考

* [OpenAI API Reference: Create video](https://platform.openai.com/docs/api-reference/videos/create)
* [OpenAI Video Generation Guide](https://platform.openai.com/docs/guides/video-generation)

## 创建视频任务

### `multipart/form-data`

当你需要直接上传参考图文件时，使用 multipart 表单：

```bash theme={null}
curl -X POST "https://models.hingnet.com.cn/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=sora-2" \
  -F "prompt=百事可乐宣传片，都市街拍风，年轻活力，镜头运动丰富" \
  -F "seconds=8" \
  -F "size=720x1280" \
  -F "input_reference=@/absolute/path/to/ref.jpg"
```

### `application/json`

当你使用 JSON 请求体时，`input_reference` 应为单个对象，而不是数组：

```bash theme={null}
curl -X POST "https://models.hingnet.com.cn/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "百事可乐宣传片，都市街拍风，年轻活力，镜头运动丰富",
    "seconds": 8,
    "size": "720x1280",
    "input_reference": {
      "image_url": "https://example.com/ref.jpg"
    }
  }'
```

<Callout type="warning">
  `input_reference` 的官方 JSON 结构是单个对象，例如 `{ "image_url": "..." }` 或 `{ "file_id": "..." }`；不要传 `["https://..."]` 这样的数组。
</Callout>

## 请求字段

* `model`：模型名称，例如 `sora-2`、`sora-2-pro`
* `prompt`：视频生成提示词
* `seconds`：使用当前 OpenAI 官方文档允许的时长值。当前 API Reference 公开了 `4`、`8`、`12`；Video Generation Guide 还描述了部分官方 Sora 2 / Sora 2 Pro 工作流中的更长时长。请以你配置的官方渠道实际支持能力为准。
* `size`：使用当前 OpenAI 官方文档允许的分辨率值。当前 API Reference 列出 `720x1280`、`1280x720`、`1024x1792`、`1792x1024`；Video Generation Guide 还描述了部分官方 `sora-2-pro` 工作流中的 `1920x1080`、`1080x1920`。
* `input_reference`：
  * `multipart/form-data` 下：单个文件字段
  * `application/json` 下：单个对象，例如 `{"image_url":"..."}` 或 `{"file_id":"file_..."}`

## 响应示例

```json theme={null}
{
  "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
  "object": "video",
  "created_at": 1762789802,
  "status": "queued",
  "model": "sora-2",
  "prompt": "百事可乐宣传片",
  "progress": 0,
  "seconds": "8",
  "size": "720x1280"
}
```

## 官方工作流

1. 创建任务：`POST /v1/videos`
2. 查询状态：`GET /v1/videos/{video_id}`，见 [视频查询](/openai/video-query)
3. 下载结果：`GET /v1/videos/{video_id}/content`，见 [视频下载](/openai/video-download)

<Callout type="info">
  如果你对外承诺“OpenAI 官方兼容”，请把这份页面视为公开契约边界；灰色渠道时长槽位、宽高比别名和角色扩展字段不应继续写入 OpenAI 主文档。
</Callout>


## 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

````