Ling 3.0 Flash VL accepts text, image, and video inputs through Novita AI’s OpenAI-compatible API. Set https://api.novita.ai/openai as the base URL, use inclusionai/ling-3.0-flash-vl as the model ID, and put an image URL or data URL in a standard chat-completions message. This guide focuses on setup, image requests, video workflows, function calling, reasoning controls, and production checks.
For model positioning, availability, and catalog context, see Ling 3.0 Flash VL on Novita AI: Launch, Capabilities, and Pricing. For a text-only integration, compare this guide with the Ling 3.0 Flash API Quick Start.
What You Need
| Item | Value |
|---|---|
| API key | A Novita AI API key in NOVITA_API_KEY |
| OpenAI-compatible base URL | https://api.novita.ai/openai |
| Chat completions endpoint | POST https://api.novita.ai/openai/v1/chat/completions |
| Model ID | inclusionai/ling-3.0-flash-vl |
The Novita AI LLM guide documents the OpenAI-compatible client setup. The vision-language guide documents the content array format, image_url entries, image detail, and base64 data URLs. The model page checked on September 9, 2026 lists text, image, and video input, text output, function calling, reasoning, a 256K context window, and a 32K maximum output.
Export the key in your shell rather than placing it in source code:
export NOVITA_API_KEY="your_api_key"Python Image Request
The OpenAI Python SDK accepts an array for the user message’s content. Put the visual input first, then add the instruction as a separate text item.
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 can be low, high, or auto. Use high for small text and fine visual details; start with low or auto when latency matters. Image input is tokenized and counted with text, so measure cost and quality on representative images.
cURL Image Request
The same payload works from a shell script. --fail-with-body keeps HTTP failures visible while returning a nonzero exit status.
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
}'For a private local image, substitute a data URL such as data:image/jpeg;base64,<base64_image_bytes> for the remote URL. Keep the MIME type aligned with the encoded file, and do not log request bodies containing private images.
Handling Video Inputs
The current Ling 3.0 Flash VL model listing includes video among its input modalities. The public Novita vision guide documents the portable OpenAI-compatible image payload above, but does not define a separate generic video_url message schema. Do not invent one in a production client.
For a portable video-understanding workflow, extract representative frames, send them as multiple image_url items, and include timestamps in the prompt. The vision guide recommends no more than two images per request, so sample short windows or make multiple calls:
ffmpeg -ss 00:00:05 -i input.mp4 -vf "fps=1/5,scale=1280:-2" -frames:v 2 frame-%02d.jpgThe resulting frames can be sent by repeating the image item in the Python or cURL payload. If the current API reference for your account exposes a native video-content shape, follow that reference and validate it with a small clip first. The model listing confirms video capability; the transport format must be checked against the live API documentation for your integration.
Function Calling with Visual Context
Function calling is useful when the model should turn what it sees into an application action. Keep the tool narrow and validate its arguments in application code.
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)Treat tool arguments as untrusted model output. Validate the JSON, check permissions, and execute the function outside the model. A visual observation should not directly trigger an irreversible action without the checks your workflow requires.
Reasoning Controls
Novita’s OpenAI-compatible chat completions API includes enable_thinking and separate_reasoning fields, and the Ling 3.0 Flash VL listing includes reasoning support. Test these fields with a small request before adding them to a production wrapper:
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)Reasoning output may change response parsing and latency. If your application only needs a caption or tool call, leave these fields off and compare quality with the simpler request first.
Integration Checklist
Before moving beyond a smoke test:
- Confirm the exact model ID and endpoint rather than using the display name.
- Test a public image URL, then a base64 data URL, and validate private-image handling separately.
- Keep
max_tokensbounded and log usage and latency without retaining unnecessary image content. - Test image detail settings on small text, charts, and ordinary photographs.
- Validate tool arguments before execution and handle a response with no tool call.
- For video workflows, define frame sampling, timestamp tracking, and the native video payload supported by the live API reference.
- Recheck model availability, pricing, and limits before production; catalog values can change.
FAQ
What model ID should I use?
Use inclusionai/ling-3.0-flash-vl. Ling 3.0 Flash VL is the display name, not the request value.
Which endpoint does this guide use?
Use https://api.novita.ai/openai as the SDK base URL, or send cURL requests to https://api.novita.ai/openai/v1/chat/completions.
How do I send an image?
Add a content array to the user message with an image_url item and a text item. The image URL can point to a reachable image or use a base64 data URL.
Does the model accept video?
The Novita model listing checked on September 9, 2026 lists video as an input modality. The public vision guide does not document a generic direct-video message shape, so confirm the live API reference before sending a native video payload. A frame-sampling workflow is the portable fallback.
Does it support function calling and reasoning?
The current Novita listing includes both features. The examples above show tools, enable_thinking, and separate_reasoning; test their response shape and latency with your own workload.
