Ling 3.0 Flash VL acepta entradas de texto, imagen y video a través de la API compatible con OpenAI de Novita AI. Establece https://api.novita.ai/openai como URL base, usa inclusionai/ling-3.0-flash-vl como ID del modelo e incluye una URL de imagen o una URL de datos en un mensaje estándar de completaciones de chat. Esta guía se centra en la configuración, solicitudes de imagen, flujos de trabajo de video, llamadas a funciones, controles de razonamiento y comprobaciones de producción.
Para conocer el posicionamiento del modelo, la disponibilidad y el contexto del catálogo, consulta Ling 3.0 Flash VL en Novita AI: Lanzamiento, capacidades y precios. Para una integración solo de texto, compara esta guía con el Inicio rápido de la API de Ling 3.0 Flash.
Lo que necesitas
| Elemento | Valor |
|---|---|
| Clave API | Una clave API de Novita AI en NOVITA_API_KEY |
| URL base compatible con OpenAI | https://api.novita.ai/openai |
| Endpoint de completaciones de chat | POST https://api.novita.ai/openai/v1/chat/completions |
| ID del modelo | inclusionai/ling-3.0-flash-vl |
La guía de LLM de Novita AI documenta la configuración del cliente compatible con OpenAI. La guía de lenguaje visual documenta el formato del array content, las entradas image_url, el detalle de la imagen y las URL de datos en base64. La página del modelo consultada el 9 de septiembre de 2026 enumera entrada de texto, imagen y video, salida de texto, llamadas a funciones, razonamiento, una ventana de contexto de 256K y una salida máxima de 32K.
Exporta la clave en tu terminal en lugar de colocarla en el código fuente:
export NOVITA_API_KEY="tu_clave_api"
Solicitud de imagen en Python
El SDK de OpenAI para Python acepta un array para el content del mensaje del usuario. Coloca la entrada visual primero, luego añade la instrucción como un elemento de texto separado.
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": "Extrae el comerciante, la fecha y el total. Si algún campo no es legible, indícalo.",
},
],
}
],
max_tokens=256,
temperature=0.2,
)
print(response.choices[0].message.content)
detail puede ser low, high o auto. Usa high para texto pequeño y detalles visuales finos; comienza con low o auto cuando la latencia importe. La entrada de imagen se tokeniza y cuenta junto con el texto, por lo que debes medir el costo y la calidad en imágenes representativas.
Solicitud de imagen con cURL
El mismo payload funciona desde un script de shell. --fail-with-body mantiene los fallos HTTP visibles mientras devuelve un código de salida distinto de cero.
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 los componentes principales y sus conexiones."
}
]
}
],
"max_tokens": 512,
"temperature": 0.2
}'
Para una imagen local privada, sustituye la URL remota por una URL de datos como `data:image/jpeg;base64,<base64_image_bytes>>. Mantén el tipo MIME alineado con el archivo codificado y no registres los cuerpos de las solicitudes que contengan imágenes privadas.
Manejo de entradas de video
El listado actual del modelo Ling 3.0 Flash VL incluye video entre sus modalidades de entrada. La guía pública de visión de Novita documenta el payload de imagen portátil compatible con OpenAI descrito anteriormente, pero no define un esquema de mensaje video_url genérico separado. No inventes uno en un cliente de producción.
Para un flujo de trabajo de comprensión de video portátil, extrae fotogramas representativos, envíalos como múltiples elementos image_url e incluye marcas de tiempo en el prompt. La guía de visión recomienda no más de dos imágenes por solicitud, por lo que debes muestrear ventanas cortas o hacer múltiples llamadas:
ffmpeg -ss 00:00:05 -i input.mp4 -vf "fps=1/5,scale=1280:-2" -frames:v 2 frame-%02d.jpg
Los fotogramas resultantes se pueden enviar repitiendo el elemento de imagen en el payload de Python o cURL. Si la referencia actual de la API para tu cuenta expone una forma de contenido de video nativa, sigue esa referencia y valídala primero con un clip pequeño. El listado del modelo confirma la capacidad de video; el formato de transporte debe verificarse con la documentación de la API en vivo para tu integración.
Llamadas a funciones con contexto visual
Las llamadas a funciones son útiles cuando el modelo debe convertir lo que ve en una acción de la aplicación. Mantén la herramienta específica y valida sus argumentos en el código de la aplicación.
tools = [
{
"type": "function",
"function": {
"name": "flag_document",
"description": "Envía un documento para verificación manual.",
"parameters": {
"type": "object",
"properties": {
"reason": {"type": "string", "description": "Por qué se necesita revisión."},
"page_or_frame": {"type": "string", "description": "Página o marca de tiempo del video."},
},
"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": "Marca este documento si los campos clave no están claros."},
],
}
],
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)
Trata los argumentos de las herramientas como salida del modelo no confiable. Valida el JSON, verifica los permisos y ejecuta la función fuera del modelo. Una observación visual no debería desencadenar directamente una acción irreversible sin las comprobaciones que tu flujo de trabajo requiera.
Controles de razonamiento
La API de completaciones de chat compatible con OpenAI de Novita incluye los campos enable_thinking y separate_reasoning, y el listado de Ling 3.0 Flash VL incluye soporte de razonamiento. Prueba estos campos con una solicitud pequeña antes de agregarlos a un envoltorio de producción:
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": "Compara las dos tendencias e indica cuál necesita investigación."},
],
}
],
enable_thinking=True,
separate_reasoning=True,
max_tokens=512,
temperature=0.2,
)
print(response.choices[0].message)
La salida del razonamiento puede cambiar el análisis de la respuesta y la latencia. Si tu aplicación solo necesita un subtítulo o una llamada a función, omite estos campos y compara primero la calidad con la solicitud más simple.
Lista de verificación de integración
Antes de pasar de una prueba de humo:
- Confirma el ID exacto del modelo y el endpoint, no uses el nombre mostrado.
- Prueba una URL de imagen pública, luego una URL de datos en base64, y valida el manejo de imágenes privadas por separado.
- Mantén
max_tokensacotado y registra el uso y la latencia sin retener contenido de imagen innecesario. - Prueba las configuraciones de detalle de imagen en texto pequeño, gráficos y fotografías comunes.
- Valida los argumentos de las herramientas antes de la ejecución y maneja una respuesta sin llamada a función.
- Para flujos de trabajo de video, define el muestreo de fotogramas, el seguimiento de marcas de tiempo y el payload de video nativo compatible con la referencia de API en vivo.
- Vuelve a verificar la disponibilidad del modelo, los precios y los límites antes de producción; los valores del catálogo pueden cambiar.
Preguntas frecuentes
¿Qué ID de modelo debo usar?
Usa inclusionai/ling-3.0-flash-vl. Ling 3.0 Flash VL es el nombre mostrado, no el valor de la solicitud.
¿Qué endpoint utiliza esta guía?
Usa https://api.novita.ai/openai como URL base del SDK, o envía solicitudes cURL a https://api.novita.ai/openai/v1/chat/completions.
¿Cómo envío una imagen?
Agrega un array content al mensaje del usuario con un elemento image_url y un elemento text. La URL de la imagen puede apuntar a una imagen accesible o usar una URL de datos en base64.
¿El modelo acepta video?
El listado del modelo de Novita consultado el 9 de septiembre de 2026 enumera video como una modalidad de entrada. La guía pública de visión no documenta una forma de mensaje de video directo genérico, por lo que debes confirmar la referencia de API en vivo antes de enviar un payload de video nativo. Un flujo de trabajo de muestreo de fotogramas es la alternativa portátil.
¿Soporta llamadas a funciones y razonamiento?
El listado actual de Novita incluye ambas características. Los ejemplos anteriores muestran tools, enable_thinking y separate_reasoning; prueba su forma de respuesta y latencia con tu propia carga de trabajo.
