Multimodal Video Input

Lunos supports video input for compatible models through the Chat Completions API. You can send video as a public URL or as a base64 data URL.

Use video URL when your file is publicly accessible and your selected provider accepts URL-based video input.
Use base64 data URL for local files, private assets, or providers that do not support direct video URLs.

Video URL behavior depends on provider-level capabilities. For example, some Gemini routes only accept YouTube links while others require base64 payloads.

Endpoint

POST /v1/chat/completions

Video content format

Send video in the message content array using type: "video_url":

{
  "type": "video_url",
  "video_url": {
    "url": "https://example.com/video.mp4"
  }
}

Only models with video input capability can process this payload. Check model metadata and ensure inputModalities includes video.

Send video using URL

cURL Python TypeScript

curl -X POST "https://api.lunos.tech/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe what happens in this video." },
          { "type": "video_url", "video_url": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } }
        ]
      }
    ]
  }'

import requests

payload = {
    "model": "google/gemini-2.5-flash",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe what happens in this video."},
                {
                    "type": "video_url",
                    "video_url": {"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
                },
            ],
        }
    ],
}
response = requests.post(
    "https://api.lunos.tech/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())

const response = await fetch("https://api.lunos.tech/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/gemini-2.5-flash",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Describe what happens in this video." },
          {
            type: "video_url",
            video_url: { url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
          },
        ],
      },
    ],
  }),
});
console.log(await response.json());

Send video using base64 data URL

Use this method when the video is local/private or when your provider route does not accept direct video URLs.

Python

import base64
import requests

def encode_video(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

base64_video = encode_video("path/to/video.mp4")
data_url = f"data:video/mp4;base64,{base64_video}"

payload = {
    "model": "google/gemini-2.5-flash",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is shown in this video?"},
                {"type": "video_url", "video_url": {"url": data_url}},
            ],
        }
    ],
}

response = requests.post(
    "https://api.lunos.tech/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)

print(response.json())

TypeScript

import { readFile } from "node:fs/promises";

async function encodeVideo(path: string) {
  const buffer = await readFile(path);
  return `data:video/mp4;base64,${buffer.toString("base64")}`;
}

const dataUrl = await encodeVideo("path/to/video.mp4");

const response = await fetch("https://api.lunos.tech/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/gemini-2.5-flash",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "What is shown in this video?" },
          { type: "video_url", video_url: { url: dataUrl } },
        ],
      },
    ],
  }),
});

console.log(await response.json());

Supported video formats

video/mp4
video/mpeg
video/mov
video/webm

Common use cases

Best practices

File size and cost

Compress videos where possible.
Trim to relevant segments.
Use practical resolution (for example 720p for general analysis).
Lower frame rate if high temporal detail is not required.

Video duration

Check model-specific maximum duration.
Split long footage into shorter clips.
Focus prompts on key moments.

Quality trade-offs

High quality is better for detailed detection and text reading.
Medium quality is enough for most content understanding tasks.
Lower quality is acceptable for coarse scene/action summaries.

Provider-specific URL support

URL support is provider-specific and may differ for the same model family.
Some routes accept only specific video hosts.
If URL input fails on your chosen route, use base64 data URL.

Troubleshooting

Video not processed

Confirm the selected model supports video in inputModalities.
Verify your provider route supports URL-based video input.
If using Gemini AI Studio routes, prefer YouTube URLs.
If direct URL fails, switch to base64 data URL.
Check file format and ensure the video is not corrupted.

Large payload or timeout

Compress, trim, or lower resolution/frame rate.
Check provider/model limits for video size and duration.
For supported providers, use URL input for large public files.

Weak analysis quality

Improve video quality or lighting.
Use more specific prompts about what to analyze.
Send shorter clips focused on relevant events.