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

# Grok Video 1.5 Generation

> Generate videos from text, a first frame, or reference images

> [!NOTE]
>
> For users in mainland China, use `https://toapis.cn` instead of `https://toapis.com` in these examples.

Use `grok-video-1.5` with one of the three input modes below. Modes are available only when enabled on a compatible channel. A successful price quote does not guarantee that a generation channel is available.

> [!WARNING]
>
> Use public `http://` or `https://` image URLs. For local files, use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) first. Do not send base64 data. JSON with uploaded URLs works across the supported channels; some channels reject multipart binary uploads.

## Generation modes

| Mode | Input |
| - | - |
| `text_to_video` | Text only, no images |
| `first_frame_image_to_video` | Exactly one first frame |
| `reference_images_to_video` | 1-7 reference images, including the single-reference case |

For new requests, set `video_generation_mode` explicitly. Without it, legacy single-image input remains image-to-video; one `reference_images` entry alone does not select reference mode. Text mode rejects images.

## Authorization

**Authorization** `string` *required*

Authenticate with your API key as a Bearer token.

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required* (default: grok-video-1.5)

Use the public model name `grok-video-1.5`; do not substitute a supplier model name.

**prompt** `string`

Describe the scene and motion. Required for text and reference modes. Some legacy single-frame requests may omit it; other first-frame requests may still require it. Include a non-empty prompt in new integrations.

**video\_generation\_mode** `string`

Optional for legacy clients. Choose the value matching the input: `text_to_video` for text only, `first_frame_image_to_video` for exactly one first frame via `image` or `input_reference`, `reference_images_to_video` for 1-7 `reference_images`. A mode that does not match the media fields is rejected. Explicit reference mode is required to distinguish one reference image from a legacy single-frame input.

**image** `string`

One first-frame URL. Required in first-frame mode, unless `input_reference` is used instead. Omit in text and pure reference mode. The upstream handling of a first frame depends on the channel.

**input\_reference** `string`

String alias for the first-frame URL. Use `image` or `input_reference`, not conflicting values in both. For portable new requests using this alias, also set the mode explicitly.

**reference\_images** `array`

1-7 reference URLs, as strings or objects such as `{"url":"https://example.com/reference.jpg"}`. Required in reference mode. Legacy `image_urls` and `images` aliases remain supported, but avoid sending multiple list fields with different contents.

**duration** `integer`

Integer seconds. Set it explicitly. Supports 1-15 seconds.

**resolution** `string`

Use `480p` or `720p` for reference mode. Text and first-frame modes may use `1080p` when supported by the channel. These examples explicitly request `720p`.

**aspect\_ratio** `string`

Video aspect ratio, for example `16:9`. Common values are `1:1`, `16:9`, `9:16`, `3:2` and `2:3`; availability depends on the channel.

## Compatibility limits

Some channels handle single-frame and single-reference input in the same way. The mode name does not guarantee a strict first frame there. Enabling a mode does not remove protocol limits. Unsupported input can be rejected before submission; requests with no compatible enabled channel cannot generate a task.

## Pricing

Video pricing follows the current account and SKU configuration. Check [current pricing](https://toapis.com/pricing) and the authenticated quote for your parameters. No fixed per-second price is guaranteed by this page.

## Create a video task

The examples explicitly specify the mode, duration and resolution. Replace example image URLs with accessible images.

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "grok-video-1.5",
  "prompt": "A cinematic product shot with a slow camera push-in",
  "video_generation_mode": "text_to_video",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "grok-video-1.5",
        "prompt": "A cinematic product shot with a slow camera push-in",
        "video_generation_mode": "first_frame_image_to_video",
        "image": "https://example.com/first-frame.jpg",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    },
)
response.raise_for_status()
print(response.json()["id"])
```

### Reference images

```json theme={null}
{
  "model": "grok-video-1.5",
  "prompt": "A cinematic product shot with a slow camera push-in",
  "video_generation_mode": "reference_images_to_video",
  "reference_images": [
    "https://example.com/reference-a.jpg",
    "https://example.com/reference-b.jpg"
  ],
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

## Response

**id** `string`

Task ID used for polling.

**object** `string`

Object type: `generation.task`.

**model** `string`

Public model name.

**status** `string`

Task state: `queued`, `in_progress`, `completed` or `failed`.

```json 200 theme={null}
{
  "id": "video_abc123def456",
  "object": "generation.task",
  "model": "grok-video-1.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380224,
  "metadata": {}
}
```

## Query task status

Use the returned `id` with [Video Task Status](https://docs.toapis.com/docs/en/api-reference/tasks/video-status.md).


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