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

# API для понимания видео

> Используйте продвинутые модели, такие как Gemini 3.5 Flash и Gemini 3.1 Pro предпросмотр, для интеллектуального анализа видео — распознавания контента, описания сцен, анализа действий и привязки к временным меткам

APIYI предоставляет понимание видео через мультимодальные модели Gemini: по одному prompt модель «просматривает» сцены, действия, текст на экране и аудио в видео и может ссылаться на ключевые моменты по timestamp. На этой странице описаны поддерживаемые модели, способы ввода видео, которые действительно работают, и ограничения, на которых люди часто спотыкаются.

<Note>
  **Сначала прочитайте это**: видео можно передать только через **Base64 inline (весь запрос ≤ 20 MB)** или **ссылку YouTube** (нативный формат Gemini). Передача обычного публичного video URL (например, `https://example.com/demo.mp4`) возвращает `Request contains an invalid argument` —— это Google отклоняет прямые ссылки, а не блокировка со стороны APIYI. См. «Способы ввода видео» ниже.
</Note>

<CardGroup cols={2}>
  <Card title="Визуальное тестирование API" icon="flask-conical" href="https://icover.ai/video-understanding">
    Загрузите видео и протестируйте эндпоинт понимания в визуальном инструменте тестирования iCover.
  </Card>
</CardGroup>

## Поддерживаемые модели

| Модель                     | ID модели                | Основные преимущества                                                            | Рекомендуется для                                    |
| -------------------------- | ------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Gemini 3.5 Flash** 🔥    | `gemini-3.5-flash`       | Быстрая, лучшее соотношение цены и качества, сильные мультимодальные возможности | Выбор по умолчанию для повседневного анализа видео   |
| **Gemini 3.1 Pro Preview** | `gemini-3.1-pro-preview` | Самое сильное рассуждение Google + мультимодальные возможности                   | Сложный, глубокий анализ длинного видео              |
| **Gemini 3.1 Flash Lite**  | `gemini-3.1-flash-lite`  | Сверхнизкая цена и задержка                                                      | Нагрузки с большим объёмом и высокой параллельностью |

Стабильные классические модели `gemini-2.5-pro` (контекстное окно 2M) и `gemini-2.5-flash` по-прежнему доступны. См. [Модели и тарификация](/ru/api-capabilities/model-info) для полной информации о тарификации.

## Методы ввода видео

Именно здесь возникает большинство проблем. Проверьте таблицу ниже, чтобы убедиться, что ваш метод ввода поддерживается:

| Метод ввода                                      | Поддерживается | Примечания                                                                                                                                                                        |
| ------------------------------------------------ | :------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Base64 inline**                                |        ✅       | Считайте локальное видео, закодируйте его в base64 и передайте. **Весь body запроса должен быть ≤ 20 MB.** Работает как в формате, совместимом с OpenAI, так и в нативном формате |
| **Ссылка YouTube**                               |        ✅       | **Только нативный формат Gemini**, передается через `file_uri`                                                                                                                    |
| **Публичный URL видео** (например, адрес `.mp4`) |        ❌       | **Google не принимает его** и возвращает `Request contains an invalid argument` — это не блокировка со стороны APIYI                                                              |
| **Files API** (`files.upload`)                   |        ❌       | Не поддерживается сторонними сервисами; только официальный эндпоинт Google поддерживает это                                                                                       |

<Warning>
  **Ограничение 20 MB**: При использовании Base64 весь body запроса (включая закодированное видео) должен оставаться меньше 20 MB. Для **видео размером более 20 MB** у вас есть только такие варианты: ① использовать ссылку YouTube; ② сжать / обрезать видео локально до менее чем 20 MB перед кодированием в base64.
</Warning>

## Быстрый старт: встроенный Base64 (формат, совместимый с OpenAI)

Самый распространенный подход: прочитайте локальное видео → закодируйте его в base64 → передайте его в поле `image_url`.

```python theme={null}
from openai import OpenAI
import base64

client = OpenAI(
    api_key="YOUR_API_KEY",            # Replace with your APIYI key
    base_url="https://api.apiyi.com/v1"
)

{/* Read the local video and base64-encode it (entire request ≤ 20 MB) */}
with open("demo.mp4", "rb") as f:
    video_b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe the content of this video in detail"},
            {
                "type": "image_url",
                "image_url": {"url": f"data:video/mp4;base64,{video_b64}"},
                "mime_type": "video/mp4",
            },
        ],
    }],
)

print(response.choices[0].message.content)
```

Эквивалентный curl (замените `<BASE64_VIDEO>` на строку base64 видео; для больших файлов лучше позволить SDK выполнить кодирование автоматически):

```bash theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this video"},
        {"type": "image_url",
         "image_url": {"url": "data:video/mp4;base64,<BASE64_VIDEO>"},
         "mime_type": "video/mp4"}
      ]
    }]
  }'
```

## Ссылки YouTube (нативный формат Gemini)

Ссылки YouTube не требуют загрузки и не подпадают под лимит 20 MB, но их можно передавать только через нативный формат Gemini (`google-genai` SDK, эндпоинт `https://api.apiyi.com`).

```python theme={null}
from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options={"base_url": "https://api.apiyi.com"}
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=types.Content(parts=[
        types.Part(file_data=types.FileData(
            file_uri="https://www.youtube.com/watch?v=VIDEO_ID"
        )),
        types.Part(text="Summarize the main content and key points of this video"),
    ]),
)

print(response.text)
```

<Info>
  Для использования нативного формата в других сценариях (потоковая передача, budget рассуждений, вызов функций и т. д.) см. [Нативный формат Gemini](/ru/api-capabilities/gemini/native).
</Info>

## Продвинутые советы

### Ссылка на временную метку

Модель по умолчанию делает выборку с частотой 1 кадр в секунду и понимает аудиодорожку, поэтому вы можете ссылаться на моменты напрямую с помощью `MM:SS` в вашем prompt — это чисто приём составления prompt и работает с любым способом ввода:

```text theme={null}
Describe what happens between 00:30 and 01:15, and identify the on-screen text that appears at 02:40.
```

### Идеи prompt для типовых задач

Один и тот же video поддерживает разные варианты анализа, если просто изменить prompt — никаких изменений кода не требуется:

* **Краткое содержание**: кратко изложите тему, ключевые моменты и вывод в 3–5 предложениях
* **Образовательный анализ**: выделите ключевые concepts, разбивку по главам и важные timestamps
* **Анализ наблюдения**: определите необычное поведение, присутствующих людей/объекты и когда они появляются
* **Маркетинговый обзор**: проанализируйте, как представлены преимущества, темп подачи и соответствие целевой аудитории
* **Анализ действий**: разберите шаги, детали позы и моменты, которые можно улучшить

## Технические примечания

* **Частота выборки**: по умолчанию модель выбирает **1 кадр в секунду (FPS)** и также понимает аудиодорожку.
* **Использование token**: примерно **300 token/секунду** при разрешении по умолчанию, примерно **100 token/секунду** при низком разрешении — более длинные видео расходуют больше token, поэтому оценивайте это соответствующим образом.
* **Поддерживаемые форматы**: mp4, mpeg, mov (quicktime), avi, webm, wmv, 3gpp и другие распространенные форматы.

## FAQ

<AccordionGroup>
  <Accordion title="Публичная ссылка на видео возвращает «Запрос содержит недопустимый аргумент / не удается получить»">
    Понимание видео Google **не принимает произвольные публичные прямые ссылки** (например, `https://example.com/video.mp4`) и возвращает `Request contains an invalid argument`. Это не блокировка со стороны APIYI или Nginx. Используйте либо: ① встроенный Base64 (≤20 MB); либо ② ссылку YouTube (нативный формат).
  </Accordion>

  <Accordion title="Почему лимит 20 MB? Раньше это работало">
    При встроенном Base64 весь тело запроса всегда было ограничено 20 MB (что соответствует официальному лимиту Google). Если то, что «раньше работало», было публичной прямой ссылкой, это никогда не было поддерживаемым способом — просто в некоторых случаях ошибка не возникала; теперь это отклоняется согласно спецификации.
  </Accordion>

  <Accordion title="Могу ли я использовать files.upload для загрузки больших видео?">
    Нет. Официальный Files API Google (`client.files.upload()`) **не поддерживается сторонними сервисами** — его поддерживает только собственный эндпоинт Google. Для больших видео используйте ссылку YouTube или сожмите файл до менее чем 20 MB и используйте Base64.
  </Accordion>

  <Accordion title="Что насчет видео больше 20 MB?">
    Два пути: ① загрузить в YouTube и передать ссылку (нативный формат, на который не распространяется лимит 20 MB); ② использовать инструмент вроде ffmpeg, чтобы локально сжать или обрезать ключевой фрагмент до менее чем 20 MB, а затем закодировать в base64.
  </Accordion>
</AccordionGroup>

## Связанные материалы

<CardGroup cols={2}>
  <Card title="Модели и тарифы" icon="list" href="/ru/api-capabilities/model-info">
    Просмотрите все модели Gemini и актуальные тарифы
  </Card>

  <Card title="Нативный формат Gemini" icon="sparkles" href="/ru/api-capabilities/gemini/native">
    Ссылки YouTube, потоковая передача, бюджет на рассуждение и другие варианты нативного использования
  </Card>

  <Card title="API для понимания изображений" icon="image" href="/ru/api-capabilities/vision-understanding">
    Распознавание содержимого изображений и мультимодальный анализ
  </Card>

  <Card title="Справочник API" icon="book" href="/ru/api-manual">
    Полная спецификация API и сведения об эндпоинтах
  </Card>
</CardGroup>