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

# Video Inputs

> Send videos to supported models and check their duration, size and format limits.

> [!NOTE]
>
> Use a current public model ID from [Models](https://nomask.ai/models) or `GET /models`. Example IDs and options must match the selected model's advertised capabilities and limits.

Send a video with your prompt to a model marked Video input. Check the model's details for its maximum duration, file size and supported formats before uploading.

## Choose a video model

Open [API Models](https://nomask.ai/models), choose the **Video input** filter and open a model. Its Video input section shows the current limits. These settings vary by model; a model that accepts images may not accept video.

You can also check `GET /models` or `GET /models/{model}`. A supported model has `capabilities.video: true` and a `video_input`object containing `max_duration_seconds`, `max_file_size_mb` and `allowed_formats`. Unsupported models return `video_input: null`.

## Send a video

In a user message, make `content` an array with a text part and a `video_url` part. Send at most one video across the entire request, including conversation history. This example uses `MP4` on a model that accepts that format.

```json theme={"system"}
{
  "model": "your-video-model-id",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe the main events in this clip."},
      {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}
    ]
  }]
}
```

```bash theme={"system"}
curl https://api.nomask.ai/v1/chat/completions \
  -H "Authorization: Bearer $NOMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"your-video-model-id",
    "messages":[{"role":"user","content":[
      {"type":"text","text":"Describe the main events in this clip."},
      {"type":"video_url","video_url":{"url":"https://example.com/clip.mp4"}}
    ]}]
  }'
```

## Direct URLs and inline data

A URL must be a publicly accessible HTTPS link to the video file itself. Watch pages, embedded players, private hosts and URLs requiring redirects are not supported. The file must be readable without a login or custom request headers.

Alternatively, send the video as a base64 data URL with its matching media type:

```json theme={"system"}
{"type":"video_url","video_url":{"url":"data:video/mp4;base64,AAAA..."}}
```

For an allowed MOV file use `video/quicktime`, for WebM use `video/webm`, and for MPEG use `video/mpeg`. The model's allowed formats still apply. Replace the example's shortened base64 with the complete file; base64 increases the JSON request size.

## Duration, size and billing

The actual file size, format and duration are checked before generation. Changing the filename, media type or a claimed duration does not bypass the model's limits. Shorten or compress a clip that exceeds the values shown in its model details.

Video contributes to the model's input token usage. Reported usage determines billing; when exact usage is unavailable, the API uses an estimate marked `tokens_estimated` in the usage record. Streaming and reasoning options continue to work as documented for the model.

Video is processed only for the request and is not retained in your billing or analytics records. See [Privacy](https://docs.nomask.ai/privacy.md).

## Video errors

| Code | What to check |
| - | - |
| `model_lacks_video` | Choose a model marked Video input. |
| `invalid_video` | Use a complete, readable video with the matching media type. |
| `video_unsupported_format` | Use one of the formats in the model's details. |
| `video_duration_exceeded` / `video_too_large` | Shorten or compress the video to fit that model's duration and size limits. |
| `video_fetch_failed` | Use a direct public HTTPS file URL without redirects, or send inline base64 data. |
| `video_input_unavailable` | Video processing is temporarily unavailable. Retry later. |


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