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

# 图片生成视频

> Veo 3 图片生成视频 — 为图片添加动画或从图片参考创建视频

使用 Google Veo 3.1 从图片创建视频。根据输入图片数量支持三种模式。

### 可用模型

`veo3` · `veo3_fast` · `veo3_lite`

### 生成模式

<AccordionGroup>
  <Accordion title="单图生成（I2V）— 1 张图片">
    为单张图片添加动画作为首帧。视频从该图片开始并延展运动。
  </Accordion>

  <Accordion title="首尾帧视频（I2V-FL）— 2 张图片">
    创建起始帧和结束帧之间的平滑过渡视频。
  </Accordion>

  <Accordion title="参考图生成（R2V）— 1-3 张图片">
    使用 1-3 张参考图片生成视频，可用于风格迁移或创意灵感。
  </Accordion>
</AccordionGroup>

<Note>
  **模式选择：**

  * **自动推断**（默认）：系统根据图片数量自动推断模式（0→t2v, 1→i2v, 2→i2v-fl, 3→r2v）
  * **显式指定**：添加 `mode` 字段覆盖自动推断（例如：使用 1 张图片时指定 `mode: "r2v"` 作为风格参考而非首帧控制）

  **I2V vs R2V 的区别：**

  * **I2V**：图片作为视频的**首帧**（严格的帧控制）
  * **R2V**：图片作为**风格/内容参考**（灵活的创意生成）
</Note>

<ParamField body="model" type="string" required>
  模型名称，如 `veo3`、`veo3_fast`、`veo3_lite`。
</ParamField>

<ParamField body="callBackUrl" type="string">
  Webhook 回调地址。
</ParamField>

<ParamField body="input" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ParamField body="prompt" type="string" required>
      描述视频运动或过渡效果的提示词。
    </ParamField>

    <ParamField body="ratio" type="string">
      视频宽高比。可选值：`16:9`、`9:16`。默认值：`16:9`。
    </ParamField>

    <ParamField body="mode" type="string">
      显式指定生成模式：`i2v`、`i2v-fl` 或 `r2v`。可选 — 不提供时系统会根据图片数量自动推断。当需要覆盖自动推断时使用（例如：使用 1 张图片时指定 `mode: "r2v"` 作为风格参考）。
    </ParamField>

    <ParamField body="resolution" type="string">
      分辨率放大。可选值：`1080p`、`4k`。不传则为默认分辨率（不放大）。注意：I2V 单图模式不支持分辨率放大，传入会被忽略。
    </ParamField>

    <ParamField body="duration" type="integer">
      视频时长（秒）。可选值：`4`、`6`、`8`。默认值：`8`。

      Credits 按时长线性折扣。各模式/等级支持情况：

      * `i2v-fl`（首尾帧）：所有等级（Quality/Fast/Lite）均支持 4/6/8。
      * `i2v`（单图）：仅 Lite 支持 4/6/8；Quality/Fast 会静默回退到 8 秒。
      * `r2v`（多图参考）：仅支持 `8` 秒；传 4/6 会静默回退到 8 秒。
    </ParamField>

    <ParamField body="imageUrls" type="array" required>
      图片 URL 数组。必须包含 **1、2 或 3 张图片**：

      * **1 张图片**：单图动画（I2V）或风格参考（显式指定 R2V 模式）
      * **2 张图片**：首尾帧过渡（I2V-FL）或风格参考（显式指定 R2V 模式）
      * **3 张图片**：参考图生成（R2V）
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash 单图生成（I2V） theme={null}
  curl --request POST \
    --url https://api.maxapi.io/api/v1/task/submit \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "veo3",
    "callBackUrl": "https://example.com/webhook",
    "input": {
      "prompt": "海浪轻柔地涌动，太阳慢慢落下",
      "ratio": "16:9",
      "imageUrls": ["https://example.com/beach.jpg"]
    }
  }'
  ```

  ```bash 首尾帧生成（I2V-FL） theme={null}
  curl --request POST \
    --url https://api.maxapi.io/api/v1/task/submit \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "veo3",
    "callBackUrl": "https://example.com/webhook",
    "input": {
      "prompt": "从白天平滑过渡到夜晚",
      "ratio": "16:9",
      "resolution": "1080p",
      "imageUrls": [
        "https://example.com/day.jpg",
        "https://example.com/night.jpg"
      ]
    }
  }'
  ```

  ```bash 参考图生成（R2V）使用 1 张图片 theme={null}
  curl --request POST \
    --url https://api.maxapi.io/api/v1/task/submit \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "veo3",
    "callBackUrl": "https://example.com/webhook",
    "input": {
      "prompt": "创建一个受中国水墨画风格启发的视频",
      "ratio": "16:9",
      "mode": "r2v",
      "resolution": "1080p",
      "imageUrls": ["https://example.com/reference.jpg"]
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 提交成功 theme={null}
  {
    "code": 0,
    "msg": "ok",
    "data": {
      "taskId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  }
  ```
</ResponseExample>

***

## 查询结果

```json theme={null}
{
  "code": 0,
  "msg": "ok",
  "data": {
    "taskId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "SUCCESS",
    "input": {
      "model": "veo3",
      "prompt": "海浪轻柔地涌动，太阳慢慢落下",
      "ratio": "16:9",
      "imageUrls": ["https://example.com/beach.jpg"]
    },
    "result": {
      "type": "video",
      "urls": [
        "https://example.com/output/video-b2c3d4e5.mp4"
      ]
    },
    "created_at": "2026-02-12T11:00:00.000000Z",
    "updated_at": "2026-02-12T11:02:45.000000Z"
  }
}
```

<Warning>
  **图片要求：**

  * 格式：JPEG、PNG、WebP
  * 必须是公网可访问的 HTTPS 地址
  * 建议大小：单张图片 \< 10MB
  * 宽高比应与 `ratio` 参数匹配
</Warning>

<Note>
  **速度模式限制：**

  * **R2V 模式（3 张图片）**：不支持 Quality 质量模式。如果使用 `veo3` 模型，将自动回退到 Fast 模式。建议明确使用 `veo3_fast`。
  * **Lite 模式（`veo3_lite`）**：仅支持 I2V（单图，固定 720p）和 I2V-FL（首尾帧）。不支持 R2V — 传 3 张图片会直接报错。`resolution` 参数会被忽略。
</Note>