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

# Image to Video

> Veo 3 Image-to-Video — Animate images or create videos from image references

Use Google Veo 3.1 to create videos from images. Supports three modes based on the number of input images.

### Available Models

`veo3` · `veo3_fast` · `veo3_lite`

### Generation Modes

<AccordionGroup>
  <Accordion title="Single Image (I2V) — 1 image">
    Animate a single image as the first frame. The video starts from this image and extends the motion.
  </Accordion>

  <Accordion title="First + Last Frame (I2V-FL) — 2 images">
    Create a smooth transition video between a start frame and an end frame.
  </Accordion>

  <Accordion title="Reference Images (R2V) — 1-3 images">
    Generate a video using 1-3 reference images for style transfer or creative inspiration.
  </Accordion>
</AccordionGroup>

<Note>
  **Mode Selection:**

  * **Auto-inference** (default): System infers mode from image count (0→t2v, 1→i2v, 2→i2v-fl, 3→r2v)
  * **Explicit mode**: Add `mode` field to override auto-inference (e.g., use `mode: "r2v"` with 1 image for style reference instead of first-frame control)

  **I2V vs R2V difference:**

  * **I2V**: Image becomes the video's **first frame** (strict frame control)
  * **R2V**: Image serves as **style/content reference** (flexible creative generation)
</Note>

<ParamField body="model" type="string" required>
  Model name, e.g. `veo3`, `veo3_fast`, `veo3_lite`.
</ParamField>

<ParamField body="callBackUrl" type="string">
  Webhook callback URL.
</ParamField>

<ParamField body="input" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ParamField body="prompt" type="string" required>
      Prompt describing the video motion or transition effect.
    </ParamField>

    <ParamField body="ratio" type="string">
      Video aspect ratio. Options: `16:9`, `9:16`. Default: `16:9`.
    </ParamField>

    <ParamField body="mode" type="string">
      Explicitly specify generation mode: `i2v`, `i2v-fl`, or `r2v`. Optional — system auto-infers from image count if not provided. Use this when you want to override auto-inference (e.g., `mode: "r2v"` with 1 image for style reference).
    </ParamField>

    <ParamField body="resolution" type="string">
      Resolution upscale. Options: `1080p`, `4k`. Default: standard resolution (no upscale). Note: I2V (single image) mode does not support resolution upscale — the parameter will be ignored.
    </ParamField>

    <ParamField body="duration" type="integer">
      Video length in seconds. Options: `4`, `6`, `8`. Default: `8`.

      Credits scale linearly with duration. Mode/tier support:

      * `i2v-fl` (first+last frame): all tiers (Quality, Fast, Lite) support 4/6/8.
      * `i2v` (single image): only Lite supports 4/6/8; Quality/Fast silently fall back to 8s.
      * `r2v` (multi-image reference): only `8` supported; 4/6 silently fall back to 8.
    </ParamField>

    <ParamField body="imageUrls" type="array" required>
      Array of image URLs. Must contain **1, 2, or 3 images**:

      * **1 image**: Single image animation (I2V) or style reference (R2V with explicit mode)
      * **2 images**: First + last frame transition (I2V-FL) or style reference (R2V with explicit mode)
      * **3 images**: Reference-based video generation (R2V)
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash Single Image (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": "The waves gently move and the sun slowly sets",
      "ratio": "16:9",
      "imageUrls": ["https://example.com/beach.jpg"]
    }
  }'
  ```

  ```bash First + Last Frame (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": "Smooth transition from daytime to nighttime",
      "ratio": "16:9",
      "resolution": "1080p",
      "imageUrls": [
        "https://example.com/day.jpg",
        "https://example.com/night.jpg"
      ]
    }
  }'
  ```

  ```bash Reference Images (R2V) with 1 image 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": "Create a video inspired by this artistic style",
      "ratio": "16:9",
      "mode": "r2v",
      "resolution": "1080p",
      "imageUrls": ["https://example.com/reference.jpg"]
    }
  }'
  ```
</RequestExample>

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

***

## Query Result

```json theme={null}
{
  "code": 0,
  "msg": "ok",
  "data": {
    "taskId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "SUCCESS",
    "input": {
      "model": "veo3",
      "prompt": "The waves gently move and the sun slowly sets",
      "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>
  **Image Requirements:**

  * Formats: JPEG, PNG, WebP
  * Must be publicly accessible HTTPS URLs
  * Recommended size: \< 10MB per image
  * Aspect ratio should match the `ratio` parameter
</Warning>

<Note>
  **Speed Mode Limitations:**

  * **R2V mode (3 images)**: Does not support Quality mode. If you use `veo3` model, it will automatically fall back to Fast mode. We recommend explicitly using `veo3_fast` for R2V.
  * **Lite mode (`veo3_lite`)**: Supports I2V (single image, fixed at 720p) and I2V-FL (first+last frame) only. Does not support R2V — requests with 3 images will fail. The `resolution` parameter is ignored.
</Note>