Ling 3.0 Flash VL принимает на вход текст, изображения и видео через OpenAI-совместимый API Novita AI. Укажите https://api.novita.ai/openai как базовый URL, используйте inclusionai/ling-3.0-flash-vl как идентификатор модели и поместите URL изображения или data URL в стандартное сообщение chat completions. В этом руководстве рассматриваются настройка, запросы с изображениями, процессы работы с видео, вызов функций, управление рассуждениями и проверки для продакшена.
Для информации о позиционировании модели, доступности и каталоге см. Ling 3.0 Flash VL в Novita AI: запуск, возможности и цены. Для интеграции только с текстом сравните это руководство с быстрым стартом API Ling 3.0 Flash.
Что вам понадобится
| Параметр | Значение |
|---|---|
| API-ключ | Ключ API Novita AI в переменной NOVITA_API_KEY |
| OpenAI-совместимый базовый URL | https://api.novita.ai/openai |
| Эндпоинт chat completions | POST https://api.novita.ai/openai/v1/chat/completions |
| Идентификатор модели | inclusionai/ling-3.0-flash-vl |
В руководстве Novita AI по LLM описана настройка OpenAI-совместимого клиента. В руководстве по vision-language описан формат массива content, элементы image_url, детализация изображения и data URL в base64. На странице модели по состоянию на 9 сентября 2026 года указаны поддержка ввода текста, изображений и видео, вывод текста, вызов функций, рассуждения, контекстное окно 256K и максимальный размер вывода 32K.
Экспортируйте ключ в вашей оболочке, а не указывайте его в исходном коде:
export NOVITA_API_KEY="your_api_key"
Запрос изображения на Python
OpenAI Python SDK принимает массив в качестве content сообщения пользователя. Сначала поместите визуальный ввод, затем добавьте инструкцию отдельным текстовым элементом.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
response = client.chat.completions.create(
model="inclusionai/ling-3.0-flash-vl",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/receipt.jpg",
"detail": "high",
},
},
{
"type": "text",
"text": "Extract the merchant, date, and total. If a field is not legible, say so.",
},
],
}
],
max_tokens=256,
temperature=0.2,
)
print(response.choices[0].message.content)
Параметр detail может быть low, high или auto. Используйте high для мелкого текста и тонких визуальных деталей; начинайте с low или auto, если важна задержка. Изображения токенизируются и учитываются вместе с текстом, поэтому оценивайте стоимость и качество на репрезентативных изображениях.
Запрос изображения через cURL
Тот же запрос работает из shell-скрипта. Флаг --fail-with-body оставляет HTTP-ошибки видимыми и возвращает ненулевой код завершения.
curl --fail-with-body "https://api.novita.ai/openai/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${NOVITA_API_KEY}" \
-d '{
"model": "inclusionai/ling-3.0-flash-vl",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/diagram.png",
"detail": "auto"
}
},
{
"type": "text",
"text": "Describe the main components and their connections."
}
]
}
],
"max_tokens": 512,
"temperature": 0.2
}'
Для частного локального изображения подставьте вместо удаленного URL data URL вида data:image/jpeg;base64,<base64_image_bytes>. Следите, чтобы MIME-тип соответствовал закодированному файлу, и не логируйте тела запросов, содержащие приватные изображения.
Работа с видеовходом
Текущая страница модели Ling 3.0 Flash VL включает видео среди поддерживаемых типов ввода. В публичном руководстве Novita по vision описан переносимый OpenAI-совместимый запрос с изображением, приведенный выше, но не определена отдельная универсальная схема сообщения video_url. Не придумывайте её в продакшен-клиенте.
Для переносимого процесса анализа видео извлекайте характерные кадры, отправляйте их как несколько элементов image_url и добавляйте временные метки в запрос. Руководство по vision рекомендует не более двух изображений на запрос, поэтому выбирайте короткие окна или делайте несколько запросов:
ffmpeg -ss 00:00:05 -i input.mp4 -vf "fps=1/5,scale=1280:-2" -frames:v 2 frame-%02d.jpg
Полученные кадры можно отправить, повторив элемент изображения в Python- или cURL-запросе. Если в текущей API-справке для вашего аккаунта указан нативный формат видеоконтента, следуйте этой справке и сначала проверьте его на коротком клипе. Страница модели подтверждает поддержку видео; формат передачи необходимо сверять с актуальной документацией API для вашей интеграции.
Вызов функций с визуальным контекстом
Вызов функций полезен, когда модель должна превратить увиденное в действие приложения. Держите инструмент узкоспециализированным и проверяйте его аргументы в коде приложения.
tools = [
{
"type": "function",
"function": {
"name": "flag_document",
"description": "Send a document for manual verification.",
"parameters": {
"type": "object",
"properties": {
"reason": {"type": "string", "description": "Why review is needed."},
"page_or_frame": {"type": "string", "description": "Page or video timestamp."},
},
"required": ["reason"],
},
},
}
]
response = client.chat.completions.create(
model="inclusionai/ling-3.0-flash-vl",
messages=[
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/document.jpg"}},
{"type": "text", "text": "Flag this document if key fields are unclear."},
],
}
],
tools=tools,
tool_choice="auto",
max_tokens=256,
temperature=0.1,
)
message = response.choices[0].message
if message.tool_calls:
for call in message.tool_calls:
print(call.function.name, call.function.arguments)
else:
print(message.content)
Относитесь к аргументам инструмента как к недоверенному выводу модели. Проверяйте JSON, контролируйте права доступа и выполняйте функцию вне модели. Визуальное наблюдение не должно напрямую запускать необратимое действие без проверок, предусмотренных вашим процессом.
Управление рассуждениями
OpenAI-совместимый API chat completions Novita включает поля enable_thinking и separate_reasoning, а в описании Ling 3.0 Flash VL указана поддержка рассуждений. Протестируйте эти поля на небольшом запросе, прежде чем добавлять их в продакшен-обёртку:
response = client.chat.completions.create(
model="inclusionai/ling-3.0-flash-vl",
messages=[
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}},
{"type": "text", "text": "Compare the two trends and state which one needs investigation."},
],
}
],
enable_thinking=True,
separate_reasoning=True,
max_tokens=512,
temperature=0.2,
)
print(response.choices[0].message)
Вывод рассуждений может изменить разбор ответа и задержку. Если вашему приложению нужна только подпись или вызов инструмента, не включайте эти поля и сначала сравните качество с более простым запросом.
Чек-лист интеграции
Прежде чем выходить за пределы смоук-теста:
- Проверьте точный идентификатор модели и эндпоинт, а не используйте отображаемое имя.
- Протестируйте публичный URL изображения, затем data URL в base64 и отдельно проверьте обработку приватных изображений.
- Ограничивайте
max_tokens, логируйте использование и задержку, не сохраняя лишние изображения. - Проверьте настройки детализации изображений на мелком тексте, графиках и обычных фотографиях.
- Проверяйте аргументы инструмента перед выполнением и обрабатывайте ответ без вызова инструмента.
- Для видеозадач определите выборку кадров, отслеживание временных меток и нативный видео-пейлоад, поддерживаемый актуальной API-справкой.
- Перед продакшеном повторно проверьте доступность модели, цены и лимиты; значения в каталоге могут меняться.
FAQ
Какой идентификатор модели использовать?
Используйте inclusionai/ling-3.0-flash-vl. Ling 3.0 Flash VL — это отображаемое имя, а не значение запроса.
Какой эндпоинт используется в этом руководстве?
Используйте https://api.novita.ai/openai как базовый URL SDK или отправляйте cURL-запросы на https://api.novita.ai/openai/v1/chat/completions.
Как отправить изображение?
Добавьте массив content в сообщение пользователя с элементом image_url и элементом text. URL изображения может указывать на доступное изображение или использовать data URL в base64.
Принимает ли модель видео?
В описании модели Novita, проверенном 9 сентября 2026 года, видео указано как поддерживаемый тип ввода. В публичном руководстве по vision нет универсальной схемы сообщения для прямой отправки видео, поэтому перед отправкой нативного видео-пейлоада проверьте актуальную API-справку. Переносимый запасной вариант — процесс с выборкой кадров.
Поддерживает ли модель вызов функций и рассуждения?
В текущем описании Novita указаны обе функции. Примеры выше показывают tools, enable_thinking и separate_reasoning; протестируйте формат ответа и задержку на своей нагрузке.
